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