1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // Utility class for calculating the HMAC for a given message. We currently only 6 // support SHA-1 and SHA-256 for the hash algorithm, but this can be extended 7 // easily. Prefer the base::span and std::vector overloads over the 8 // std::string_view and std::string overloads. 9 10 #ifndef CRYPTO_HMAC_H_ 11 #define CRYPTO_HMAC_H_ 12 13 #include <stddef.h> 14 15 #include <memory> 16 #include <string_view> 17 #include <vector> 18 19 #include "base/containers/span.h" 20 #include "crypto/crypto_export.h" 21 #include "crypto/hash.h" 22 23 namespace crypto { 24 25 // Simplify the interface and reduce includes by abstracting out the internals. 26 class SymmetricKey; 27 28 // TODO(https://issues.chromium.org/issues/374334448): Rework this interface and 29 // delete much of it. 30 class CRYPTO_EXPORT HMAC { 31 public: 32 // The set of supported hash functions. Extend as required. 33 enum HashAlgorithm { 34 SHA1, 35 SHA256, 36 }; 37 38 explicit HMAC(HashAlgorithm hash_alg); 39 40 HMAC(const HMAC&) = delete; 41 HMAC& operator=(const HMAC&) = delete; 42 43 ~HMAC(); 44 45 // Returns the length of digest that this HMAC will create. 46 size_t DigestLength() const; 47 48 // TODO(abarth): Add a PreferredKeyLength() member function. 49 50 // Initializes this instance using |key| of the length |key_length|. Call Init 51 // only once. It returns false on the second or later calls. 52 // 53 // NOTE: the US Federal crypto standard FIPS 198, Section 3 says: 54 // The size of the key, K, shall be equal to or greater than L/2, where L 55 // is the size of the hash function output. 56 // In FIPS 198-1 (and SP-800-107, which describes key size recommendations), 57 // this requirement is gone. But a system crypto library may still enforce 58 // this old requirement. If the key is shorter than this recommended value, 59 // Init() may fail. 60 [[nodiscard]] bool Init(const unsigned char* key, size_t key_length); 61 62 // Initializes this instance using |key|. Call Init 63 // only once. It returns false on the second or later calls. 64 [[nodiscard]] bool Init(const SymmetricKey* key); 65 66 // Initializes this instance using |key|. Call Init only once. It returns 67 // false on the second or later calls. Init(std::string_view key)68 [[nodiscard]] bool Init(std::string_view key) { 69 return Init(base::as_byte_span(key)); 70 } 71 72 // Initializes this instance using |key|. Call Init only once. It returns 73 // false on the second or later calls. Init(base::span<const uint8_t> key)74 [[nodiscard]] bool Init(base::span<const uint8_t> key) { 75 return Init(key.data(), key.size()); 76 } 77 78 // Calculates the HMAC for the message in |data| using the algorithm supplied 79 // to the constructor and the key supplied to the Init method. The HMAC is 80 // returned in |digest|, which has |digest_length| bytes of storage available. 81 // If |digest_length| is smaller than DigestLength(), the output will be 82 // truncated. If it is larger, this method will fail. 83 [[nodiscard]] bool Sign(std::string_view data, 84 unsigned char* digest, 85 size_t digest_length) const; 86 [[nodiscard]] bool Sign(base::span<const uint8_t> data, 87 base::span<uint8_t> digest) const; 88 89 // Verifies that the HMAC for the message in |data| equals the HMAC provided 90 // in |digest|, using the algorithm supplied to the constructor and the key 91 // supplied to the Init method. Use of this method is strongly recommended 92 // over using Sign() with a manual comparison (such as memcmp), as such 93 // comparisons may result in side-channel disclosures, such as timing, that 94 // undermine the cryptographic integrity. |digest| must be exactly 95 // |DigestLength()| bytes long. 96 [[nodiscard]] bool Verify(std::string_view data, 97 std::string_view digest) const; 98 [[nodiscard]] bool Verify(base::span<const uint8_t> data, 99 base::span<const uint8_t> digest) const; 100 101 // Verifies a truncated HMAC, behaving identical to Verify(), except 102 // that |digest| is allowed to be smaller than |DigestLength()|. 103 [[nodiscard]] bool VerifyTruncated(std::string_view data, 104 std::string_view digest) const; 105 [[nodiscard]] bool VerifyTruncated(base::span<const uint8_t> data, 106 base::span<const uint8_t> digest) const; 107 108 private: 109 HashAlgorithm hash_alg_; 110 bool initialized_; 111 std::vector<unsigned char> key_; 112 }; 113 114 namespace hmac { 115 116 // Single-shot interfaces for working with HMACs. Unless your code needs to be 117 // generic over hash kinds, you should use the convenience interfaces that are 118 // named after a specific kind, since they allow compile-time error checking of 119 // the hmac size. 120 CRYPTO_EXPORT std::array<uint8_t, crypto::hash::kSha1Size> SignSha1( 121 base::span<const uint8_t> key, 122 base::span<const uint8_t> data); 123 124 CRYPTO_EXPORT std::array<uint8_t, crypto::hash::kSha256Size> SignSha256( 125 base::span<const uint8_t> key, 126 base::span<const uint8_t> data); 127 128 CRYPTO_EXPORT std::array<uint8_t, crypto::hash::kSha512Size> SignSha512( 129 base::span<const uint8_t> key, 130 base::span<const uint8_t> data); 131 132 [[nodiscard]] CRYPTO_EXPORT bool VerifySha1( 133 base::span<const uint8_t> key, 134 base::span<const uint8_t> data, 135 base::span<const uint8_t, crypto::hash::kSha1Size> hmac); 136 137 [[nodiscard]] CRYPTO_EXPORT bool VerifySha256( 138 base::span<const uint8_t> key, 139 base::span<const uint8_t> data, 140 base::span<const uint8_t, crypto::hash::kSha256Size> hmac); 141 142 [[nodiscard]] CRYPTO_EXPORT bool VerifySha512( 143 base::span<const uint8_t> key, 144 base::span<const uint8_t> data, 145 base::span<const uint8_t, crypto::hash::kSha512Size> hmac); 146 147 // If you need to be generic over hash types, you can instead use these, but you 148 // must pass the correct size buffer for |hmac|: 149 CRYPTO_EXPORT void Sign(crypto::hash::HashKind kind, 150 base::span<const uint8_t> key, 151 base::span<const uint8_t> data, 152 base::span<uint8_t> hmac); 153 [[nodiscard]] CRYPTO_EXPORT bool Verify(crypto::hash::HashKind kind, 154 base::span<const uint8_t> key, 155 base::span<const uint8_t> data, 156 base::span<const uint8_t> hmac); 157 158 } // namespace hmac 159 160 } // namespace crypto 161 162 #endif // CRYPTO_HMAC_H_ 163