crypto/hmac.h

   1 // Copyright 2012 The Chromium Authors
   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 only
   6 // support SHA-1 and SHA-256 for the hash algorithm, but this can be extended
   7 // easily. Prefer the base::span and std::vector overloads over the
   8 // std::string_view and std::string overloads.
   9
  10 #ifndef CRYPTO_HMAC_H_
  11 #define CRYPTO_HMAC_H_
  12
  13 #include <stddef.h>
  14
  15 #include <memory>
  16 #include <string_view>
  17 #include <vector>
  18
  19 #include "base/containers/span.h"
  20 #include "crypto/crypto_export.h"
  21
  22 namespace crypto {
  23
  24 // Simplify the interface and reduce includes by abstracting out the internals.
  25 class SymmetricKey;
  26
  27 class CRYPTO_EXPORT HMAC {
  28  public:
  29   // The set of supported hash functions. Extend as required.
  30   enum HashAlgorithm {
  31     SHA1,
  32     SHA256,
  33   };
  34
  35   explicit HMAC(HashAlgorithm hash_alg);
  36
  37   HMAC(const HMAC&) = delete;
  38   HMAC& operator=(const HMAC&) = delete;
  39
  40   ~HMAC();
  41
  42   // Returns the length of digest that this HMAC will create.
  43   size_t DigestLength() const;
  44
  45   // TODO(abarth): Add a PreferredKeyLength() member function.
  46
  47   // Initializes this instance using |key| of the length |key_length|. Call Init
  48   // only once. It returns false on the second or later calls.
  49   //
  50   // NOTE: the US Federal crypto standard FIPS 198, Section 3 says:
  51   //   The size of the key, K, shall be equal to or greater than L/2, where L
  52   //   is the size of the hash function output.
  53   // In FIPS 198-1 (and SP-800-107, which describes key size recommendations),
  54   // this requirement is gone.  But a system crypto library may still enforce
  55   // this old requirement.  If the key is shorter than this recommended value,
  56   // Init() may fail.
  57   [[nodiscard]] bool Init(const unsigned char* key, size_t key_length);
  58
  59   // Initializes this instance using |key|. Call Init
  60   // only once. It returns false on the second or later calls.
  61   [[nodiscard]] bool Init(const SymmetricKey* key);
  62
  63   // Initializes this instance using |key|. Call Init only once. It returns
  64   // false on the second or later calls.
  65   [[nodiscard]] bool Init(std::string_view key) {
  66     return Init(base::as_bytes(base::make_span(key)));
  67   }
  68
  69   // Initializes this instance using |key|. Call Init only once. It returns
  70   // false on the second or later calls.
  71   [[nodiscard]] bool Init(base::span<const uint8_t> key) {
  72     return Init(key.data(), key.size());
  73   }
  74
  75   // Calculates the HMAC for the message in |data| using the algorithm supplied
  76   // to the constructor and the key supplied to the Init method. The HMAC is
  77   // returned in |digest|, which has |digest_length| bytes of storage available.
  78   // If |digest_length| is smaller than DigestLength(), the output will be
  79   // truncated. If it is larger, this method will fail.
  80   [[nodiscard]] bool Sign(std::string_view data,
  81                           unsigned char* digest,
  82                           size_t digest_length) const;
  83   [[nodiscard]] bool Sign(base::span<const uint8_t> data,
  84                           base::span<uint8_t> digest) const;
  85
  86   // Verifies that the HMAC for the message in |data| equals the HMAC provided
  87   // in |digest|, using the algorithm supplied to the constructor and the key
  88   // supplied to the Init method. Use of this method is strongly recommended
  89   // over using Sign() with a manual comparison (such as memcmp), as such
  90   // comparisons may result in side-channel disclosures, such as timing, that
  91   // undermine the cryptographic integrity. |digest| must be exactly
  92   // |DigestLength()| bytes long.
  93   [[nodiscard]] bool Verify(std::string_view data,
  94                             std::string_view digest) const;
  95   [[nodiscard]] bool Verify(base::span<const uint8_t> data,
  96                             base::span<const uint8_t> digest) const;
  97
  98   // Verifies a truncated HMAC, behaving identical to Verify(), except
  99   // that |digest| is allowed to be smaller than |DigestLength()|.
 100   [[nodiscard]] bool VerifyTruncated(std::string_view data,
 101                                      std::string_view digest) const;
 102   [[nodiscard]] bool VerifyTruncated(base::span<const uint8_t> data,
 103                                      base::span<const uint8_t> digest) const;
 104
 105  private:
 106   HashAlgorithm hash_alg_;
 107   bool initialized_;
 108   std::vector<unsigned char> key_;
 109 };
 110
 111 }  // namespace crypto
 112
 113 #endif  // CRYPTO_HMAC_H_