15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Utility class for calculating the HMAC for a given message. We currently 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// only support SHA1 for the hash algorithm, but this can be extended easily. 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef CRYPTO_HMAC_H_ 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define CRYPTO_HMAC_H_ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/compiler_specific.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/memory/scoped_ptr.h" 14c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "base/strings/string_piece.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "crypto/crypto_export.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace crypto { 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Simplify the interface and reduce includes by abstracting out the internals. 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)struct HMACPlatformData; 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class SymmetricKey; 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CRYPTO_EXPORT HMAC { 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The set of supported hash functions. Extend as required. 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum HashAlgorithm { 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) SHA1, 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) SHA256, 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit HMAC(HashAlgorithm hash_alg); 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ~HMAC(); 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the length of digest that this HMAC will create. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) size_t DigestLength() const; 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(abarth): Add a PreferredKeyLength() member function. 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Initializes this instance using |key| of the length |key_length|. Call Init 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // only once. It returns false on the second or later calls. 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NOTE: the US Federal crypto standard FIPS 198, Section 3 says: 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The size of the key, K, shall be equal to or greater than L/2, where L 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // is the size of the hash function output. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // In FIPS 198-1 (and SP-800-107, which describes key size recommendations), 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this requirement is gone. But a system crypto library may still enforce 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // this old requirement. If the key is shorter than this recommended value, 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Init() may fail. 492a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) bool Init(const unsigned char* key, size_t key_length) WARN_UNUSED_RESULT; 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Initializes this instance using |key|. Call Init 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // only once. It returns false on the second or later calls. 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool Init(SymmetricKey* key) WARN_UNUSED_RESULT; 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Initializes this instance using |key|. Call Init only once. It returns 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // false on the second or later calls. 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool Init(const base::StringPiece& key) WARN_UNUSED_RESULT { 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return Init(reinterpret_cast<const unsigned char*>(key.data()), 592a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) key.size()); 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Calculates the HMAC for the message in |data| using the algorithm supplied 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to the constructor and the key supplied to the Init method. The HMAC is 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // returned in |digest|, which has |digest_length| bytes of storage available. 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool Sign(const base::StringPiece& data, unsigned char* digest, 662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) size_t digest_length) const WARN_UNUSED_RESULT; 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Verifies that the HMAC for the message in |data| equals the HMAC provided 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in |digest|, using the algorithm supplied to the constructor and the key 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // supplied to the Init method. Use of this method is strongly recommended 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // over using Sign() with a manual comparison (such as memcmp), as such 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // comparisons may result in side-channel disclosures, such as timing, that 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // undermine the cryptographic integrity. |digest| must be exactly 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |DigestLength()| bytes long. 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool Verify(const base::StringPiece& data, 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const base::StringPiece& digest) const WARN_UNUSED_RESULT; 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Verifies a truncated HMAC, behaving identical to Verify(), except 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // that |digest| is allowed to be smaller than |DigestLength()|. 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool VerifyTruncated( 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const base::StringPiece& data, 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const base::StringPiece& digest) const WARN_UNUSED_RESULT; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) HashAlgorithm hash_alg_; 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_ptr<HMACPlatformData> plat_; 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(HMAC); 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace crypto 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // CRYPTO_HMAC_H_ 94