hmac.h 4.3 KB

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