1 /*
2 * libjingle
3 * Copyright 2004, Google Inc.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 * 1. Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 * 2. Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 * 3. The name of the author may not be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 #ifndef TALK_BASE_MESSAGEDIGEST_H_
29 #define TALK_BASE_MESSAGEDIGEST_H_
30
31 #include <string>
32
33 namespace talk_base {
34
35 // Definitions for the digest algorithms.
36 extern const char DIGEST_MD5[];
37 extern const char DIGEST_SHA_1[];
38 extern const char DIGEST_SHA_224[];
39 extern const char DIGEST_SHA_256[];
40 extern const char DIGEST_SHA_384[];
41 extern const char DIGEST_SHA_512[];
42
43 // A general class for computing hashes.
44 class MessageDigest {
45 public:
46 enum { kMaxSize = 64 }; // Maximum known size (SHA-512)
~MessageDigest()47 virtual ~MessageDigest() {}
48 // Returns the digest output size (e.g. 16 bytes for MD5).
49 virtual size_t Size() const = 0;
50 // Updates the digest with |len| bytes from |buf|.
51 virtual void Update(const void* buf, size_t len) = 0;
52 // Outputs the digest value to |buf| with length |len|.
53 // Returns the number of bytes written, i.e., Size().
54 virtual size_t Finish(void* buf, size_t len) = 0;
55 };
56
57 // A factory class for creating digest objects.
58 class MessageDigestFactory {
59 public:
60 static MessageDigest* Create(const std::string& alg);
61 };
62
63 // A whitelist of approved digest algorithms from RFC 4572 (FIPS 180).
64 bool IsFips180DigestAlgorithm(const std::string& alg);
65
66 // Functions to create hashes.
67
68 // Computes the hash of |in_len| bytes of |input|, using the |digest| hash
69 // implementation, and outputs the hash to the buffer |output|, which is
70 // |out_len| bytes long. Returns the number of bytes written to |output| if
71 // successful, or 0 if |out_len| was too small.
72 size_t ComputeDigest(MessageDigest* digest, const void* input, size_t in_len,
73 void* output, size_t out_len);
74 // Like the previous function, but creates a digest implementation based on
75 // the desired digest name |alg|, e.g. DIGEST_SHA_1. Returns 0 if there is no
76 // digest with the given name.
77 size_t ComputeDigest(const std::string& alg, const void* input, size_t in_len,
78 void* output, size_t out_len);
79 // Computes the hash of |input| using the |digest| hash implementation, and
80 // returns it as a hex-encoded string.
81 std::string ComputeDigest(MessageDigest* digest, const std::string& input);
82 // Like the previous function, but creates a digest implementation based on
83 // the desired digest name |alg|, e.g. DIGEST_SHA_1. Returns empty string if
84 // there is no digest with the given name.
85 std::string ComputeDigest(const std::string& alg, const std::string& input);
86 // Like the previous function, but returns an explicit result code.
87 bool ComputeDigest(const std::string& alg, const std::string& input,
88 std::string* output);
89
90 // Shorthand way to compute a hex-encoded hash using MD5.
MD5(const std::string & input)91 inline std::string MD5(const std::string& input) {
92 return ComputeDigest(DIGEST_MD5, input);
93 }
94
95 // Functions to compute RFC 2104 HMACs.
96
97 // Computes the HMAC of |in_len| bytes of |input|, using the |digest| hash
98 // implementation and |key_len| bytes of |key| to key the HMAC, and outputs
99 // the HMAC to the buffer |output|, which is |out_len| bytes long. Returns the
100 // number of bytes written to |output| if successful, or 0 if |out_len| was too
101 // small.
102 size_t ComputeHmac(MessageDigest* digest, const void* key, size_t key_len,
103 const void* input, size_t in_len,
104 void* output, size_t out_len);
105 // Like the previous function, but creates a digest implementation based on
106 // the desired digest name |alg|, e.g. DIGEST_SHA_1. Returns 0 if there is no
107 // digest with the given name.
108 size_t ComputeHmac(const std::string& alg, const void* key, size_t key_len,
109 const void* input, size_t in_len,
110 void* output, size_t out_len);
111 // Computes the HMAC of |input| using the |digest| hash implementation and |key|
112 // to key the HMAC, and returns it as a hex-encoded string.
113 std::string ComputeHmac(MessageDigest* digest, const std::string& key,
114 const std::string& input);
115 // Like the previous function, but creates a digest implementation based on
116 // the desired digest name |alg|, e.g. DIGEST_SHA_1. Returns empty string if
117 // there is no digest with the given name.
118 std::string ComputeHmac(const std::string& alg, const std::string& key,
119 const std::string& input);
120 // Like the previous function, but returns an explicit result code.
121 bool ComputeHmac(const std::string& alg, const std::string& key,
122 const std::string& input, std::string* output);
123
124 } // namespace talk_base
125
126 #endif // TALK_BASE_MESSAGEDIGEST_H_
127