1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup generichash Generic Hash
26 * ## Generic Hash related functions
27 *
28 * Lws provides generic hash / digest accessors that abstract the ones
29 * provided by whatever tls library you are linking against.
30 *
31 * It lets you use the same code if you build against mbedtls or OpenSSL
32 * for example.
33 */
34///@{
35
36#if defined(LWS_WITH_AWSLC) || defined(LWS_WITH_BORINGSSL)
37#include <openssl/hmac.h>
38#endif
39
40
41enum lws_genhash_types {
42 LWS_GENHASH_TYPE_UNKNOWN,
43 LWS_GENHASH_TYPE_MD5,
44 LWS_GENHASH_TYPE_SHA1,
45 LWS_GENHASH_TYPE_SHA256,
46 LWS_GENHASH_TYPE_SHA384,
47 LWS_GENHASH_TYPE_SHA512,
48};
49
50enum lws_genhmac_types {
51 LWS_GENHMAC_TYPE_UNKNOWN,
52 LWS_GENHMAC_TYPE_SHA256,
53 LWS_GENHMAC_TYPE_SHA384,
54 LWS_GENHMAC_TYPE_SHA512,
55};
56
57#define LWS_GENHASH_LARGEST 64
58
59#if defined(LWS_WITH_TLS) && defined(LWS_WITH_GENCRYPTO)
60
61struct lws_genhash_ctx {
62 uint8_t type;
63#if defined(LWS_WITH_MBEDTLS)
64 union {
65 mbedtls_md5_context md5;
66 mbedtls_sha1_context sha1;
67 mbedtls_sha256_context sha256;
68 mbedtls_sha512_context sha512; /* 384 also uses this */
69 const mbedtls_md_info_t *hmac;
70 } u;
71#else
72 const EVP_MD *evp_type;
73 EVP_MD_CTX *mdctx;
74#endif
75};
76
77struct lws_genhmac_ctx {
78 uint8_t type;
79#if defined(LWS_WITH_MBEDTLS)
80 const mbedtls_md_info_t *hmac;
81 mbedtls_md_context_t ctx;
82#else
83 const EVP_MD *evp_type;
84
85#if !defined(LWS_WITH_BORINGSSL) &&\
86 defined(LWS_HAVE_EVP_PKEY_new_raw_private_key)
87 EVP_MD_CTX *ctx;
88 EVP_PKEY *key;
89#else
90#if defined(LWS_HAVE_HMAC_CTX_new)
91 HMAC_CTX *ctx;
92#else
93 HMAC_CTX ctx;
94#endif
95#endif
96
97#endif
98};
99
100/** lws_genhash_size() - get hash size in bytes
101 *
102 * \param type: one of LWS_GENHASH_TYPE_...
103 *
104 * Returns number of bytes in this type of hash, if the hash type is unknown, it
105 * will return 0.
106 */
107LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
108lws_genhash_size(enum lws_genhash_types type);
109
110/** lws_genhmac_size() - get hash size in bytes
111 *
112 * \param type: one of LWS_GENHASH_TYPE_...
113 *
114 * Returns number of bytes in this type of hmac, if the hmac type is unknown, it
115 * will return 0.
116 */
117LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
118lws_genhmac_size(enum lws_genhmac_types type);
119
120/** lws_genhash_init() - prepare your struct lws_genhash_ctx for use
121 *
122 * \param ctx: your struct lws_genhash_ctx
123 * \param type: one of LWS_GENHASH_TYPE_...
124 *
125 * Initializes the hash context for the type you requested
126 */
127LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
128lws_genhash_init(struct lws_genhash_ctx *ctx, enum lws_genhash_types type);
129
130/** lws_genhash_update() - digest len bytes of the buffer starting at in
131 *
132 * \param ctx: your struct lws_genhash_ctx
133 * \param in: start of the bytes to digest
134 * \param len: count of bytes to digest
135 *
136 * Updates the state of your hash context to reflect digesting len bytes from in
137 */
138LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
139lws_genhash_update(struct lws_genhash_ctx *ctx, const void *in, size_t len);
140
141/** lws_genhash_destroy() - copy out the result digest and destroy the ctx
142 *
143 * \param ctx: your struct lws_genhash_ctx
144 * \param result: NULL, or where to copy the result hash
145 *
146 * Finalizes the hash and copies out the digest. Destroys any allocations such
147 * that ctx can safely go out of scope after calling this.
148 *
149 * NULL result is supported so that you can destroy the ctx cleanly on error
150 * conditions, where there is no valid result.
151 */
152LWS_VISIBLE LWS_EXTERN int
153lws_genhash_destroy(struct lws_genhash_ctx *ctx, void *result);
154
155/** lws_genhmac_init() - prepare your struct lws_genhmac_ctx for use
156 *
157 * \param ctx: your struct lws_genhmac_ctx
158 * \param type: one of LWS_GENHMAC_TYPE_...
159 * \param key: pointer to the start of the HMAC key
160 * \param key_len: length of the HMAC key
161 *
162 * Initializes the hash context for the type you requested
163 *
164 * If the return is nonzero, it failed and there is nothing needing to be
165 * destroyed.
166 */
167LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
168lws_genhmac_init(struct lws_genhmac_ctx *ctx, enum lws_genhmac_types type,
169 const uint8_t *key, size_t key_len);
170
171/** lws_genhmac_update() - digest len bytes of the buffer starting at in
172 *
173 * \param ctx: your struct lws_genhmac_ctx
174 * \param in: start of the bytes to digest
175 * \param len: count of bytes to digest
176 *
177 * Updates the state of your hash context to reflect digesting len bytes from in
178 *
179 * If the return is nonzero, it failed and needs destroying.
180 */
181LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
182lws_genhmac_update(struct lws_genhmac_ctx *ctx, const void *in, size_t len);
183
184/** lws_genhmac_destroy() - copy out the result digest and destroy the ctx
185 *
186 * \param ctx: your struct lws_genhmac_ctx
187 * \param result: NULL, or where to copy the result hash
188 *
189 * Finalizes the hash and copies out the digest. Destroys any allocations such
190 * that ctx can safely go out of scope after calling this.
191 *
192 * NULL result is supported so that you can destroy the ctx cleanly on error
193 * conditions, where there is no valid result.
194 */
195LWS_VISIBLE LWS_EXTERN int
196lws_genhmac_destroy(struct lws_genhmac_ctx *ctx, void *result);
197
198#endif
199///@}
200