src/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   JwkWriter(const std::string& algorithm,
 112             bool extractable,
 113             blink::WebCryptoKeyUsageMask usages,
 114             const std::string& kty);
 115
 116   // Sets a string member |member_name| to |value|.
 117   void SetString(const std::string& member_name, const std::string& value);
 118
 119   // Sets a bytes member |value| to |value| by base64 url-safe encoding it.
 120   void SetBytes(const std::string& member_name, const CryptoData& value);
 121
 122   // Flattens the JWK to JSON (UTF-8 encoded if necessary, however in practice
 123   // it will be ASCII).
 124   void ToJson(std::vector<uint8_t>* utf8_bytes) const;
 125
 126  private:
 127   base::DictionaryValue dict_;
 128 };
 129
 130 // Writes a JWK-formatted symmetric key to |jwk_key_data|.
 131 //  * raw_key_data: The actual key data
 132 //  * algorithm: The JWK algorithm name (i.e. "alg")
 133 //  * extractable: The JWK extractability (i.e. "ext")
 134 //  * usages: The JWK usages (i.e. "key_ops")
 135 void WriteSecretKeyJwk(const CryptoData& raw_key_data,
 136                        const std::string& algorithm,
 137                        bool extractable,
 138                        blink::WebCryptoKeyUsageMask usages,
 139                        std::vector<uint8_t>* jwk_key_data);
 140
 141 // Parses a UTF-8 encoded JWK (key_data), and extracts the key material to
 142 // |*raw_key_data|. Returns Status::Success() on success, otherwise an error.
 143 // In order for this to succeed:
 144 //   * expected_alg must match the JWK's "alg", if present.
 145 //   * expected_extractable must be consistent with the JWK's "ext", if
 146 //     present.
 147 //   * expected_usages must be a subset of the JWK's "key_ops" if present.
 148 Status ReadSecretKeyJwk(const CryptoData& key_data,
 149                         const std::string& expected_alg,
 150                         bool expected_extractable,
 151                         blink::WebCryptoKeyUsageMask expected_usages,
 152                         std::vector<uint8_t>* raw_key_data);
 153
 154 // Creates an AES algorithm name for the given key size (in bytes). For
 155 // instance "A128CBC" is the result of suffix="CBC", keylen_bytes=16.
 156 std::string MakeJwkAesAlgorithmName(const std::string& suffix,
 157                                     unsigned int keylen_bytes);
 158
 159 // This is very similar to ReadSecretKeyJwk(), except instead of specifying an
 160 // absolute "expected_alg", the suffix for an AES algorithm name is given
 161 // (See MakeJwkAesAlgorithmName() for an explanation of what the suffix is).
 162 //
 163 // This is because the algorithm name for AES keys is dependent on the length
 164 // of the key. This function expects key lengths to be either 128, 192, or 256
 165 // bits.
 166 Status ReadAesSecretKeyJwk(const CryptoData& key_data,
 167                            const std::string& algorithm_name_suffix,
 168                            bool expected_extractable,
 169                            blink::WebCryptoKeyUsageMask expected_usages,
 170                            std::vector<uint8_t>* raw_key_data);
 171
 172 // Writes a JWK-formated RSA public key and saves the result to
 173 // |*jwk_key_data|.
 174 void WriteRsaPublicKeyJwk(const CryptoData& n,
 175                           const CryptoData& e,
 176                           const std::string& algorithm,
 177                           bool extractable,
 178                           blink::WebCryptoKeyUsageMask usages,
 179                           std::vector<uint8_t>* jwk_key_data);
 180
 181 // Writes a JWK-formated RSA private key and saves the result to
 182 // |*jwk_key_data|.
 183 void WriteRsaPrivateKeyJwk(const CryptoData& n,
 184                            const CryptoData& e,
 185                            const CryptoData& d,
 186                            const CryptoData& p,
 187                            const CryptoData& q,
 188                            const CryptoData& dp,
 189                            const CryptoData& dq,
 190                            const CryptoData& qi,
 191                            const std::string& algorithm,
 192                            bool extractable,
 193                            blink::WebCryptoKeyUsageMask usages,
 194                            std::vector<uint8_t>* jwk_key_data);
 195
 196 // Describes the RSA components for a parsed key. The names of the properties
 197 // correspond with those from the JWK spec. Note that Chromium's WebCrypto
 198 // implementation does not support multi-primes, so there is no parsed field
 199 // for othinfo.
 200 struct JwkRsaInfo {
 201   JwkRsaInfo();
 202   ~JwkRsaInfo();
 203
 204   bool is_private_key;
 205   std::string n;
 206   std::string e;
 207   std::string d;
 208   std::string p;
 209   std::string q;
 210   std::string dp;
 211   std::string dq;
 212   std::string qi;
 213 };
 214
 215 // Parses a UTF-8 encoded JWK (key_data), and extracts the RSA components to
 216 // |*result|. Returns Status::Success() on success, otherwise an error.
 217 // In order for this to succeed:
 218 //   * expected_alg must match the JWK's "alg", if present.
 219 //   * expected_extractable must be consistent with the JWK's "ext", if
 220 //     present.
 221 //   * expected_usages must be a subset of the JWK's "key_ops" if present.
 222 Status ReadRsaKeyJwk(const CryptoData& key_data,
 223                      const std::string& expected_alg,
 224                      bool expected_extractable,
 225                      blink::WebCryptoKeyUsageMask expected_usages,
 226                      JwkRsaInfo* result);
 227
 228 const char* GetJwkHmacAlgorithmName(blink::WebCryptoAlgorithmId hash);
 229
 230 // This function decodes unpadded 'base64url' encoded data, as described in
 231 // RFC4648 (http://www.ietf.org/rfc/rfc4648.txt) Section 5.
 232 CONTENT_EXPORT bool Base64DecodeUrlSafe(const std::string& input,
 233                                         std::string* output);
 234
 235 // Returns an unpadded 'base64url' encoding of the input data, the opposite of
 236 // Base64DecodeUrlSafe() above.
 237 CONTENT_EXPORT std::string Base64EncodeUrlSafe(const base::StringPiece& input);
 238 CONTENT_EXPORT std::string Base64EncodeUrlSafe(
 239     const std::vector<uint8_t>& input);
 240
 241 }  // namespace webcrypto
 242
 243 }  // namespace content
 244
 245 #endif  // CONTENT_CHILD_WEBCRYPTO_JWK_H_