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 // This decodes JWK's flavor of base64 encoding, as described by:
 130 // https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-36#section-2
 131 //
 132 // In essence it is RFC 4648 'base64url' encoding where padding is omitted.
 133 bool Base64DecodeUrlSafe(const std::string& input, std::string* output);
 134
 135 // Encodes |input| using JWK's flavor of base64 encoding. See the description
 136 // above for details.
 137 std::string Base64EncodeUrlSafe(const base::StringPiece& input);
 138 std::string Base64EncodeUrlSafe(const std::vector<uint8_t>& input);
 139
 140 // Converts a JWK "key_ops" array to the corresponding WebCrypto usages. Used by
 141 // testing.
 142 Status GetWebCryptoUsagesFromJwkKeyOpsForTest(
 143     const base::ListValue* key_ops,
 144     blink::WebCryptoKeyUsageMask* usages);
 145
 146 }  // namespace webcrypto
 147
 148 #endif  // COMPONENTS_WEBCRYPTO_JWK_H_