algorithm_implementation.h 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202
  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. #ifndef COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_
  5. #define COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_
  6. #include <stdint.h>
  7. #include <memory>
  8. #include <vector>
  9. #include "base/containers/span.h"
  10. #include "third_party/blink/public/platform/web_crypto.h"
  11. namespace webcrypto {
  12. class GenerateKeyResult;
  13. class Status;
  14. // AlgorithmImplementation is a base class for *executing* the operations of an
  15. // algorithm (generating keys, encrypting, signing, etc.).
  16. //
  17. // This is in contrast to blink::WebCryptoAlgorithm which instead *describes*
  18. // the operation and its parameters.
  19. //
  20. // AlgorithmImplementation has reasonable default implementations for all
  21. // methods which behave as if the operation is it is unsupported, so
  22. // implementations need only override the applicable methods.
  23. //
  24. // Unless stated otherwise methods of AlgorithmImplementation are responsible
  25. // for sanitizing their inputs. The following can be assumed:
  26. //
  27. // * |algorithm.id()| and |key.algorithm.id()| matches the algorithm under
  28. // which the implementation was registerd.
  29. // * |algorithm| has the correct parameters type for the operation.
  30. // * The key usages have already been verified. In fact in the case of calls
  31. // to Encrypt()/Decrypt() the corresponding key usages may not be present
  32. // (when wrapping/unwrapping).
  33. //
  34. // An AlgorithmImplementation can also assume that crypto::EnsureOpenSSLInit()
  35. // will be called before any of its methods are invoked (except the
  36. // constructor).
  37. class AlgorithmImplementation {
  38. public:
  39. virtual ~AlgorithmImplementation();
  40. // This is what is run whenever the spec says:
  41. // "Let result be the result of performing the encrypt operation"
  42. //
  43. // (crypto.subtle.encrypt() dispatches to this)
  44. virtual Status Encrypt(const blink::WebCryptoAlgorithm& algorithm,
  45. const blink::WebCryptoKey& key,
  46. base::span<const uint8_t> data,
  47. std::vector<uint8_t>* buffer) const;
  48. // This is what is run whenever the spec says:
  49. // "Let result be the result of performing the decrypt operation"
  50. //
  51. // (crypto.subtle.decrypt() dispatches to this)
  52. virtual Status Decrypt(const blink::WebCryptoAlgorithm& algorithm,
  53. const blink::WebCryptoKey& key,
  54. base::span<const uint8_t> data,
  55. std::vector<uint8_t>* buffer) const;
  56. // This is what is run whenever the spec says:
  57. // "Let result be the result of performing the sign operation"
  58. //
  59. // (crypto.subtle.sign() dispatches to this)
  60. virtual Status Sign(const blink::WebCryptoAlgorithm& algorithm,
  61. const blink::WebCryptoKey& key,
  62. base::span<const uint8_t> data,
  63. std::vector<uint8_t>* buffer) const;
  64. // This is what is run whenever the spec says:
  65. // "Let result be the result of performing the verify operation"
  66. //
  67. // (crypto.subtle.verify() dispatches to this)
  68. virtual Status Verify(const blink::WebCryptoAlgorithm& algorithm,
  69. const blink::WebCryptoKey& key,
  70. base::span<const uint8_t> signature,
  71. base::span<const uint8_t> data,
  72. bool* signature_match) const;
  73. // This is what is run whenever the spec says:
  74. // "Let result be the result of performing the digest operation"
  75. //
  76. // (crypto.subtle.digest() dispatches to this)
  77. virtual Status Digest(const blink::WebCryptoAlgorithm& algorithm,
  78. base::span<const uint8_t> data,
  79. std::vector<uint8_t>* buffer) const;
  80. // This is what is run whenever the spec says:
  81. // "Let result be the result of executing the generate key operation"
  82. //
  83. // (crypto.subtle.generateKey() dispatches to this)
  84. virtual Status GenerateKey(const blink::WebCryptoAlgorithm& algorithm,
  85. bool extractable,
  86. blink::WebCryptoKeyUsageMask usages,
  87. GenerateKeyResult* result) const;
  88. // This is what is run whenever the spec says:
  89. // "Let result be a new ArrayBuffer containing the result of executing the
  90. // derive bits operation"
  91. //
  92. // (crypto.subtle.deriveBits() dispatches to this)
  93. virtual Status DeriveBits(const blink::WebCryptoAlgorithm& algorithm,
  94. const blink::WebCryptoKey& base_key,
  95. bool has_optional_length_bits,
  96. unsigned int optional_length_bits,
  97. std::vector<uint8_t>* derived_bytes) const;
  98. // This is what is run whenever the spec says:
  99. // "Let length be the result of executing the get key length algorithm"
  100. //
  101. // In the Web Crypto spec the operation returns either "null" or an
  102. // "Integer". In this code "null" is represented by setting
  103. // |*has_length_bits = false|.
  104. virtual Status GetKeyLength(
  105. const blink::WebCryptoAlgorithm& key_length_algorithm,
  106. bool* has_length_bits,
  107. unsigned int* length_bits) const;
  108. // This is what is run whenever the spec says:
  109. // "Let result be the result of performing the import key operation"
  110. //
  111. // (crypto.subtle.importKey() dispatches to this).
  112. virtual Status ImportKey(blink::WebCryptoKeyFormat format,
  113. base::span<const uint8_t> key_data,
  114. const blink::WebCryptoAlgorithm& algorithm,
  115. bool extractable,
  116. blink::WebCryptoKeyUsageMask usages,
  117. blink::WebCryptoKey* key) const;
  118. // This is what is run whenever the spec says:
  119. // "Let result be the result of performing the export key operation"
  120. //
  121. // (crypto.subtle.exportKey() dispatches to this).
  122. virtual Status ExportKey(blink::WebCryptoKeyFormat format,
  123. const blink::WebCryptoKey& key,
  124. std::vector<uint8_t>* buffer) const;
  125. // -----------------------------------------------
  126. // Structured clone
  127. // -----------------------------------------------
  128. // The Structured clone methods are used for synchronous serialization /
  129. // deserialization of a WebCryptoKey.
  130. //
  131. // This serialized format is used by Blink to:
  132. // * Copy WebCryptoKeys between threads (postMessage to WebWorkers)
  133. // * Copy WebCryptoKeys between domains (postMessage)
  134. // * Copy WebCryptoKeys within the same domain (postMessage)
  135. // * Persist the key to storage (IndexedDB)
  136. //
  137. // Implementations of structured cloning must:
  138. // * Be threadsafe (structured cloning is called directly on the Blink
  139. // thread, in contrast to the other methods of AlgorithmImplementation).
  140. // * Use a stable format (a serialized key must forever be de-serializable,
  141. // and be able to survive future migrations to crypto libraries)
  142. // * Work for all keys (including ones marked as non-extractable).
  143. // * Gracefully handle invalid inputs
  144. //
  145. // Tests to verify structured cloning are available in:
  146. // LayoutTests/crypto/clone-*.html
  147. // Note that SerializeKeyForClone() is not virtual because all
  148. // implementations end up doing the same thing.
  149. Status SerializeKeyForClone(const blink::WebCryptoKey& key,
  150. blink::WebVector<uint8_t>* key_data) const;
  151. // Deserializes key data from Blink (used for structured cloning).
  152. //
  153. // The inputs to this function originate from Blink, and may not be
  154. // consistent or valid. Implementations must return a failure when processing
  155. // invalid or adversarially constructed inputs.
  156. //
  157. // The ONLY guarantee implementations can assume is that |algorithm.id()|
  158. // corresponds with that which the AlgorithmImplementation was registered
  159. // under.
  160. //
  161. // Implementations must be prepared to handle:
  162. //
  163. // * |type| being invalid for this algorithm's key type(s)
  164. // * |algorithm.params()| being inconsistent with the |algorithm.id()|
  165. // * |usages| being inconsistent with the key type
  166. // * |extractable| being inconsistent with the key type
  167. // * |key_data| containing an incorrect serialized format
  168. // * Backwards-compatibility: the inputs may have been produced by older
  169. // versions of the code.
  170. virtual Status DeserializeKeyForClone(
  171. const blink::WebCryptoKeyAlgorithm& algorithm,
  172. blink::WebCryptoKeyType type,
  173. bool extractable,
  174. blink::WebCryptoKeyUsageMask usages,
  175. base::span<const uint8_t> key_data,
  176. blink::WebCryptoKey* key) const;
  177. };
  178. } // namespace webcrypto
  179. #endif // COMPONENTS_WEBCRYPTO_ALGORITHM_IMPLEMENTATION_H_