components/webcrypto/jwk.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_WEBCRYPTO_JWK_H_
   6 #define COMPONENTS_WEBCRYPTO_JWK_H_
   7
   8 #include <stdint.h>
   9 #include <vector>
  10
  11 #include "base/strings/string_piece.h"
  12 #include "base/values.h"
  13 #include "third_party/WebKit/public/platform/WebCrypto.h"
  14
  15 namespace webcrypto {
  16
  17 class CryptoData;
  18 class Status;
  19
  20 // Helper class for parsing a JWK from JSON.
  21 //
  22 // This primarily exists to ensure strict enforcement of the JWK schema, as the
  23 // type and presence of particular members is security relevant. For example,
  24 // GetString() will ensure a given JSON member is present and is a string type,
  25 // and will fail if these conditions aren't met.
  26 //
  27 // Users of JwkReader must call Init() successfully before any other method can
  28 // be called.
  29 class JwkReader {
  30  public:
  31   JwkReader();
  32   ~JwkReader();
  33
  34   // Initializes a JWK reader by parsing the JSON |bytes|. To succeed, the JWK
  35   // must:
  36   //   * Have "kty" matching |expected_kty|
  37   //   * Have "ext" compatible with |expected_extractable|
  38   //   * Have usages ("use", "key_ops") compatible with |expected_usages|
  39   //   * Have an "alg" matching |expected_alg|
  40   //
  41   // NOTE: If |expected_alg| is empty, then the test on "alg" is skipped.
  42   Status Init(const CryptoData& bytes,
  43               bool expected_extractable,
  44               blink::WebCryptoKeyUsageMask expected_usages,
  45               const std::string& expected_kty,
  46               const std::string& expected_alg);
  47
  48   // Returns true if the member |member_name| is present.
  49   bool HasMember(const std::string& member_name) const;
  50
  51   // Extracts the required string member |member_name| and saves the result to
  52   // |*result|. If the member does not exist or is not a string, returns an
  53   // error.
  54   Status GetString(const std::string& member_name, std::string* result) const;
  55
  56   // Extracts the optional string member |member_name| and saves the result to
  57   // |*result| if it was found. If the member exists and is not a string,
  58   // returns an error. Otherwise returns success, and sets |*member_exists| if
  59   // it was found.
  60   Status GetOptionalString(const std::string& member_name,
  61                            std::string* result,
  62                            bool* member_exists) const;
  63
  64   // Extracts the optional array member |member_name| and saves the result to
  65   // |*result| if it was found. If the member exists and is not an array,
  66   // returns an error. Otherwise returns success, and sets |*member_exists| if
  67   // it was found.
  68   //
  69   // NOTE: |*result| is owned by the JwkReader.
  70   Status GetOptionalList(const std::string& member_name,
  71                          base::ListValue** result,
  72                          bool* member_exists) const;
  73
  74   // Extracts the required string member |member_name| and saves the
  75   // base64url-decoded bytes to |*result|. If the member does not exist or is
  76   // not a string, or could not be base64url-decoded, returns an error.
  77   Status GetBytes(const std::string& member_name, std::string* result) const;
  78
  79   // Extracts the required base64url member, which is interpreted as being a
  80   // big-endian unsigned integer.
  81   //
  82   // Sequences that contain leading zeros will be rejected.
  83   Status GetBigInteger(const std::string& member_name,
  84                        std::string* result) const;
  85
  86   // Extracts the optional boolean member |member_name| and saves the result to
  87   // |*result| if it was found. If the member exists and is not a boolean,
  88   // returns an error. Otherwise returns success, and sets |*member_exists| if
  89   // it was found.
  90   Status GetOptionalBool(const std::string& member_name,
  91                          bool* result,
  92                          bool* member_exists) const;
  93
  94   // Gets the optional algorithm ("alg") string.
  95   Status GetAlg(std::string* alg, bool* has_alg) const;
  96
  97   // Checks if the "alg" member matches |expected_alg|.
  98   Status VerifyAlg(const std::string& expected_alg) const;
  99
 100  private:
 101   scoped_ptr<base::DictionaryValue> dict_;
 102 };
 103
 104 // Helper class for building the JSON for a JWK.
 105 class JwkWriter {
 106  public:
 107   // Initializes a writer, and sets the standard JWK members as indicated.
 108   // |algorithm| is optional, and is only written if the provided |algorithm| is
 109   // non-empty.
 110   JwkWriter(const std::string& algorithm,
 111             bool extractable,
 112             blink::WebCryptoKeyUsageMask usages,
 113             const std::string& kty);
 114
 115   // Sets a string member |member_name| to |value|.
 116   void SetString(const std::string& member_name, const std::string& value);
 117
 118   // Sets a bytes member |value| to |value| by base64 url-safe encoding it.
 119   void SetBytes(const std::string& member_name, const CryptoData& value);
 120
 121   // Flattens the JWK to JSON (UTF-8 encoded if necessary, however in practice
 122   // it will be ASCII).
 123   void ToJson(std::vector<uint8_t>* utf8_bytes) const;
 124
 125  private:
 126   base::DictionaryValue dict_;
 127 };
 128
 129 // Writes a JWK-formatted symmetric key to |jwk_key_data|.
 130 //  * raw_key_data: The actual key data
 131 //  * algorithm: The JWK algorithm name (i.e. "alg")
 132 //  * extractable: The JWK extractability (i.e. "ext")
 133 //  * usages: The JWK usages (i.e. "key_ops")
 134 void WriteSecretKeyJwk(const CryptoData& raw_key_data,
 135                        const std::string& algorithm,
 136                        bool extractable,
 137                        blink::WebCryptoKeyUsageMask usages,
 138                        std::vector<uint8_t>* jwk_key_data);
 139
 140 // Parses a UTF-8 encoded JWK (key_data), and extracts the key material to
 141 // |*raw_key_data|. Returns Status::Success() on success, otherwise an error.
 142 // In order for this to succeed:
 143 //   * expected_alg must match the JWK's "alg", if present.
 144 //   * expected_extractable must be consistent with the JWK's "ext", if
 145 //     present.
 146 //   * expected_usages must be a subset of the JWK's "key_ops" if present.
 147 Status ReadSecretKeyJwk(const CryptoData& key_data,
 148                         const std::string& expected_alg,
 149                         bool expected_extractable,
 150                         blink::WebCryptoKeyUsageMask expected_usages,
 151                         std::vector<uint8_t>* raw_key_data);
 152
 153 // Creates an AES algorithm name for the given key size (in bytes). For
 154 // instance "A128CBC" is the result of suffix="CBC", keylen_bytes=16.
 155 std::string MakeJwkAesAlgorithmName(const std::string& suffix,
 156                                     size_t keylen_bytes);
 157
 158 // This is very similar to ReadSecretKeyJwk(), except instead of specifying an
 159 // absolute "expected_alg", the suffix for an AES algorithm name is given
 160 // (See MakeJwkAesAlgorithmName() for an explanation of what the suffix is).
 161 //
 162 // This is because the algorithm name for AES keys is dependent on the length
 163 // of the key. This function expects key lengths to be either 128, 192, or 256
 164 // bits.
 165 Status ReadAesSecretKeyJwk(const CryptoData& key_data,
 166                            const std::string& algorithm_name_suffix,
 167                            bool expected_extractable,
 168                            blink::WebCryptoKeyUsageMask expected_usages,
 169                            std::vector<uint8_t>* raw_key_data);
 170
 171 // Writes a JWK-formated RSA public key and saves the result to
 172 // |*jwk_key_data|.
 173 void WriteRsaPublicKeyJwk(const CryptoData& n,
 174                           const CryptoData& e,
 175                           const std::string& algorithm,
 176                           bool extractable,
 177                           blink::WebCryptoKeyUsageMask usages,
 178                           std::vector<uint8_t>* jwk_key_data);
 179
 180 // Writes a JWK-formated RSA private key and saves the result to
 181 // |*jwk_key_data|.
 182 void WriteRsaPrivateKeyJwk(const CryptoData& n,
 183                            const CryptoData& e,
 184                            const CryptoData& d,
 185                            const CryptoData& p,
 186                            const CryptoData& q,
 187                            const CryptoData& dp,
 188                            const CryptoData& dq,
 189                            const CryptoData& qi,
 190                            const std::string& algorithm,
 191                            bool extractable,
 192                            blink::WebCryptoKeyUsageMask usages,
 193                            std::vector<uint8_t>* jwk_key_data);
 194
 195 // Describes the RSA components for a parsed key. The names of the properties
 196 // correspond with those from the JWK spec. Note that Chromium's WebCrypto
 197 // implementation does not support multi-primes, so there is no parsed field
 198 // for othinfo.
 199 struct JwkRsaInfo {
 200   JwkRsaInfo();
 201   ~JwkRsaInfo();
 202
 203   bool is_private_key;
 204   std::string n;
 205   std::string e;
 206   std::string d;
 207   std::string p;
 208   std::string q;
 209   std::string dp;
 210   std::string dq;
 211   std::string qi;
 212 };
 213
 214 // Parses a UTF-8 encoded JWK (key_data), and extracts the RSA components to
 215 // |*result|. Returns Status::Success() on success, otherwise an error.
 216 // In order for this to succeed:
 217 //   * expected_alg must match the JWK's "alg", if present.
 218 //   * expected_extractable must be consistent with the JWK's "ext", if
 219 //     present.
 220 //   * expected_usages must be a subset of the JWK's "key_ops" if present.
 221 Status ReadRsaKeyJwk(const CryptoData& key_data,
 222                      const std::string& expected_alg,
 223                      bool expected_extractable,
 224                      blink::WebCryptoKeyUsageMask expected_usages,
 225                      JwkRsaInfo* result);
 226
 227 const char* GetJwkHmacAlgorithmName(blink::WebCryptoAlgorithmId hash);
 228
 229 // This decodes JWK's flavor of base64 encoding, as described by:
 230 // https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-36#section-2
 231 //
 232 // In essence it is RFC 4648 'base64url' encoding where padding is omitted.
 233 bool Base64DecodeUrlSafe(const std::string& input, std::string* output);
 234
 235 // Encodes |input| using JWK's flavor of base64 encoding. See the description
 236 // above for details.
 237 std::string Base64EncodeUrlSafe(const base::StringPiece& input);
 238 std::string Base64EncodeUrlSafe(const std::vector<uint8_t>& input);
 239
 240 // Converts a JWK "key_ops" array to the corresponding WebCrypto usages. Used by
 241 // testing.
 242 Status GetWebCryptoUsagesFromJwkKeyOpsForTest(
 243     const base::ListValue* key_ops,
 244     blink::WebCryptoKeyUsageMask* usages);
 245
 246 }  // namespace webcrypto
 247
 248 #endif  // COMPONENTS_WEBCRYPTO_JWK_H_