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 enum 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 45 enum 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 54 struct 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 70 struct 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 #if defined(LWS_HAVE_HMAC_CTX_new) 78 HMAC_CTX *ctx; 79 #else 80 HMAC_CTX ctx; 81 #endif 82 #endif 83 }; 84 85 /** lws_genhash_size() - get hash size in bytes 86 * 87 * \param type: one of LWS_GENHASH_TYPE_... 88 * 89 * Returns number of bytes in this type of hash 90 */ 91 LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT 92 lws_genhash_size(enum lws_genhash_types type); 93 94 /** lws_genhmac_size() - get hash size in bytes 95 * 96 * \param type: one of LWS_GENHASH_TYPE_... 97 * 98 * Returns number of bytes in this type of hmac 99 */ 100 LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT 101 lws_genhmac_size(enum lws_genhmac_types type); 102 103 /** lws_genhash_init() - prepare your struct lws_genhash_ctx for use 104 * 105 * \param ctx: your struct lws_genhash_ctx 106 * \param type: one of LWS_GENHASH_TYPE_... 107 * 108 * Initializes the hash context for the type you requested 109 */ 110 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 111 lws_genhash_init(struct lws_genhash_ctx *ctx, enum lws_genhash_types type); 112 113 /** lws_genhash_update() - digest len bytes of the buffer starting at in 114 * 115 * \param ctx: your struct lws_genhash_ctx 116 * \param in: start of the bytes to digest 117 * \param len: count of bytes to digest 118 * 119 * Updates the state of your hash context to reflect digesting len bytes from in 120 */ 121 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 122 lws_genhash_update(struct lws_genhash_ctx *ctx, const void *in, size_t len); 123 124 /** lws_genhash_destroy() - copy out the result digest and destroy the ctx 125 * 126 * \param ctx: your struct lws_genhash_ctx 127 * \param result: NULL, or where to copy the result hash 128 * 129 * Finalizes the hash and copies out the digest. Destroys any allocations such 130 * that ctx can safely go out of scope after calling this. 131 * 132 * NULL result is supported so that you can destroy the ctx cleanly on error 133 * conditions, where there is no valid result. 134 */ 135 LWS_VISIBLE LWS_EXTERN int 136 lws_genhash_destroy(struct lws_genhash_ctx *ctx, void *result); 137 138 /** lws_genhmac_init() - prepare your struct lws_genhmac_ctx for use 139 * 140 * \param ctx: your struct lws_genhmac_ctx 141 * \param type: one of LWS_GENHMAC_TYPE_... 142 * \param key: pointer to the start of the HMAC key 143 * \param key_len: length of the HMAC key 144 * 145 * Initializes the hash context for the type you requested 146 * 147 * If the return is nonzero, it failed and there is nothing needing to be 148 * destroyed. 149 */ 150 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 151 lws_genhmac_init(struct lws_genhmac_ctx *ctx, enum lws_genhmac_types type, 152 const uint8_t *key, size_t key_len); 153 154 /** lws_genhmac_update() - digest len bytes of the buffer starting at in 155 * 156 * \param ctx: your struct lws_genhmac_ctx 157 * \param in: start of the bytes to digest 158 * \param len: count of bytes to digest 159 * 160 * Updates the state of your hash context to reflect digesting len bytes from in 161 * 162 * If the return is nonzero, it failed and needs destroying. 163 */ 164 LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT 165 lws_genhmac_update(struct lws_genhmac_ctx *ctx, const void *in, size_t len); 166 167 /** lws_genhmac_destroy() - copy out the result digest and destroy the ctx 168 * 169 * \param ctx: your struct lws_genhmac_ctx 170 * \param result: NULL, or where to copy the result hash 171 * 172 * Finalizes the hash and copies out the digest. Destroys any allocations such 173 * that ctx can safely go out of scope after calling this. 174 * 175 * NULL result is supported so that you can destroy the ctx cleanly on error 176 * conditions, where there is no valid result. 177 */ 178 LWS_VISIBLE LWS_EXTERN int 179 lws_genhmac_destroy(struct lws_genhmac_ctx *ctx, void *result); 180 ///@} 181