components/webcrypto/webcrypto_util.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 COMPONENTS_WEBCRYPTO_WEBCRYPTO_UTIL_H_
   6 #define COMPONENTS_WEBCRYPTO_WEBCRYPTO_UTIL_H_
   7
   8 #include <stdint.h>
   9 #include <string>
  10
  11 #include "base/values.h"
  12 #include "third_party/WebKit/public/platform/WebCryptoAlgorithm.h"
  13 #include "third_party/WebKit/public/platform/WebCryptoKey.h"
  14
  15 namespace webcrypto {
  16
  17 class Status;
  18
  19 // Creates a WebCryptoAlgorithm without any parameters.
  20 blink::WebCryptoAlgorithm CreateAlgorithm(blink::WebCryptoAlgorithmId id);
  21
  22 // Creates an HMAC import algorithm whose inner hash algorithm is determined by
  23 // the specified algorithm ID. It is an error to call this method with a hash
  24 // algorithm that is not SHA*.
  25 blink::WebCryptoAlgorithm CreateHmacImportAlgorithm(
  26     blink::WebCryptoAlgorithmId hash_id,
  27     unsigned int length_bits);
  28
  29 // Same as above but without specifying a length.
  30 blink::WebCryptoAlgorithm CreateHmacImportAlgorithmNoLength(
  31     blink::WebCryptoAlgorithmId hash_id);
  32
  33 // Creates an import algorithm for RSA algorithms that take a hash.
  34 // It is an error to call this with a hash_id that is not a SHA*.
  35 blink::WebCryptoAlgorithm CreateRsaHashedImportAlgorithm(
  36     blink::WebCryptoAlgorithmId id,
  37     blink::WebCryptoAlgorithmId hash_id);
  38
  39 // Creates an import algorithm for EC keys.
  40 blink::WebCryptoAlgorithm CreateEcImportAlgorithm(
  41     blink::WebCryptoAlgorithmId id,
  42     blink::WebCryptoNamedCurve named_curve);
  43
  44 // Returns true if the set bits in b make up a subset of the set bits in a.
  45 bool ContainsKeyUsages(blink::WebCryptoKeyUsageMask a,
  46                        blink::WebCryptoKeyUsageMask b);
  47
  48 bool KeyUsageAllows(const blink::WebCryptoKey& key,
  49                     const blink::WebCryptoKeyUsage usage);
  50
  51 Status GetAesGcmTagLengthInBits(const blink::WebCryptoAesGcmParams* params,
  52                                 unsigned int* tag_length_bits);
  53
  54 Status GetAesKeyGenLengthInBits(const blink::WebCryptoAesKeyGenParams* params,
  55                                 unsigned int* keylen_bits);
  56
  57 Status GetHmacKeyGenLengthInBits(const blink::WebCryptoHmacKeyGenParams* params,
  58                                  unsigned int* keylen_bits);
  59
  60 // Gets the requested key length in bits for an HMAC import operation.
  61 Status GetHmacImportKeyLengthBits(
  62     const blink::WebCryptoHmacImportParams* params,
  63     unsigned int key_data_byte_length,
  64     unsigned int* keylen_bits);
  65
  66 Status VerifyAesKeyLengthForImport(unsigned int keylen_bytes);
  67
  68 Status CheckKeyCreationUsages(blink::WebCryptoKeyUsageMask all_possible_usages,
  69                               blink::WebCryptoKeyUsageMask actual_usages,
  70                               bool allow_empty_usages);
  71
  72 // Extracts the public exponent and modulus length from the Blink parameters.
  73 // On success it is guaranteed that:
  74 //   * public_exponent is either 3 or 65537
  75 //   * modulus_length_bits is a multiple of 8
  76 //   * modulus_length is >= 256
  77 //   * modulus_length is <= 16K
  78 Status GetRsaKeyGenParameters(
  79     const blink::WebCryptoRsaHashedKeyGenParams* params,
  80     unsigned int* public_exponent,
  81     unsigned int* modulus_length_bits);
  82
  83 // Verifies that |usages| is valid when importing a key of the given format.
  84 Status VerifyUsagesBeforeImportAsymmetricKey(
  85     blink::WebCryptoKeyFormat format,
  86     blink::WebCryptoKeyUsageMask all_public_key_usages,
  87     blink::WebCryptoKeyUsageMask all_private_key_usages,
  88     blink::WebCryptoKeyUsageMask usages);
  89
  90 // Truncates an octet string to a particular bit length. This is accomplished by
  91 // resizing to the closest byte length, and then zero-ing the unused
  92 // least-significant bits of the final byte.
  93 //
  94 // It is an error to call this function with a bit length that is larger than
  95 // that of |bytes|.
  96 //
  97 // TODO(eroman): This operation is not yet defined by the WebCrypto spec,
  98 // however this is a reasonable interpretation:
  99 // https://www.w3.org/Bugs/Public/show_bug.cgi?id=27402
 100 void TruncateToBitLength(size_t length_bits, std::vector<uint8_t>* bytes);
 101
 102 // Rounds a bit count (up) to the nearest byte count.
 103 //
 104 // This is mathematically equivalent to (x + 7) / 8, however has no
 105 // possibility of integer overflow.
 106 template <typename T>
 107 T NumBitsToBytes(T x) {
 108   return (x / 8) + (7 + (x % 8)) / 8;
 109 }
 110
 111 // The "get key length" operation for AES keys.
 112 Status GetAesKeyLength(const blink::WebCryptoAlgorithm& key_length_algorithm,
 113                        bool* has_length_bits,
 114                        unsigned int* length_bits);
 115
 116 // The "get key length" operation for HMAC keys.
 117 Status GetHmacKeyLength(const blink::WebCryptoAlgorithm& key_length_algorithm,
 118                         bool* has_length_bits,
 119                         unsigned int* length_bits);
 120
 121 // Splits the combined usages given to GenerateKey() into the respective usages
 122 // for the public key and private key. Returns an error if the usages are
 123 // invalid.
 124 Status GetUsagesForGenerateAsymmetricKey(
 125     blink::WebCryptoKeyUsageMask combined_usages,
 126     blink::WebCryptoKeyUsageMask all_public_usages,
 127     blink::WebCryptoKeyUsageMask all_private_usages,
 128     blink::WebCryptoKeyUsageMask* public_usages,
 129     blink::WebCryptoKeyUsageMask* private_usages);
 130
 131 }  // namespace webcrypto
 132
 133 #endif  // COMPONENTS_WEBCRYPTO_WEBCRYPTO_UTIL_H_