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
36enum lws_genhash_types {
37 LWS_GENHASH_TYPE_UNKNOWN,
38 LWS_GENHASH_TYPE_MD5,
39 LWS_GENHASH_TYPE_SHA1,
40 LWS_GENHASH_TYPE_SHA256,
41 LWS_GENHASH_TYPE_SHA384,
42 LWS_GENHASH_TYPE_SHA512,
43};
44
45enum lws_genhmac_types {
46 LWS_GENHMAC_TYPE_UNKNOWN,
47 LWS_GENHMAC_TYPE_SHA256,
48 LWS_GENHMAC_TYPE_SHA384,
49 LWS_GENHMAC_TYPE_SHA512,
50};
51
52#define LWS_GENHASH_LARGEST 64
53
54struct lws_genhash_ctx {
55 uint8_t type;
56#if defined(LWS_WITH_MBEDTLS)
57 union {
58 mbedtls_md5_context md5;
59 mbedtls_sha1_context sha1;
60 mbedtls_sha256_context sha256;
61 mbedtls_sha512_context sha512; /* 384 also uses this */
62 const mbedtls_md_info_t *hmac;
63 } u;
64#else
65 const EVP_MD *evp_type;
66 EVP_MD_CTX *mdctx;
67#endif
68};
69
70struct lws_genhmac_ctx {
71 uint8_t type;
72#if defined(LWS_WITH_MBEDTLS)
73 const mbedtls_md_info_t *hmac;
74 mbedtls_md_context_t ctx;
75#else
76 const EVP_MD *evp_type;
77
78#if defined(LWS_HAVE_EVP_PKEY_new_raw_private_key)
79 EVP_MD_CTX *ctx;
80 EVP_PKEY *key;
81#else
82#if defined(LWS_HAVE_HMAC_CTX_new)
83 HMAC_CTX *ctx;
84#else
85 HMAC_CTX ctx;
86#endif
87#endif
88
89#endif
90};
91
92/** lws_genhash_size() - get hash size in bytes
93 *
94 * \param type: one of LWS_GENHASH_TYPE_...
95 *
96 * Returns number of bytes in this type of hash, if the hash type is unknown, it
97 * will return 0.
98 */
99LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
100lws_genhash_size(enum lws_genhash_types type);
101
102/** lws_genhmac_size() - get hash size in bytes
103 *
104 * \param type: one of LWS_GENHASH_TYPE_...
105 *
106 * Returns number of bytes in this type of hmac, if the hmac type is unknown, it
107 * will return 0.
108 */
109LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT
110lws_genhmac_size(enum lws_genhmac_types type);
111
112/** lws_genhash_init() - prepare your struct lws_genhash_ctx for use
113 *
114 * \param ctx: your struct lws_genhash_ctx
115 * \param type: one of LWS_GENHASH_TYPE_...
116 *
117 * Initializes the hash context for the type you requested
118 */
119LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
120lws_genhash_init(struct lws_genhash_ctx *ctx, enum lws_genhash_types type);
121
122/** lws_genhash_update() - digest len bytes of the buffer starting at in
123 *
124 * \param ctx: your struct lws_genhash_ctx
125 * \param in: start of the bytes to digest
126 * \param len: count of bytes to digest
127 *
128 * Updates the state of your hash context to reflect digesting len bytes from in
129 */
130LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
131lws_genhash_update(struct lws_genhash_ctx *ctx, const void *in, size_t len);
132
133/** lws_genhash_destroy() - copy out the result digest and destroy the ctx
134 *
135 * \param ctx: your struct lws_genhash_ctx
136 * \param result: NULL, or where to copy the result hash
137 *
138 * Finalizes the hash and copies out the digest. Destroys any allocations such
139 * that ctx can safely go out of scope after calling this.
140 *
141 * NULL result is supported so that you can destroy the ctx cleanly on error
142 * conditions, where there is no valid result.
143 */
144LWS_VISIBLE LWS_EXTERN int
145lws_genhash_destroy(struct lws_genhash_ctx *ctx, void *result);
146
147/** lws_genhmac_init() - prepare your struct lws_genhmac_ctx for use
148 *
149 * \param ctx: your struct lws_genhmac_ctx
150 * \param type: one of LWS_GENHMAC_TYPE_...
151 * \param key: pointer to the start of the HMAC key
152 * \param key_len: length of the HMAC key
153 *
154 * Initializes the hash context for the type you requested
155 *
156 * If the return is nonzero, it failed and there is nothing needing to be
157 * destroyed.
158 */
159LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
160lws_genhmac_init(struct lws_genhmac_ctx *ctx, enum lws_genhmac_types type,
161 const uint8_t *key, size_t key_len);
162
163/** lws_genhmac_update() - digest len bytes of the buffer starting at in
164 *
165 * \param ctx: your struct lws_genhmac_ctx
166 * \param in: start of the bytes to digest
167 * \param len: count of bytes to digest
168 *
169 * Updates the state of your hash context to reflect digesting len bytes from in
170 *
171 * If the return is nonzero, it failed and needs destroying.
172 */
173LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT
174lws_genhmac_update(struct lws_genhmac_ctx *ctx, const void *in, size_t len);
175
176/** lws_genhmac_destroy() - copy out the result digest and destroy the ctx
177 *
178 * \param ctx: your struct lws_genhmac_ctx
179 * \param result: NULL, or where to copy the result hash
180 *
181 * Finalizes the hash and copies out the digest. Destroys any allocations such
182 * that ctx can safely go out of scope after calling this.
183 *
184 * NULL result is supported so that you can destroy the ctx cleanly on error
185 * conditions, where there is no valid result.
186 */
187LWS_VISIBLE LWS_EXTERN int
188lws_genhmac_destroy(struct lws_genhmac_ctx *ctx, void *result);
189///@}
190