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