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