Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / third_party / WebKit / public / platform / WebCrypto.h
blobd3271971d5e843bba80cf65a82f2a75ba69b659f
1 /*
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
6 * met:
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
13 * distribution.
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.
31 #ifndef WebCrypto_h
32 #define WebCrypto_h
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 #if INSIDE_BLINK
42 #include "platform/heap/Handle.h"
43 #endif
45 namespace blink {
47 class CryptoResult;
48 class CryptoResultCancel;
49 class WebString;
51 enum WebCryptoErrorType {
52 WebCryptoErrorTypeType,
53 WebCryptoErrorTypeNotSupported,
54 WebCryptoErrorTypeSyntax,
55 WebCryptoErrorTypeInvalidAccess,
56 WebCryptoErrorTypeData,
57 WebCryptoErrorTypeOperation,
60 class WebCryptoResult {
61 public:
62 WebCryptoResult(const WebCryptoResult& o)
64 assign(o);
67 ~WebCryptoResult()
69 reset();
72 WebCryptoResult& operator=(const WebCryptoResult& o)
74 assign(o);
75 return *this;
78 // Note that WebString is NOT safe to pass across threads.
80 // Error details are surfaced in an exception, and MUST NEVER reveal any
81 // secret information such as bytes of the key or plain text. An
82 // appropriate error would be something like:
83 // "iv must be 16 bytes long".
84 BLINK_PLATFORM_EXPORT void completeWithError(WebCryptoErrorType, const WebString&);
86 // Makes a copy of the input data given as a pointer and byte length.
87 BLINK_PLATFORM_EXPORT void completeWithBuffer(const void*, unsigned);
88 BLINK_PLATFORM_EXPORT void completeWithJson(const char* utf8Data, unsigned length);
89 BLINK_PLATFORM_EXPORT void completeWithBoolean(bool);
90 BLINK_PLATFORM_EXPORT void completeWithKey(const WebCryptoKey&);
91 BLINK_PLATFORM_EXPORT void completeWithKeyPair(const WebCryptoKey& publicKey, const WebCryptoKey& privateKey);
93 // Returns true if the underlying operation was cancelled.
94 // This method can be called from any thread.
95 BLINK_PLATFORM_EXPORT bool cancelled() const;
97 #if INSIDE_BLINK
98 BLINK_PLATFORM_EXPORT WebCryptoResult(CryptoResult*, const PassRefPtr<CryptoResultCancel>&);
99 #endif
101 private:
102 BLINK_PLATFORM_EXPORT void reset();
103 BLINK_PLATFORM_EXPORT void assign(const WebCryptoResult&);
105 WebPrivatePtr<CryptoResult, WebPrivatePtrDestructionCrossThread> m_impl;
106 WebPrivatePtr<CryptoResultCancel, WebPrivatePtrDestructionCrossThread> m_cancel;
109 class WebCryptoDigestor {
110 public:
111 virtual ~WebCryptoDigestor() { }
113 // consume() will return |true| on the successful addition of data to the
114 // partially generated digest. It will return |false| when that fails. After
115 // a return of |false|, consume() should not be called again (nor should
116 // finish() be called).
117 virtual bool consume(const unsigned char* data, unsigned dataSize) { return false; }
119 // finish() will return |true| if the digest has been successfully computed
120 // and put into the result buffer, otherwise it will return |false|. In
121 // either case, neither finish() nor consume() should be called again after
122 // a call to finish(). resultData is valid until the WebCrytpoDigestor
123 // object is destroyed.
124 virtual bool finish(unsigned char*& resultData, unsigned& resultDataSize) { return false; }
126 protected:
127 WebCryptoDigestor() { }
130 class WebCrypto {
131 public:
132 // WebCrypto is the interface for starting one-shot cryptographic
133 // operations.
135 // -----------------------
136 // Completing the request
137 // -----------------------
139 // Implementations signal completion by calling one of the methods on
140 // "result". Only a single result/error should be set for the request.
141 // Different operations expect different result types based on the
142 // algorithm parameters; see the Web Crypto standard for details.
144 // The result can be set either synchronously while handling the request,
145 // or asynchronously after the method has returned. When completing
146 // asynchronously make a copy of the WebCryptoResult and call it from the
147 // same thread that started the request.
149 // If the request was cancelled it is not necessary for implementations to
150 // set the result.
152 // -----------------------
153 // Threading
154 // -----------------------
156 // The WebCrypto interface will be called from blink threads (main or
157 // web worker). All communication back to Blink must be on this same thread.
159 // Notably:
161 // * The WebCryptoResult can be copied between threads, however all
162 // methods other than the destructor must be called from the origin
163 // Blink thread.
165 // * WebCryptoKey and WebCryptoAlgorithm ARE threadsafe. They can be
166 // safely copied between threads and accessed. Copying is cheap because
167 // they are internally reference counted.
169 // -----------------------
170 // Inputs
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, ""); }
211 virtual void deriveBits(const WebCryptoAlgorithm&, const WebCryptoKey&, unsigned length, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
212 virtual void deriveKey(const WebCryptoAlgorithm& algorithm, const WebCryptoKey& baseKey, const WebCryptoAlgorithm& importAlgorithm, const WebCryptoAlgorithm& keyLengthAlgorithm, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(WebCryptoErrorTypeNotSupported, ""); }
214 // This is the exception to the "Completing the request" guarantees
215 // outlined above. This is useful for Blink internal crypto and is not part
216 // of the WebCrypto standard. createDigestor must provide the result via
217 // the WebCryptoDigestor object synchronously. createDigestor may return 0
218 // if it fails to create a WebCryptoDigestor. If it succeeds, the
219 // WebCryptoDigestor returned by createDigestor must be freed by the
220 // caller.
221 virtual WebCryptoDigestor* createDigestor(WebCryptoAlgorithmId algorithmId) { return nullptr; }
223 // -----------------------
224 // Structured clone
225 // -----------------------
227 // deserializeKeyForClone() and serializeKeyForClone() are used for
228 // implementing structured cloning of WebCryptoKey.
230 // Blink is responsible for saving and restoring all of the attributes of
231 // WebCryptoKey EXCEPT for the actual key data:
233 // In other words, Blink takes care of serializing:
234 // * Key usages
235 // * Key extractability
236 // * Key algorithm
237 // * Key type (public, private, secret)
239 // The embedder is responsible for saving the key data itself.
241 // Visibility of the serialized key data:
243 // The serialized key data will NOT be visible to web pages. So if the
244 // serialized format were to include key bytes as plain text, this wouldn't
245 // make it available to web pages.
247 // Longevity of the key data:
249 // The serialized key data is intended to be long lived (years) and MUST
250 // be using a stable format. For instance a key might be persisted to
251 // IndexedDB and should be able to be deserialized correctly in the
252 // future.
254 // Error handling and asynchronous completion:
256 // Serialization/deserialization must complete synchronously, and will
257 // block the JavaScript thread.
259 // The only reasons to fail serialization/deserialization are:
260 // * Key serialization not yet implemented
261 // * The bytes to deserialize were corrupted
263 // Creates a new key given key data which was written using
264 // serializeKeyForClone(). Returns true on success.
265 virtual bool deserializeKeyForClone(const WebCryptoKeyAlgorithm&, WebCryptoKeyType, bool extractable, WebCryptoKeyUsageMask, const unsigned char* keyData, unsigned keyDataSize, WebCryptoKey&) { return false; }
267 // Writes the key data into the given WebVector.
268 // Returns true on success.
269 virtual bool serializeKeyForClone(const WebCryptoKey&, WebVector<unsigned char>&) { return false; }
271 protected:
272 virtual ~WebCrypto() { }
275 } // namespace blink
277 #endif // WebCrypto_h