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