lws-genec.h (7152B)
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 25enum enum_genec_alg { 26 LEGENEC_UNKNOWN, 27 28 LEGENEC_ECDH, 29 LEGENEC_ECDSA 30}; 31 32struct lws_genec_ctx { 33#if defined(LWS_WITH_MBEDTLS) 34 union { 35 mbedtls_ecdh_context *ctx_ecdh; 36 mbedtls_ecdsa_context *ctx_ecdsa; 37 } u; 38#else 39 EVP_PKEY_CTX *ctx[2]; 40#endif 41 struct lws_context *context; 42 const struct lws_ec_curves *curve_table; 43 enum enum_genec_alg genec_alg; 44 45 char has_private; 46}; 47 48#if defined(LWS_WITH_MBEDTLS) 49enum enum_lws_dh_side { 50 LDHS_OURS = MBEDTLS_ECDH_OURS, 51 LDHS_THEIRS = MBEDTLS_ECDH_THEIRS 52}; 53#else 54enum enum_lws_dh_side { 55 LDHS_OURS, 56 LDHS_THEIRS 57}; 58#endif 59 60struct lws_ec_curves { 61 const char *name; 62 int tls_lib_nid; 63 uint16_t key_bytes; 64}; 65 66 67/* ECDH-specific apis */ 68 69/** lws_genecdh_create() - Create a genecdh 70 * 71 * \param ctx: your genec context 72 * \param context: your lws_context (for RNG access) 73 * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement 74 * struct lws_ec_curves array, terminated by an entry with 75 * .name = NULL, of curves you want to allow 76 * 77 * Initializes a genecdh 78 */ 79LWS_VISIBLE int 80lws_genecdh_create(struct lws_genec_ctx *ctx, struct lws_context *context, 81 const struct lws_ec_curves *curve_table); 82 83/** lws_genecdh_set_key() - Apply an EC key to our or theirs side 84 * 85 * \param ctx: your genecdh context 86 * \param el: your key elements 87 * \param side: LDHS_OURS or LDHS_THEIRS 88 * 89 * Applies an EC key to one side or the other of an ECDH ctx 90 */ 91LWS_VISIBLE LWS_EXTERN int 92lws_genecdh_set_key(struct lws_genec_ctx *ctx, struct lws_gencrypto_keyelem *el, 93 enum enum_lws_dh_side side); 94 95/** lws_genecdh_new_keypair() - Create a genec with a new public / private key 96 * 97 * \param ctx: your genec context 98 * \param side: LDHS_OURS or LDHS_THEIRS 99 * \param curve_name: an EC curve name, like "P-256" 100 * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elems to take the new key 101 * 102 * Creates a genecdh with a newly minted EC public / private key 103 */ 104LWS_VISIBLE LWS_EXTERN int 105lws_genecdh_new_keypair(struct lws_genec_ctx *ctx, enum enum_lws_dh_side side, 106 const char *curve_name, struct lws_gencrypto_keyelem *el); 107 108LWS_VISIBLE LWS_EXTERN int 109lws_genecdh_compute_shared_secret(struct lws_genec_ctx *ctx, uint8_t *ss, 110 int *ss_len); 111 112 113/* ECDSA-specific apis */ 114 115/** lws_genecdsa_create() - Create a genecdsa and 116 * 117 * \param ctx: your genec context 118 * \param context: your lws_context (for RNG access) 119 * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement 120 * struct lws_ec_curves array, terminated by an entry with 121 * .name = NULL, of curves you want to allow 122 * 123 * Initializes a genecdh 124 */ 125LWS_VISIBLE int 126lws_genecdsa_create(struct lws_genec_ctx *ctx, struct lws_context *context, 127 const struct lws_ec_curves *curve_table); 128 129/** lws_genecdsa_new_keypair() - Create a genecdsa with a new public / private key 130 * 131 * \param ctx: your genec context 132 * \param curve_name: an EC curve name, like "P-256" 133 * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elements to take the new key 134 * 135 * Creates a genecdsa with a newly minted EC public / private key 136 */ 137LWS_VISIBLE LWS_EXTERN int 138lws_genecdsa_new_keypair(struct lws_genec_ctx *ctx, const char *curve_name, 139 struct lws_gencrypto_keyelem *el); 140 141/** lws_genecdsa_set_key() - Apply an EC key to an ecdsa context 142 * 143 * \param ctx: your genecdsa context 144 * \param el: your key elements 145 * 146 * Applies an EC key to an ecdsa context 147 */ 148LWS_VISIBLE LWS_EXTERN int 149lws_genecdsa_set_key(struct lws_genec_ctx *ctx, 150 const struct lws_gencrypto_keyelem *el); 151 152/** lws_genecdsa_hash_sig_verify_jws() - Verifies a JWS ECDSA signature on a given hash 153 * 154 * \param ctx: your struct lws_genrsa_ctx 155 * \param in: unencrypted payload (usually a recomputed hash) 156 * \param hash_type: one of LWS_GENHASH_TYPE_ 157 * \param keybits: number of bits in the crypto key 158 * \param sig: pointer to the signature we received with the payload 159 * \param sig_len: length of the signature we are checking in bytes 160 * 161 * This just looks at the signed hash... that's why there's no input length 162 * parameter, it's decided by the choice of hash. It's up to you to confirm 163 * separately the actual payload matches the hash that was confirmed by this to 164 * be validly signed. 165 * 166 * Returns <0 for error, or 0 if signature matches the hash + key.. 167 * 168 * The JWS ECDSA signature verification algorithm differs to generic ECDSA 169 * signatures and they're not interoperable. 170 * 171 * This and related APIs operate identically with OpenSSL or mbedTLS backends. 172 */ 173LWS_VISIBLE LWS_EXTERN int 174lws_genecdsa_hash_sig_verify_jws(struct lws_genec_ctx *ctx, const uint8_t *in, 175 enum lws_genhash_types hash_type, int keybits, 176 const uint8_t *sig, size_t sig_len); 177 178/** lws_genecdsa_hash_sign_jws() - Creates a JWS ECDSA signature for a hash you provide 179 * 180 * \param ctx: your struct lws_genrsa_ctx 181 * \param in: precomputed hash 182 * \param hash_type: one of LWS_GENHASH_TYPE_ 183 * \param keybits: number of bits in the crypto key 184 * \param sig: pointer to buffer to take signature 185 * \param sig_len: length of the buffer (must be >= length of key N) 186 * 187 * Returns <0 for error, or >=0 for success. 188 * 189 * This creates a JWS ECDSA signature for a hash you already computed and provide. 190 * 191 * The JWS ECDSA signature generation algorithm differs to generic ECDSA 192 * signatures and they're not interoperable. 193 * 194 * This and related APIs operate identically with OpenSSL or mbedTLS backends. 195 */ 196LWS_VISIBLE LWS_EXTERN int 197lws_genecdsa_hash_sign_jws(struct lws_genec_ctx *ctx, const uint8_t *in, 198 enum lws_genhash_types hash_type, int keybits, 199 uint8_t *sig, size_t sig_len); 200 201 202/* Apis that apply to both ECDH and ECDSA */ 203 204LWS_VISIBLE LWS_EXTERN void 205lws_genec_destroy(struct lws_genec_ctx *ctx); 206 207LWS_VISIBLE LWS_EXTERN void 208lws_genec_destroy_elements(struct lws_gencrypto_keyelem *el); 209 210LWS_VISIBLE LWS_EXTERN int 211lws_genec_dump(struct lws_gencrypto_keyelem *el);