lws-genhash.h (6147B)
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///@}