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