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 // base::StringPiece 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 <vector> 17 18 #include "base/containers/span.h" 19 #include "base/strings/string_piece.h" 20 #include "crypto/crypto_export.h" 21 22 namespace crypto { 23 24 // Simplify the interface and reduce includes by abstracting out the internals. 25 class SymmetricKey; 26 27 class CRYPTO_EXPORT HMAC { 28 public: 29 // The set of supported hash functions. Extend as required. 30 enum HashAlgorithm { 31 SHA1, 32 SHA256, 33 }; 34 35 explicit HMAC(HashAlgorithm hash_alg); 36 37 HMAC(const HMAC&) = delete; 38 HMAC& operator=(const HMAC&) = delete; 39 40 ~HMAC(); 41 42 // Returns the length of digest that this HMAC will create. 43 size_t DigestLength() const; 44 45 // TODO(abarth): Add a PreferredKeyLength() member function. 46 47 // Initializes this instance using |key| of the length |key_length|. Call Init 48 // only once. It returns false on the second or later calls. 49 // 50 // NOTE: the US Federal crypto standard FIPS 198, Section 3 says: 51 // The size of the key, K, shall be equal to or greater than L/2, where L 52 // is the size of the hash function output. 53 // In FIPS 198-1 (and SP-800-107, which describes key size recommendations), 54 // this requirement is gone. But a system crypto library may still enforce 55 // this old requirement. If the key is shorter than this recommended value, 56 // Init() may fail. 57 [[nodiscard]] bool Init(const unsigned char* key, size_t key_length); 58 59 // Initializes this instance using |key|. Call Init 60 // only once. It returns false on the second or later calls. 61 [[nodiscard]] bool Init(const SymmetricKey* key); 62 63 // Initializes this instance using |key|. Call Init only once. It returns 64 // false on the second or later calls. Init(base::StringPiece key)65 [[nodiscard]] bool Init(base::StringPiece key) { 66 return Init(base::as_bytes(base::make_span(key))); 67 } 68 69 // Initializes this instance using |key|. Call Init only once. It returns 70 // false on the second or later calls. Init(base::span<const uint8_t> key)71 [[nodiscard]] bool Init(base::span<const uint8_t> key) { 72 return Init(key.data(), key.size()); 73 } 74 75 // Calculates the HMAC for the message in |data| using the algorithm supplied 76 // to the constructor and the key supplied to the Init method. The HMAC is 77 // returned in |digest|, which has |digest_length| bytes of storage available. 78 // If |digest_length| is smaller than DigestLength(), the output will be 79 // truncated. If it is larger, this method will fail. 80 [[nodiscard]] bool Sign(base::StringPiece data, 81 unsigned char* digest, 82 size_t digest_length) const; 83 [[nodiscard]] bool Sign(base::span<const uint8_t> data, 84 base::span<uint8_t> digest) const; 85 86 // Verifies that the HMAC for the message in |data| equals the HMAC provided 87 // in |digest|, using the algorithm supplied to the constructor and the key 88 // supplied to the Init method. Use of this method is strongly recommended 89 // over using Sign() with a manual comparison (such as memcmp), as such 90 // comparisons may result in side-channel disclosures, such as timing, that 91 // undermine the cryptographic integrity. |digest| must be exactly 92 // |DigestLength()| bytes long. 93 [[nodiscard]] bool Verify(base::StringPiece data, 94 base::StringPiece digest) const; 95 [[nodiscard]] bool Verify(base::span<const uint8_t> data, 96 base::span<const uint8_t> digest) const; 97 98 // Verifies a truncated HMAC, behaving identical to Verify(), except 99 // that |digest| is allowed to be smaller than |DigestLength()|. 100 [[nodiscard]] bool VerifyTruncated(base::StringPiece data, 101 base::StringPiece digest) const; 102 [[nodiscard]] bool VerifyTruncated(base::span<const uint8_t> data, 103 base::span<const uint8_t> digest) const; 104 105 private: 106 HashAlgorithm hash_alg_; 107 bool initialized_; 108 std::vector<unsigned char> key_; 109 }; 110 111 } // namespace crypto 112 113 #endif // CRYPTO_HMAC_H_ 114