src/third_party/WebKit/public/platform/WebCrypto.h

   1 /*
   2  * Copyright (C) 2013 Google Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   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.
  17  *
  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.
  29  */
  30
  31 #ifndef WebCrypto_h
  32 #define WebCrypto_h
  33
  34 #include "WebCommon.h"
  35 #include "WebCryptoKey.h"
  36 #include "WebPrivatePtr.h"
  37
  38 namespace WebCore { class CryptoResult; }
  39
  40 #if INSIDE_BLINK
  41 namespace WTF { template <typename T> class PassRefPtr; }
  42 #endif
  43
  44 namespace blink {
  45
  46 class WebArrayBuffer;
  47 class WebString;
  48
  49 class WebCryptoResult {
  50 public:
  51     WebCryptoResult(const WebCryptoResult& o)
  52     {
  53         assign(o);
  54     }
  55
  56     ~WebCryptoResult()
  57     {
  58         reset();
  59     }
  60
  61     WebCryptoResult& operator=(const WebCryptoResult& o)
  62     {
  63         assign(o);
  64         return *this;
  65     }
  66
  67     BLINK_PLATFORM_EXPORT void completeWithError();
  68
  69     // Note that WebString is NOT safe to pass across threads.
  70     //
  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&);
  76
  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);
  84
  85 #if INSIDE_BLINK
  86     BLINK_PLATFORM_EXPORT explicit WebCryptoResult(const WTF::PassRefPtr<WebCore::CryptoResult>&);
  87 #endif
  88
  89 private:
  90     BLINK_PLATFORM_EXPORT void reset();
  91     BLINK_PLATFORM_EXPORT void assign(const WebCryptoResult&);
  92
  93     WebPrivatePtr<WebCore::CryptoResult> m_impl;
  94 };
  95
  96 class WebCrypto {
  97 public:
  98     // WebCrypto is the interface for starting one-shot cryptographic
  99     // operations.
 100     //
 101     // -----------------------
 102     // Completing the request
 103     // -----------------------
 104     //
 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.
 109     //
 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.
 114     //
 115     // -----------------------
 116     // Threading
 117     // -----------------------
 118     //
 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.
 121     // Notably:
 122     //
 123     //   * The WebCryptoResult is NOT threadsafe. It should only be used from
 124     //     the Blink main thread.
 125     //
 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.
 129     //
 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.
 133     //
 134     // -----------------------
 135     // Inputs
 136     // -----------------------
 137     //
 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.
 142     //
 143     //   * All WebCryptoKeys are guaranteeed to be !isNull().
 144     //
 145     //   * All WebCryptoAlgorithms are guaranteed to be !isNull()
 146     //     unless noted otherwise. Being "null" means that it was unspecified
 147     //     by the caller.
 148     //
 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".
 153     //
 154     // -----------------------
 155     // Guarantees on input validity
 156     // -----------------------
 157     //
 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.
 161     //
 162     // Only the following checks can be assumed as having alread passed:
 163     //
 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.
 167     //
 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(); }
 180
 181 protected:
 182     virtual ~WebCrypto() { }
 183 };
 184
 185 } // namespace blink
 186
 187 #endif