2 * Copyright (C) 2013 Google Inc. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 * * Redistributions in binary form must reproduce the above
11 * copyright notice, this list of conditions and the following disclaimer
12 * in the documentation and/or other materials provided with the
14 * * Neither the name of Google Inc. nor the names of its
15 * contributors may be used to endorse or promote products derived from
16 * this software without specific prior written permission.
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 #include "WebCommon.h"
35 #include "WebCryptoAlgorithm.h"
36 #include "WebCryptoKey.h"
37 #include "WebPrivatePtr.h"
38 #include "WebString.h"
39 #include "WebVector.h"
41 namespace WebCore { class CryptoResult; }
44 namespace WTF { template <typename T> class PassRefPtr; }
52 enum WebCryptoErrorType {
53 WebCryptoErrorTypeType,
54 WebCryptoErrorTypeNotSupported,
55 WebCryptoErrorTypeSyntax,
56 WebCryptoErrorTypeInvalidState,
57 WebCryptoErrorTypeInvalidAccess,
58 WebCryptoErrorTypeUnknown,
59 WebCryptoErrorTypeData,
60 WebCryptoErrorTypeOperation,
63 class WebCryptoResult {
65 WebCryptoResult(const WebCryptoResult& o)
75 WebCryptoResult& operator=(const WebCryptoResult& o)
81 // Note that WebString is NOT safe to pass across threads.
83 // Error details are surfaced in an exception, and MUST NEVER reveal any
84 // secret information such as bytes of the key or plain text. An
85 // appropriate error would be something like:
86 // "iv must be 16 bytes long".
87 BLINK_PLATFORM_EXPORT void completeWithError(WebCryptoErrorType, const WebString&);
89 // Note that WebArrayBuffer is NOT safe to create from another thread.
90 BLINK_PLATFORM_EXPORT void completeWithBuffer(const WebArrayBuffer&);
91 // Makes a copy of the input data given as a pointer and byte length.
92 BLINK_PLATFORM_EXPORT void completeWithBuffer(const void*, unsigned);
93 BLINK_PLATFORM_EXPORT void completeWithBoolean(bool);
94 BLINK_PLATFORM_EXPORT void completeWithKey(const WebCryptoKey&);
95 BLINK_PLATFORM_EXPORT void completeWithKeyPair(const WebCryptoKey& publicKey, const WebCryptoKey& privateKey);
98 BLINK_PLATFORM_EXPORT explicit WebCryptoResult(const WTF::PassRefPtr<WebCore::CryptoResult>&);
102 BLINK_PLATFORM_EXPORT void reset();
103 BLINK_PLATFORM_EXPORT void assign(const WebCryptoResult&);
105 WebPrivatePtr<WebCore::CryptoResult> m_impl;
108 class WebCryptoDigestor {
110 virtual ~WebCryptoDigestor() { }
112 // consume() will return |true| on the successful addition of data to the
113 // partially generated digest. It will return |false| when that fails. After
114 // a return of |false|, consume() should not be called again (nor should
115 // finish() be called).
116 virtual bool consume(const unsigned char* data, unsigned dataSize) { return false; }
118 // finish() will return |true| if the digest has been successfully computed
119 // and put into the result buffer, otherwise it will return |false|. In
120 // either case, neither finish() nor consume() should be called again after
121 // a call to finish(). resultData is valid until the WebCrytpoDigestor
122 // object is destroyed.
123 virtual bool finish(unsigned char*& resultData, unsigned& resultDataSize) { return false; }
126 WebCryptoDigestor() { }
131 // WebCrypto is the interface for starting one-shot cryptographic
134 // -----------------------
135 // Completing the request
136 // -----------------------
138 // Implementations signal completion by calling one of the methods on
139 // "result". Only a single result/error should be set for the request.
140 // Different operations expect different result types based on the
141 // algorithm parameters; see the Web Crypto standard for details.
143 // The result can be set either synchronously while handling the request,
144 // or asynchronously after the method has returned. When completing
145 // asynchronously make a copy of the WebCryptoResult and call it from the
146 // same thread that started the request.
148 // -----------------------
150 // -----------------------
152 // The WebCrypto interface will be called from blink threads (main or
153 // web worker). All communication back to Blink must be on this same thread.
157 // * The WebCryptoResult can be copied between threads, however all
158 // methods other than the destructor must be called from the origin
161 // * WebCryptoKey and WebCryptoAlgorithm ARE threadsafe. They can be
162 // safely copied between threads and accessed. Copying is cheap because
163 // they are internally reference counted.
165 // * WebArrayBuffer is NOT threadsafe. It should only be created from the
166 // target Blink thread. This means threaded implementations may have to
167 // make a copy of the output buffer.
169 // -----------------------
171 // -----------------------
173 // * Data buffers are passed as (basePointer, byteLength) pairs.
174 // These buffers are only valid during the call itself. Asynchronous
175 // implementations wishing to access it after the function returns
176 // should make a copy.
178 // * All WebCryptoKeys are guaranteeed to be !isNull().
180 // * All WebCryptoAlgorithms are guaranteed to be !isNull()
182 // * Look to the Web Crypto spec for an explanation of the parameter. The
183 // method names here have a 1:1 correspondence with those of
184 // crypto.subtle, with the exception of "verify" which is here called
185 // "verifySignature".
187 // -----------------------
188 // Guarantees on input validity
189 // -----------------------
191 // Implementations MUST carefully sanitize algorithm inputs before using
192 // them, as they come directly from the user. Few checks have been done on
193 // algorithm parameters prior to passing to the embedder.
195 // Only the following checks can be assumed as having already passed:
197 // * The key is extractable when calling into exportKey/wrapKey.
198 // * The key usages permit the operation being requested.
199 // * The key's algorithm matches that of the requested operation.
201 virtual void encrypt(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
202 virtual void decrypt(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
203 virtual void sign(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
204 virtual void verifySignature(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* signature, unsigned signatureSize, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
205 virtual void digest(const WebCryptoAlgorithm&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
206 virtual void generateKey(const WebCryptoAlgorithm&, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
207 virtual void importKey(WebCryptoKeyFormat, const unsigned char* keyData, unsigned keyDataSize, const WebCryptoAlgorithm&, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
208 virtual void exportKey(WebCryptoKeyFormat, const WebCryptoKey&, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
209 virtual void wrapKey(WebCryptoKeyFormat, const WebCryptoKey& key, const WebCryptoKey& wrappingKey, const WebCryptoAlgorithm&, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
210 virtual void unwrapKey(WebCryptoKeyFormat, const unsigned char* wrappedKey, unsigned wrappedKeySize, const WebCryptoKey&, const WebCryptoAlgorithm& unwrapAlgorithm, const WebCryptoAlgorithm& unwrappedKeyAlgorithm, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
212 // This is the exception to the "Completing the request" guarantees
213 // outlined above. This is useful for Blink internal crypto and is not part
214 // of the WebCrypto standard. createDigestor must provide the result via
215 // the WebCryptoDigestor object synchronously. createDigestor may return 0
216 // if it fails to create a WebCryptoDigestor. If it succeeds, the
217 // WebCryptoDigestor returned by createDigestor must be freed by the
219 virtual WebCryptoDigestor* createDigestor(WebCryptoAlgorithmId algorithmId) { return 0; }
221 // -----------------------
223 // -----------------------
225 // deserializeKeyForClone() and serializeKeyForClone() are used for
226 // implementing structured cloning of WebCryptoKey.
228 // Blink is responsible for saving and restoring all of the attributes of
229 // WebCryptoKey EXCEPT for the actual key data:
231 // In other words, Blink takes care of serializing:
233 // * Key extractability
235 // * Key type (public, private, secret)
237 // The embedder is responsible for saving the key data itself.
239 // Visibility of the serialized key data:
241 // The serialized key data will NOT be visible to web pages. So if the
242 // serialized format were to include key bytes as plain text, this wouldn't
243 // make it available to web pages.
245 // Longevity of the key data:
247 // The serialized key data is intended to be long lived (years) and MUST
248 // be using a stable format. For instance a key might be persisted to
249 // IndexedDB and should be able to be deserialized correctly in the
252 // Error handling and asynchronous completion:
254 // Serialization/deserialization must complete synchronously, and will
255 // block the JavaScript thread.
257 // The only reasons to fail serialization/deserialization are:
258 // * Key serialization not yet implemented
259 // * The bytes to deserialize were corrupted
261 // Creates a new key given key data which was written using
262 // serializeKeyForClone(). Returns true on success.
263 virtual bool deserializeKeyForClone(const WebCryptoKeyAlgorithm&, WebCryptoKeyType, bool extractable, WebCryptoKeyUsageMask, const unsigned char* keyData, unsigned keyDataSize, WebCryptoKey&) { return false; }
265 // Writes the key data into the given WebVector.
266 // Returns true on success.
267 virtual bool serializeKeyForClone(const WebCryptoKey&, WebVector<unsigned char>&) { return false; }
270 virtual ~WebCrypto() { }