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 "base/compiler_specific.h"
14#include "base/macros.h"
15#include "base/memory/scoped_ptr.h"
16#include "base/strings/string_piece.h"
17#include "crypto/crypto_export.h"
18
19namespace crypto {
20
21// Simplify the interface and reduce includes by abstracting out the internals.
22struct HMACPlatformData;
23class SymmetricKey;
24
25class CRYPTO_EXPORT HMAC {
26 public:
27  // The set of supported hash functions. Extend as required.
28  enum HashAlgorithm {
29    SHA1,
30    SHA256,
31  };
32
33  explicit HMAC(HashAlgorithm hash_alg);
34  ~HMAC();
35
36  // Returns the length of digest that this HMAC will create.
37  size_t DigestLength() const;
38
39  // TODO(abarth): Add a PreferredKeyLength() member function.
40
41  // Initializes this instance using |key| of the length |key_length|. Call Init
42  // only once. It returns false on the second or later calls.
43  //
44  // NOTE: the US Federal crypto standard FIPS 198, Section 3 says:
45  //   The size of the key, K, shall be equal to or greater than L/2, where L
46  //   is the size of the hash function output.
47  // In FIPS 198-1 (and SP-800-107, which describes key size recommendations),
48  // this requirement is gone.  But a system crypto library may still enforce
49  // this old requirement.  If the key is shorter than this recommended value,
50  // Init() may fail.
51  bool Init(const unsigned char* key, size_t key_length) WARN_UNUSED_RESULT;
52
53  // Initializes this instance using |key|. Call Init
54  // only once. It returns false on the second or later calls.
55  bool Init(SymmetricKey* key) WARN_UNUSED_RESULT;
56
57  // Initializes this instance using |key|. Call Init only once. It returns
58  // false on the second or later calls.
59  bool Init(const base::StringPiece& key) WARN_UNUSED_RESULT {
60    return Init(reinterpret_cast<const unsigned char*>(key.data()),
61                key.size());
62  }
63
64  // Calculates the HMAC for the message in |data| using the algorithm supplied
65  // to the constructor and the key supplied to the Init method. The HMAC is
66  // returned in |digest|, which has |digest_length| bytes of storage available.
67  bool Sign(const base::StringPiece& data, unsigned char* digest,
68            size_t 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_
96