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