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   // TODO(abarth): key_length should be a size_t.
  42   //
  43   // NOTE: the US Federal crypto standard FIPS 198, Section 3 says:
  44   //   The size of the key, K, shall be equal to or greater than L/2, where L
  45   //   is the size of the hash function output.
  46   // In FIPS 198-1 (and SP-800-107, which describes key size recommendations),
  47   // this requirement is gone.  But a system crypto library may still enforce
  48   // this old requirement.  If the key is shorter than this recommended value,
  49   // Init() may fail.
  50   bool Init(const unsigned char* key, int key_length) WARN_UNUSED_RESULT;
  51
  52   // Initializes this instance using |key|. Call Init
  53   // only once. It returns false on the second or later calls.
  54   bool Init(SymmetricKey* key) WARN_UNUSED_RESULT;
  55
  56   // Initializes this instance using |key|. Call Init only once. It returns
  57   // false on the second or later calls.
  58   bool Init(const base::StringPiece& key) WARN_UNUSED_RESULT {
  59     return Init(reinterpret_cast<const unsigned char*>(key.data()),
  60                 static_cast<int>(key.size()));
  61   }
  62
  63   // Calculates the HMAC for the message in |data| using the algorithm supplied
  64   // to the constructor and the key supplied to the Init method. The HMAC is
  65   // returned in |digest|, which has |digest_length| bytes of storage available.
  66   // TODO(abarth): digest_length should be a size_t.
  67   bool Sign(const base::StringPiece& data, unsigned char* digest,
  68             int digest_length) const WARN_UNUSED_RESULT;
  69
  70   // Verifies that the HMAC for the message in |data| equals the HMAC provided
  71   // in |digest|, using the algorithm supplied to the constructor and the key
  72   // supplied to the Init method. Use of this method is strongly recommended
  73   // over using Sign() with a manual comparison (such as memcmp), as such
  74   // comparisons may result in side-channel disclosures, such as timing, that
  75   // undermine the cryptographic integrity. |digest| must be exactly
  76   // |DigestLength()| bytes long.
  77   bool Verify(const base::StringPiece& data,
  78               const base::StringPiece& digest) const WARN_UNUSED_RESULT;
  79
  80   // Verifies a truncated HMAC, behaving identical to Verify(), except
  81   // that |digest| is allowed to be smaller than |DigestLength()|.
  82   bool VerifyTruncated(
  83       const base::StringPiece& data,
  84       const base::StringPiece& digest) const WARN_UNUSED_RESULT;
  85
  86  private:
  87   HashAlgorithm hash_alg_;
  88   scoped_ptr<HMACPlatformData> plat_;
  89
  90   DISALLOW_COPY_AND_ASSIGN(HMAC);
  91 };
  92
  93 }  // namespace crypto
  94
  95 #endif  // CRYPTO_HMAC_H_