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 "WebCryptoKey.h"
36 #include "WebPrivatePtr.h"
38 namespace WebCore { class CryptoResult; }
41 namespace WTF { template <typename T> class PassRefPtr; }
49 class WebCryptoResult {
51 WebCryptoResult(const WebCryptoResult& o)
61 WebCryptoResult& operator=(const WebCryptoResult& o)
67 BLINK_PLATFORM_EXPORT void completeWithError();
69 // Note that WebString is NOT safe to pass across threads.
71 // Error details are intended to be displayed to developers for debugging.
72 // They MUST NEVER reveal any secret information such as bytes of the key
73 // or plain text. An appropriate error would be something like:
74 // "iv must be 16 bytes long".
75 BLINK_PLATFORM_EXPORT void completeWithError(const WebString&);
77 // Note that WebArrayBuffer is NOT safe to create from another thread.
78 BLINK_PLATFORM_EXPORT void completeWithBuffer(const WebArrayBuffer&);
79 // Makes a copy of the input data given as a pointer and byte length.
80 BLINK_PLATFORM_EXPORT void completeWithBuffer(const void*, unsigned);
81 BLINK_PLATFORM_EXPORT void completeWithBoolean(bool);
82 BLINK_PLATFORM_EXPORT void completeWithKey(const WebCryptoKey&);
83 BLINK_PLATFORM_EXPORT void completeWithKeyPair(const WebCryptoKey& publicKey, const WebCryptoKey& privateKey);
86 BLINK_PLATFORM_EXPORT explicit WebCryptoResult(const WTF::PassRefPtr<WebCore::CryptoResult>&);
90 BLINK_PLATFORM_EXPORT void reset();
91 BLINK_PLATFORM_EXPORT void assign(const WebCryptoResult&);
93 WebPrivatePtr<WebCore::CryptoResult> m_impl;
98 // WebCrypto is the interface for starting one-shot cryptographic
101 // -----------------------
102 // Completing the request
103 // -----------------------
105 // Implementations signal completion by calling one of the methods on
106 // "result". Only a single result/error should be set for the request.
107 // Different operations expect different result types based on the
108 // algorithm parameters; see the Web Crypto standard for details.
110 // The result can be set either synchronously while handling the request,
111 // or asynchronously after the method has returned. When completing
112 // asynchronously make a copy of the WebCryptoResult and call it from the
113 // same thread that started the request.
115 // -----------------------
117 // -----------------------
119 // The WebCrypto interface will only be called from the render's main
120 // thread. All communication back to Blink must be on this same thread.
123 // * The WebCryptoResult is NOT threadsafe. It should only be used from
124 // the Blink main thread.
126 // * WebCryptoKey and WebCryptoAlgorithm ARE threadsafe. They can be
127 // safely copied between threads and accessed. Copying is cheap because
128 // they are internally reference counted.
130 // * WebArrayBuffer is NOT threadsafe. It should only be created from the
131 // Blink main thread. This means threaded implementations may have to
132 // make a copy of the output buffer.
134 // -----------------------
136 // -----------------------
138 // * Data buffers are passed as (basePointer, byteLength) pairs.
139 // These buffers are only valid during the call itself. Asynchronous
140 // implementations wishing to access it after the function returns
141 // should make a copy.
143 // * All WebCryptoKeys are guaranteeed to be !isNull().
145 // * All WebCryptoAlgorithms are guaranteed to be !isNull()
146 // unless noted otherwise. Being "null" means that it was unspecified
149 // * Look to the Web Crypto spec for an explanation of the parameter. The
150 // method names here have a 1:1 correspondence with those of
151 // crypto.subtle, with the exception of "verify" which is here called
152 // "verifySignature".
154 // -----------------------
155 // Guarantees on input validity
156 // -----------------------
158 // Implementations MUST carefully sanitize algorithm inputs before using
159 // them, as they come directly from the user. Few checks have been done on
160 // algorithm parameters prior to passing to the embedder.
162 // Only the following checks can be assumed as having alread passed:
164 // * The key is extractable when calling into exportKey/wrapKey.
165 // * The key usages permit the operation being requested.
166 // * The key's algorithm matches that of the requested operation.
168 virtual void encrypt(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(); }
169 virtual void decrypt(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(); }
170 virtual void sign(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(); }
171 virtual void verifySignature(const WebCryptoAlgorithm&, const WebCryptoKey&, const unsigned char* signature, unsigned signatureSize, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(); }
172 virtual void digest(const WebCryptoAlgorithm&, const unsigned char* data, unsigned dataSize, WebCryptoResult result) { result.completeWithError(); }
173 virtual void generateKey(const WebCryptoAlgorithm&, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(); }
174 // It is possible for the WebCryptoAlgorithm to be "isNull()"
175 virtual void importKey(WebCryptoKeyFormat, const unsigned char* keyData, unsigned keyDataSize, const WebCryptoAlgorithm&, bool extractable, WebCryptoKeyUsageMask, WebCryptoResult result) { result.completeWithError(); }
176 virtual void exportKey(WebCryptoKeyFormat, const WebCryptoKey&, WebCryptoResult result) { result.completeWithError(); }
177 virtual void wrapKey(WebCryptoKeyFormat, const WebCryptoKey& key, const WebCryptoKey& wrappingKey, const WebCryptoAlgorithm&, WebCryptoResult result) { result.completeWithError(); }
178 // It is possible that unwrappedKeyAlgorithm.isNull()
179 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(); }
182 virtual ~WebCrypto() { }