crypto/hmac.h

   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/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_