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 Status GetAesGcmTagLengthInBits(const blink::WebCryptoAesGcmParams* params,
  49                                 unsigned int* tag_length_bits);
  50
  51 Status GetAesKeyGenLengthInBits(const blink::WebCryptoAesKeyGenParams* params,
  52                                 unsigned int* keylen_bits);
  53
  54 Status GetHmacKeyGenLengthInBits(const blink::WebCryptoHmacKeyGenParams* params,
  55                                  unsigned int* keylen_bits);
  56
  57 // Gets the requested key length in bits for an HMAC import operation.
  58 Status GetHmacImportKeyLengthBits(
  59     const blink::WebCryptoHmacImportParams* params,
  60     unsigned int key_data_byte_length,
  61     unsigned int* keylen_bits);
  62
  63 Status VerifyAesKeyLengthForImport(unsigned int keylen_bytes);
  64
  65 Status CheckKeyCreationUsages(blink::WebCryptoKeyUsageMask all_possible_usages,
  66                               blink::WebCryptoKeyUsageMask actual_usages,
  67                               bool allow_empty_usages);
  68
  69 // Extracts the public exponent and modulus length from the Blink parameters.
  70 // On success it is guaranteed that:
  71 //   * public_exponent is either 3 or 65537
  72 //   * modulus_length_bits is a multiple of 8
  73 //   * modulus_length is >= 256
  74 //   * modulus_length is <= 16K
  75 Status GetRsaKeyGenParameters(
  76     const blink::WebCryptoRsaHashedKeyGenParams* params,
  77     unsigned int* public_exponent,
  78     unsigned int* modulus_length_bits);
  79
  80 // Verifies that |usages| is valid when importing a key of the given format.
  81 Status VerifyUsagesBeforeImportAsymmetricKey(
  82     blink::WebCryptoKeyFormat format,
  83     blink::WebCryptoKeyUsageMask all_public_key_usages,
  84     blink::WebCryptoKeyUsageMask all_private_key_usages,
  85     blink::WebCryptoKeyUsageMask usages);
  86
  87 // Truncates an octet string to a particular bit length. This is accomplished by
  88 // resizing to the closest byte length, and then zero-ing the unused
  89 // least-significant bits of the final byte.
  90 //
  91 // It is an error to call this function with a bit length that is larger than
  92 // that of |bytes|.
  93 //
  94 // TODO(eroman): This operation is not yet defined by the WebCrypto spec,
  95 // however this is a reasonable interpretation:
  96 // https://www.w3.org/Bugs/Public/show_bug.cgi?id=27402
  97 void TruncateToBitLength(size_t length_bits, std::vector<uint8_t>* bytes);
  98
  99 // Rounds a bit count (up) to the nearest byte count.
 100 //
 101 // This is mathematically equivalent to (x + 7) / 8, however has no
 102 // possibility of integer overflow.
 103 template <typename T>
 104 T NumBitsToBytes(T x) {
 105   return (x / 8) + (7 + (x % 8)) / 8;
 106 }
 107
 108 // The "get key length" operation for AES keys.
 109 Status GetAesKeyLength(const blink::WebCryptoAlgorithm& key_length_algorithm,
 110                        bool* has_length_bits,
 111                        unsigned int* length_bits);
 112
 113 // The "get key length" operation for HMAC keys.
 114 Status GetHmacKeyLength(const blink::WebCryptoAlgorithm& key_length_algorithm,
 115                         bool* has_length_bits,
 116                         unsigned int* length_bits);
 117
 118 // Splits the combined usages given to GenerateKey() into the respective usages
 119 // for the public key and private key. Returns an error if the usages are
 120 // invalid.
 121 Status GetUsagesForGenerateAsymmetricKey(
 122     blink::WebCryptoKeyUsageMask combined_usages,
 123     blink::WebCryptoKeyUsageMask all_public_usages,
 124     blink::WebCryptoKeyUsageMask all_private_usages,
 125     blink::WebCryptoKeyUsageMask* public_usages,
 126     blink::WebCryptoKeyUsageMask* private_usages);
 127
 128 }  // namespace webcrypto
 129
 130 #endif  // COMPONENTS_WEBCRYPTO_WEBCRYPTO_UTIL_H_