Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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" |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 14 | #include "base/strings/string_piece.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 49 | bool Init(const unsigned char* key, size_t key_length) WARN_UNUSED_RESULT; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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()), |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 59 | key.size()); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 65 | bool Sign(const base::StringPiece& data, unsigned char* digest, |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 66 | size_t digest_length) const WARN_UNUSED_RESULT; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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_ |