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