components/webcrypto/algorithm_implementation.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_ALGORITHM_IMPLEMENTATION_H_
   6 #define COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_
   7
   8 #include <stdint.h>
   9 #include <vector>
  10
  11 #include "base/memory/scoped_ptr.h"
  12 #include "third_party/WebKit/public/platform/WebCrypto.h"
  13
  14 namespace webcrypto {
  15
  16 class CryptoData;
  17 class GenerateKeyResult;
  18 class Status;
  19
  20 // AlgorithmImplementation is a base class for *executing* the operations of an
  21 // algorithm (generating keys, encrypting, signing, etc.).
  22 //
  23 // This is in contrast to blink::WebCryptoAlgorithm which instead *describes*
  24 // the operation and its parameters.
  25 //
  26 // AlgorithmImplementation has reasonable default implementations for all
  27 // methods which behave as if the operation is it is unsupported, so
  28 // implementations need only override the applicable methods.
  29 //
  30 // Unless stated otherwise methods of AlgorithmImplementation are responsible
  31 // for sanitizing their inputs. The following can be assumed:
  32 //
  33 //   * |algorithm.id()| and |key.algorithm.id()| matches the algorithm under
  34 //     which the implementation was registerd.
  35 //   * |algorithm| has the correct parameters type for the operation.
  36 //   * The key usages have already been verified. In fact in the case of calls
  37 //     to Encrypt()/Decrypt() the corresponding key usages may not be present
  38 //     (when wrapping/unwrapping).
  39 //
  40 // An AlgorithmImplementation can also assume that
  41 // crypto::EnsureOpenSSLInit() will be called before any of its
  42 // methods are invoked (except the constructor).
  43 class AlgorithmImplementation {
  44  public:
  45   virtual ~AlgorithmImplementation();
  46
  47   // This method corresponds to Web Crypto's crypto.subtle.encrypt().
  48   virtual Status Encrypt(const blink::WebCryptoAlgorithm& algorithm,
  49                          const blink::WebCryptoKey& key,
  50                          const CryptoData& data,
  51                          std::vector<uint8_t>* buffer) const;
  52
  53   // This method corresponds to Web Crypto's crypto.subtle.decrypt().
  54   virtual Status Decrypt(const blink::WebCryptoAlgorithm& algorithm,
  55                          const blink::WebCryptoKey& key,
  56                          const CryptoData& data,
  57                          std::vector<uint8_t>* buffer) const;
  58
  59   // This method corresponds to Web Crypto's crypto.subtle.sign().
  60   virtual Status Sign(const blink::WebCryptoAlgorithm& algorithm,
  61                       const blink::WebCryptoKey& key,
  62                       const CryptoData& data,
  63                       std::vector<uint8_t>* buffer) const;
  64
  65   // This method corresponds to Web Crypto's crypto.subtle.verify().
  66   virtual Status Verify(const blink::WebCryptoAlgorithm& algorithm,
  67                         const blink::WebCryptoKey& key,
  68                         const CryptoData& signature,
  69                         const CryptoData& data,
  70                         bool* signature_match) const;
  71
  72   // This method corresponds to Web Crypto's crypto.subtle.digest().
  73   virtual Status Digest(const blink::WebCryptoAlgorithm& algorithm,
  74                         const CryptoData& data,
  75                         std::vector<uint8_t>* buffer) const;
  76
  77   // This method corresponds to Web Crypto's crypto.subtle.generateKey().
  78   //
  79   // Implementations MUST verify |usages| and return an error if it is not
  80   // appropriate.
  81   virtual Status GenerateKey(const blink::WebCryptoAlgorithm& algorithm,
  82                              bool extractable,
  83                              blink::WebCryptoKeyUsageMask usages,
  84                              GenerateKeyResult* result) const;
  85
  86   // This method corresponds to Web Crypto's "derive bits" operation. It is
  87   // essentially crypto.subtle.deriveBits() with the exception that the length
  88   // can be "null" (|has_length_bits = true|).
  89   //
  90   // In cases where the length was not specified, an appropriate default for the
  91   // algorithm should be used (as described by the spec).
  92   virtual Status DeriveBits(const blink::WebCryptoAlgorithm& algorithm,
  93                             const blink::WebCryptoKey& base_key,
  94                             bool has_optional_length_bits,
  95                             unsigned int optional_length_bits,
  96                             std::vector<uint8_t>* derived_bytes) const;
  97
  98   // This method corresponds with Web Crypto's "Get key length" operation.
  99   //
 100   // In the Web Crypto spec the operation returns either "null" or an
 101   // "Integer". In this code "null" is represented by setting
 102   // |*has_length_bits = false|.
 103   virtual Status GetKeyLength(
 104       const blink::WebCryptoAlgorithm& key_length_algorithm,
 105       bool* has_length_bits,
 106       unsigned int* length_bits) const;
 107
 108   // -----------------------------------------------
 109   // Key import
 110   // -----------------------------------------------
 111
 112   // VerifyKeyUsagesBeforeImportKey() must be called before either
 113   // importing a key, or unwrapping a key.
 114   //
 115   // Implementations should return an error if the requested usages are invalid
 116   // when importing for the specified format.
 117   //
 118   // For instance, importing an RSA-SSA key with 'spki' format and Sign usage
 119   // is invalid. The 'spki' format implies it will be a public key, and public
 120   // keys do not support signing.
 121   //
 122   // When called with format=JWK the key type may be unknown. The
 123   // ImportKeyJwk() must do the final usage check.
 124   virtual Status VerifyKeyUsagesBeforeImportKey(
 125       blink::WebCryptoKeyFormat format,
 126       blink::WebCryptoKeyUsageMask usages) const;
 127
 128   // Dispatches to the format-specific ImportKey* method.
 129   Status ImportKey(blink::WebCryptoKeyFormat format,
 130                    const CryptoData& key_data,
 131                    const blink::WebCryptoAlgorithm& algorithm,
 132                    bool extractable,
 133                    blink::WebCryptoKeyUsageMask usages,
 134                    blink::WebCryptoKey* key) const;
 135
 136   // This method corresponds to Web Crypto's
 137   // crypto.subtle.importKey(format='raw').
 138   virtual Status ImportKeyRaw(const CryptoData& key_data,
 139                               const blink::WebCryptoAlgorithm& algorithm,
 140                               bool extractable,
 141                               blink::WebCryptoKeyUsageMask usages,
 142                               blink::WebCryptoKey* key) const;
 143
 144   // This method corresponds to Web Crypto's
 145   // crypto.subtle.importKey(format='pkcs8').
 146   virtual Status ImportKeyPkcs8(const CryptoData& key_data,
 147                                 const blink::WebCryptoAlgorithm& algorithm,
 148                                 bool extractable,
 149                                 blink::WebCryptoKeyUsageMask usages,
 150                                 blink::WebCryptoKey* key) const;
 151
 152   // This method corresponds to Web Crypto's
 153   // crypto.subtle.importKey(format='spki').
 154   virtual Status ImportKeySpki(const CryptoData& key_data,
 155                                const blink::WebCryptoAlgorithm& algorithm,
 156                                bool extractable,
 157                                blink::WebCryptoKeyUsageMask usages,
 158                                blink::WebCryptoKey* key) const;
 159
 160   // This method corresponds to Web Crypto's
 161   // crypto.subtle.importKey(format='jwk').
 162   virtual Status ImportKeyJwk(const CryptoData& key_data,
 163                               const blink::WebCryptoAlgorithm& algorithm,
 164                               bool extractable,
 165                               blink::WebCryptoKeyUsageMask usages,
 166                               blink::WebCryptoKey* key) const;
 167
 168   // -----------------------------------------------
 169   // Key export
 170   // -----------------------------------------------
 171
 172   // Dispatches to the format-specific ExportKey* method.
 173   Status ExportKey(blink::WebCryptoKeyFormat format,
 174                    const blink::WebCryptoKey& key,
 175                    std::vector<uint8_t>* buffer) const;
 176
 177   virtual Status ExportKeyRaw(const blink::WebCryptoKey& key,
 178                               std::vector<uint8_t>* buffer) const;
 179
 180   virtual Status ExportKeyPkcs8(const blink::WebCryptoKey& key,
 181                                 std::vector<uint8_t>* buffer) const;
 182
 183   virtual Status ExportKeySpki(const blink::WebCryptoKey& key,
 184                                std::vector<uint8_t>* buffer) const;
 185
 186   virtual Status ExportKeyJwk(const blink::WebCryptoKey& key,
 187                               std::vector<uint8_t>* buffer) const;
 188
 189   // -----------------------------------------------
 190   // Structured clone
 191   // -----------------------------------------------
 192
 193   // The Structured clone methods are used for synchronous serialization /
 194   // deserialization of a WebCryptoKey.
 195   //
 196   // This serialized format is used by Blink to:
 197   //   * Copy WebCryptoKeys between threads (postMessage to WebWorkers)
 198   //   * Copy WebCryptoKeys between domains (postMessage)
 199   //   * Copy WebCryptoKeys within the same domain (postMessage)
 200   //   * Persist the key to storage (IndexedDB)
 201   //
 202   // Implementations of structured cloning must:
 203   //   * Be threadsafe (structured cloning is called directly on the Blink
 204   //     thread, in contrast to the other methods of AlgorithmImplementation).
 205   //   * Use a stable format (a serialized key must forever be de-serializable,
 206   //     and be able to survive future migrations to crypto libraries)
 207   //   * Work for all keys (including ones marked as non-extractable).
 208   //
 209   // Tests to verify structured cloning are available in:
 210   //   LayoutTests/crypto/clone-*.html
 211
 212   // Note that SerializeKeyForClone() is not virtual because all
 213   // implementations end up doing the same thing.
 214   Status SerializeKeyForClone(const blink::WebCryptoKey& key,
 215                               blink::WebVector<uint8_t>* key_data) const;
 216
 217   virtual Status DeserializeKeyForClone(
 218       const blink::WebCryptoKeyAlgorithm& algorithm,
 219       blink::WebCryptoKeyType type,
 220       bool extractable,
 221       blink::WebCryptoKeyUsageMask usages,
 222       const CryptoData& key_data,
 223       blink::WebCryptoKey* key) const;
 224 };
 225
 226 }  // namespace webcrypto
 227
 228 #endif  // COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_