src/content/child/webcrypto/platform_crypto.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CONTENT_CHILD_WEBCRYPTO_PLATFORM_CRYPTO_H_
   6 #define CONTENT_CHILD_WEBCRYPTO_PLATFORM_CRYPTO_H_
   7
   8 #include <vector>
   9
  10 #include "base/basictypes.h"
  11 #include "base/compiler_specific.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "third_party/WebKit/public/platform/WebCrypto.h"
  14 #include "third_party/WebKit/public/platform/WebCryptoAlgorithmParams.h"
  15
  16 namespace blink {
  17 template <typename T>
  18 class WebVector;
  19 }
  20
  21 namespace content {
  22
  23 enum EncryptOrDecrypt { ENCRYPT, DECRYPT };
  24
  25 namespace webcrypto {
  26
  27 class CryptoData;
  28 class Status;
  29
  30 // Functions in the webcrypto::platform namespace are intended to be those
  31 // which are OpenSSL/NSS specific.
  32 //
  33 // The general purpose code which applies to both OpenSSL and NSS
  34 // implementations of webcrypto should live in the outter webcrypto namespace,
  35 // and the crypto library specific bits in the "platform" namespace.
  36 //
  37 // -----------------
  38 // Threading:
  39 // -----------------
  40 //
  41 // Unless otherwise noted, functions in webcrypto::platform are called
  42 // exclusively from a sequenced worker pool.
  43 //
  44 // This means that operations using a given key cannot occur in
  45 // parallel and it is not necessary to guard against concurrent usage.
  46 //
  47 // The exceptions are:
  48 //
  49 //   * Key::ThreadSafeSerializeForClone(), which is called from the
  50 //     target Blink thread during structured clone.
  51 //
  52 //   * ImportKeyRaw(), ImportKeySpki(), ImportKeyPkcs8(), which can be
  53 //     called from the target Blink thread during structured clone
  54 //     deserialization, as well as from the webcrypto worker pool.
  55 //
  56 //     TODO(eroman): Change it so import happens in worker pool too.
  57 //                   http://crbug.com/366834
  58 namespace platform {
  59
  60 class SymKey;
  61 class PublicKey;
  62 class PrivateKey;
  63
  64 // Base key class for all platform keys, used to safely cast between types.
  65 class Key : public blink::WebCryptoKeyHandle {
  66  public:
  67   virtual SymKey* AsSymKey() = 0;
  68   virtual PublicKey* AsPublicKey() = 0;
  69   virtual PrivateKey* AsPrivateKey() = 0;
  70
  71   virtual bool ThreadSafeSerializeForClone(
  72       blink::WebVector<uint8>* key_data) = 0;
  73 };
  74
  75 // Do any one-time initialization. Note that this can be called MULTIPLE times
  76 // (once per instantiation of WebCryptoImpl).
  77 void Init();
  78
  79 // Preconditions:
  80 //  * |key| is a non-null AES-CBC key.
  81 //  * |iv| is exactly 16 bytes long
  82 Status EncryptDecryptAesCbc(EncryptOrDecrypt mode,
  83                             SymKey* key,
  84                             const CryptoData& data,
  85                             const CryptoData& iv,
  86                             std::vector<uint8>* buffer);
  87
  88 // Preconditions:
  89 //  * |key| is a non-null AES-GCM key.
  90 //  * |tag_length_bits| is one of {32, 64, 96, 104, 112, 120, 128}
  91 Status EncryptDecryptAesGcm(EncryptOrDecrypt mode,
  92                             SymKey* key,
  93                             const CryptoData& data,
  94                             const CryptoData& iv,
  95                             const CryptoData& additional_data,
  96                             unsigned int tag_length_bits,
  97                             std::vector<uint8>* buffer);
  98
  99 // Preconditions:
 100 //  * |key| is non-null.
 101 //  * |data| is not empty.
 102 Status EncryptRsaEsPkcs1v1_5(PublicKey* key,
 103                              const CryptoData& data,
 104                              std::vector<uint8>* buffer);
 105
 106 // Preconditions:
 107 //  * |key| is non-null.
 108 Status DecryptRsaEsPkcs1v1_5(PrivateKey* key,
 109                              const CryptoData& data,
 110                              std::vector<uint8>* buffer);
 111
 112 // Preconditions:
 113 //  * |key| is a non-null HMAC key.
 114 //  * |hash| is a digest algorithm.
 115 Status SignHmac(SymKey* key,
 116                 const blink::WebCryptoAlgorithm& hash,
 117                 const CryptoData& data,
 118                 std::vector<uint8>* buffer);
 119
 120 // Preconditions:
 121 //  * |algorithm| is a SHA function.
 122 Status DigestSha(blink::WebCryptoAlgorithmId algorithm,
 123                  const CryptoData& data,
 124                  std::vector<uint8>* buffer);
 125
 126 // Preconditions:
 127 //  * |algorithm| is a SHA function.
 128 scoped_ptr<blink::WebCryptoDigestor> CreateDigestor(
 129     blink::WebCryptoAlgorithmId algorithm);
 130
 131 // Preconditions:
 132 //  * |key| is non-null.
 133 //  * |hash| is a digest algorithm.
 134 Status SignRsaSsaPkcs1v1_5(PrivateKey* key,
 135                            const blink::WebCryptoAlgorithm& hash,
 136                            const CryptoData& data,
 137                            std::vector<uint8>* buffer);
 138
 139 // Preconditions:
 140 //  * |key| is non-null.
 141 //  * |hash| is a digest algorithm.
 142 Status VerifyRsaSsaPkcs1v1_5(PublicKey* key,
 143                              const blink::WebCryptoAlgorithm& hash,
 144                              const CryptoData& signature,
 145                              const CryptoData& data,
 146                              bool* signature_match);
 147
 148 // |keylen_bytes| is the desired length of the key in bits.
 149 //
 150 // Preconditions:
 151 //  * algorithm.id() is for a symmetric key algorithm.
 152 //  * keylen_bytes is non-zero (TODO(eroman): revisit this).
 153 //  * For AES algorithms |keylen_bytes| is either 16, 24, or 32 bytes long.
 154 Status GenerateSecretKey(const blink::WebCryptoAlgorithm& algorithm,
 155                          bool extractable,
 156                          blink::WebCryptoKeyUsageMask usage_mask,
 157                          unsigned keylen_bytes,
 158                          blink::WebCryptoKey* key);
 159
 160 // Preconditions:
 161 //  * algorithm.id() is for an RSA algorithm.
 162 //  * public_exponent, modulus_length_bits and hash_or_null are the same as what
 163 //    is in algorithm. They are split out for convenience.
 164 //  * hash_or_null.isNull() may be true if a hash is not applicable to the
 165 //    algorithm
 166 //  * modulus_length_bits is not 0
 167 //  * public_exponent is not empty.
 168 Status GenerateRsaKeyPair(const blink::WebCryptoAlgorithm& algorithm,
 169                           bool extractable,
 170                           blink::WebCryptoKeyUsageMask usage_mask,
 171                           unsigned int modulus_length_bits,
 172                           const CryptoData& public_exponent,
 173                           const blink::WebCryptoAlgorithm& hash,
 174                           blink::WebCryptoKey* public_key,
 175                           blink::WebCryptoKey* private_key);
 176
 177 // Preconditions:
 178 //  * |key| is non-null.
 179 //  * |algorithm.id()| is for a symmetric key algorithm.
 180 //  * For AES algorithms |key_data| is either 16, 24, or 32 bytes long.
 181 // Note that this may be called from target Blink thread.
 182 Status ImportKeyRaw(const blink::WebCryptoAlgorithm& algorithm,
 183                     const CryptoData& key_data,
 184                     bool extractable,
 185                     blink::WebCryptoKeyUsageMask usage_mask,
 186                     blink::WebCryptoKey* key);
 187
 188 // Preconditions:
 189 //  * algorithm.id() is for an RSA algorithm.
 190 Status ImportRsaPublicKey(const blink::WebCryptoAlgorithm& algorithm,
 191                           bool extractable,
 192                           blink::WebCryptoKeyUsageMask usage_mask,
 193                           const CryptoData& modulus_data,
 194                           const CryptoData& exponent_data,
 195                           blink::WebCryptoKey* key);
 196
 197 // Note that this may be called from target Blink thread.
 198 Status ImportKeySpki(const blink::WebCryptoAlgorithm& algorithm,
 199                      const CryptoData& key_data,
 200                      bool extractable,
 201                      blink::WebCryptoKeyUsageMask usage_mask,
 202                      blink::WebCryptoKey* key);
 203
 204 // Note that this may be called from target Blink thread.
 205 Status ImportKeyPkcs8(const blink::WebCryptoAlgorithm& algorithm,
 206                       const CryptoData& key_data,
 207                       bool extractable,
 208                       blink::WebCryptoKeyUsageMask usage_mask,
 209                       blink::WebCryptoKey* key);
 210
 211 // Preconditions:
 212 //  * |key| is non-null.
 213 Status ExportKeyRaw(SymKey* key, std::vector<uint8>* buffer);
 214
 215 // Preconditions:
 216 //  * |key| is non-null.
 217 Status ExportKeySpki(PublicKey* key, std::vector<uint8>* buffer);
 218
 219 // Preconditions:
 220 //  * |key| is non-null.
 221 Status ExportRsaPublicKey(PublicKey* key,
 222                           std::vector<uint8>* modulus,
 223                           std::vector<uint8>* public_exponent);
 224
 225 // Preconditions:
 226 //  * |key| is non-null.
 227 Status ExportKeyPkcs8(PrivateKey* key,
 228                       const blink::WebCryptoKeyAlgorithm& key_algorithm,
 229                       std::vector<uint8>* buffer);
 230
 231 // Preconditions:
 232 //  * |wrapping_key| is non-null
 233 //  * |key| is non-null
 234 Status WrapSymKeyAesKw(SymKey* wrapping_key,
 235                        SymKey* key,
 236                        std::vector<uint8>* buffer);
 237
 238 // Unwraps (decrypts) |wrapped_key_data| using AES-KW and places the results in
 239 // a WebCryptoKey. Raw key data remains inside NSS. This function should be used
 240 // when the input |wrapped_key_data| is known to result in symmetric raw key
 241 // data after AES-KW decryption.
 242 // Preconditions:
 243 //  * |wrapping_key| is non-null
 244 //  * |key| is non-null
 245 //  * |wrapped_key_data| is at least 24 bytes and a multiple of 8 bytes
 246 //  * |algorithm.id()| is for a symmetric key algorithm.
 247 Status UnwrapSymKeyAesKw(const CryptoData& wrapped_key_data,
 248                          SymKey* wrapping_key,
 249                          const blink::WebCryptoAlgorithm& algorithm,
 250                          bool extractable,
 251                          blink::WebCryptoKeyUsageMask usage_mask,
 252                          blink::WebCryptoKey* key);
 253
 254 // Performs AES-KW decryption on the input |data|. This function should be used
 255 // when the input |data| does not directly represent a key and should instead be
 256 // interpreted as generic bytes.
 257 // Preconditions:
 258 //  * |key| is non-null
 259 //  * |data| is at least 24 bytes and a multiple of 8 bytes
 260 //  * |buffer| is non-null.
 261 Status DecryptAesKw(SymKey* key,
 262                     const CryptoData& data,
 263                     std::vector<uint8>* buffer);
 264
 265 // Preconditions:
 266 //  * |wrapping_key| is non-null
 267 //  * |key| is non-null
 268 Status WrapSymKeyRsaEs(PublicKey* wrapping_key,
 269                        SymKey* key,
 270                        std::vector<uint8>* buffer);
 271
 272 // Preconditions:
 273 //  * |wrapping_key| is non-null
 274 //  * |key| is non-null
 275 //  * |algorithm.id()| is for a symmetric key algorithm.
 276 Status UnwrapSymKeyRsaEs(const CryptoData& wrapped_key_data,
 277                          PrivateKey* wrapping_key,
 278                          const blink::WebCryptoAlgorithm& algorithm,
 279                          bool extractable,
 280                          blink::WebCryptoKeyUsageMask usage_mask,
 281                          blink::WebCryptoKey* key);
 282
 283 }  // namespace platform
 284
 285 }  // namespace webcrypto
 286
 287 }  // namespace content
 288
 289 #endif  // CONTENT_CHILD_WEBCRYPTO_PLATFORM_CRYPTO_H_