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 class AlgorithmImplementation {
  40  public:
  41   virtual ~AlgorithmImplementation();
  42
  43   // This method corresponds to Web Crypto's crypto.subtle.encrypt().
  44   virtual Status Encrypt(const blink::WebCryptoAlgorithm& algorithm,
  45                          const blink::WebCryptoKey& key,
  46                          const CryptoData& data,
  47                          std::vector<uint8_t>* buffer) const;
  48
  49   // This method corresponds to Web Crypto's crypto.subtle.decrypt().
  50   virtual Status Decrypt(const blink::WebCryptoAlgorithm& algorithm,
  51                          const blink::WebCryptoKey& key,
  52                          const CryptoData& data,
  53                          std::vector<uint8_t>* buffer) const;
  54
  55   // This method corresponds to Web Crypto's crypto.subtle.sign().
  56   virtual Status Sign(const blink::WebCryptoAlgorithm& algorithm,
  57                       const blink::WebCryptoKey& key,
  58                       const CryptoData& data,
  59                       std::vector<uint8_t>* buffer) const;
  60
  61   // This method corresponds to Web Crypto's crypto.subtle.verify().
  62   virtual Status Verify(const blink::WebCryptoAlgorithm& algorithm,
  63                         const blink::WebCryptoKey& key,
  64                         const CryptoData& signature,
  65                         const CryptoData& data,
  66                         bool* signature_match) const;
  67
  68   // This method corresponds to Web Crypto's crypto.subtle.digest().
  69   virtual Status Digest(const blink::WebCryptoAlgorithm& algorithm,
  70                         const CryptoData& data,
  71                         std::vector<uint8_t>* buffer) const;
  72
  73   // This method corresponds to Web Crypto's crypto.subtle.generateKey().
  74   //
  75   // Implementations MUST verify |usages| and return an error if it is not
  76   // appropriate.
  77   virtual Status GenerateKey(const blink::WebCryptoAlgorithm& algorithm,
  78                              bool extractable,
  79                              blink::WebCryptoKeyUsageMask usages,
  80                              GenerateKeyResult* result) const;
  81
  82   // This method corresponds to Web Crypto's "derive bits" operation. It is
  83   // essentially crypto.subtle.deriveBits() with the exception that the length
  84   // can be "null" (|has_length_bits = true|).
  85   //
  86   // In cases where the length was not specified, an appropriate default for the
  87   // algorithm should be used (as described by the spec).
  88   virtual Status DeriveBits(const blink::WebCryptoAlgorithm& algorithm,
  89                             const blink::WebCryptoKey& base_key,
  90                             bool has_optional_length_bits,
  91                             unsigned int optional_length_bits,
  92                             std::vector<uint8_t>* derived_bytes) const;
  93
  94   // This method corresponds with Web Crypto's "Get key length" operation.
  95   //
  96   // In the Web Crypto spec the operation returns either "null" or an
  97   // "Integer". In this code "null" is represented by setting
  98   // |*has_length_bits = false|.
  99   virtual Status GetKeyLength(
 100       const blink::WebCryptoAlgorithm& key_length_algorithm,
 101       bool* has_length_bits,
 102       unsigned int* length_bits) const;
 103
 104   // -----------------------------------------------
 105   // Key import
 106   // -----------------------------------------------
 107
 108   // VerifyKeyUsagesBeforeImportKey() must be called before either
 109   // importing a key, or unwrapping a key.
 110   //
 111   // Implementations should return an error if the requested usages are invalid
 112   // when importing for the specified format.
 113   //
 114   // For instance, importing an RSA-SSA key with 'spki' format and Sign usage
 115   // is invalid. The 'spki' format implies it will be a public key, and public
 116   // keys do not support signing.
 117   //
 118   // When called with format=JWK the key type may be unknown. The
 119   // ImportKeyJwk() must do the final usage check.
 120   virtual Status VerifyKeyUsagesBeforeImportKey(
 121       blink::WebCryptoKeyFormat format,
 122       blink::WebCryptoKeyUsageMask usages) const;
 123
 124   // Dispatches to the format-specific ImportKey* method.
 125   Status ImportKey(blink::WebCryptoKeyFormat format,
 126                    const CryptoData& key_data,
 127                    const blink::WebCryptoAlgorithm& algorithm,
 128                    bool extractable,
 129                    blink::WebCryptoKeyUsageMask usages,
 130                    blink::WebCryptoKey* key) const;
 131
 132   // This method corresponds to Web Crypto's
 133   // crypto.subtle.importKey(format='raw').
 134   virtual Status ImportKeyRaw(const CryptoData& key_data,
 135                               const blink::WebCryptoAlgorithm& algorithm,
 136                               bool extractable,
 137                               blink::WebCryptoKeyUsageMask usages,
 138                               blink::WebCryptoKey* key) const;
 139
 140   // This method corresponds to Web Crypto's
 141   // crypto.subtle.importKey(format='pkcs8').
 142   virtual Status ImportKeyPkcs8(const CryptoData& key_data,
 143                                 const blink::WebCryptoAlgorithm& algorithm,
 144                                 bool extractable,
 145                                 blink::WebCryptoKeyUsageMask usages,
 146                                 blink::WebCryptoKey* key) const;
 147
 148   // This method corresponds to Web Crypto's
 149   // crypto.subtle.importKey(format='spki').
 150   virtual Status ImportKeySpki(const CryptoData& key_data,
 151                                const blink::WebCryptoAlgorithm& algorithm,
 152                                bool extractable,
 153                                blink::WebCryptoKeyUsageMask usages,
 154                                blink::WebCryptoKey* key) const;
 155
 156   // This method corresponds to Web Crypto's
 157   // crypto.subtle.importKey(format='jwk').
 158   virtual Status ImportKeyJwk(const CryptoData& key_data,
 159                               const blink::WebCryptoAlgorithm& algorithm,
 160                               bool extractable,
 161                               blink::WebCryptoKeyUsageMask usages,
 162                               blink::WebCryptoKey* key) const;
 163
 164   // -----------------------------------------------
 165   // Key export
 166   // -----------------------------------------------
 167
 168   // Dispatches to the format-specific ExportKey* method.
 169   Status ExportKey(blink::WebCryptoKeyFormat format,
 170                    const blink::WebCryptoKey& key,
 171                    std::vector<uint8_t>* buffer) const;
 172
 173   virtual Status ExportKeyRaw(const blink::WebCryptoKey& key,
 174                               std::vector<uint8_t>* buffer) const;
 175
 176   virtual Status ExportKeyPkcs8(const blink::WebCryptoKey& key,
 177                                 std::vector<uint8_t>* buffer) const;
 178
 179   virtual Status ExportKeySpki(const blink::WebCryptoKey& key,
 180                                std::vector<uint8_t>* buffer) const;
 181
 182   virtual Status ExportKeyJwk(const blink::WebCryptoKey& key,
 183                               std::vector<uint8_t>* buffer) const;
 184
 185   // -----------------------------------------------
 186   // Structured clone
 187   // -----------------------------------------------
 188
 189   // The Structured clone methods are used for synchronous serialization /
 190   // deserialization of a WebCryptoKey.
 191   //
 192   // This serialized format is used by Blink to:
 193   //   * Copy WebCryptoKeys between threads (postMessage to WebWorkers)
 194   //   * Copy WebCryptoKeys between domains (postMessage)
 195   //   * Copy WebCryptoKeys within the same domain (postMessage)
 196   //   * Persist the key to storage (IndexedDB)
 197   //
 198   // Implementations of structured cloning must:
 199   //   * Be threadsafe (structured cloning is called directly on the Blink
 200   //     thread, in contrast to the other methods of AlgorithmImplementation).
 201   //   * Use a stable format (a serialized key must forever be de-serializable,
 202   //     and be able to survive future migrations to crypto libraries)
 203   //   * Work for all keys (including ones marked as non-extractable).
 204   //
 205   // Tests to verify structured cloning are available in:
 206   //   LayoutTests/crypto/clone-*.html
 207   virtual Status SerializeKeyForClone(
 208       const blink::WebCryptoKey& key,
 209       blink::WebVector<uint8_t>* key_data) const;
 210
 211   virtual Status DeserializeKeyForClone(
 212       const blink::WebCryptoKeyAlgorithm& algorithm,
 213       blink::WebCryptoKeyType type,
 214       bool extractable,
 215       blink::WebCryptoKeyUsageMask usages,
 216       const CryptoData& key_data,
 217       blink::WebCryptoKey* key) const;
 218 };
 219
 220 }  // namespace webcrypto
 221
 222 #endif  // COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_