include/libwebsockets/lws-genec.h

   1 /*
   2  * libwebsockets - Generic Elliptic Curve Encryption
   3  *
   4  * Copyright (C) 2010 - 2018 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  *
  21  * included from libwebsockets.h
  22  */
  23
  24 enum enum_genec_alg {
  25         LEGENEC_UNKNOWN,
  26
  27         LEGENEC_ECDH,
  28         LEGENEC_ECDSA
  29 };
  30
  31 struct lws_genec_ctx {
  32 #if defined(LWS_WITH_MBEDTLS)
  33         union {
  34                 mbedtls_ecdh_context *ctx_ecdh;
  35                 mbedtls_ecdsa_context *ctx_ecdsa;
  36         } u;
  37 #else
  38         EVP_PKEY_CTX *ctx[2];
  39 #endif
  40         struct lws_context *context;
  41         const struct lws_ec_curves *curve_table;
  42         enum enum_genec_alg genec_alg;
  43
  44         char has_private;
  45 };
  46
  47 #if defined(LWS_WITH_MBEDTLS)
  48 enum enum_lws_dh_side {
  49         LDHS_OURS = MBEDTLS_ECDH_OURS,
  50         LDHS_THEIRS = MBEDTLS_ECDH_THEIRS
  51 };
  52 #else
  53 enum enum_lws_dh_side {
  54         LDHS_OURS,
  55         LDHS_THEIRS
  56 };
  57 #endif
  58
  59 struct lws_ec_curves {
  60         const char *name;
  61         int tls_lib_nid;
  62         uint16_t key_bytes;
  63 };
  64
  65
  66 /* ECDH-specific apis */
  67
  68 /** lws_genecdh_create() - Create a genecdh
  69  *
  70  * \param ctx: your genec context
  71  * \param context: your lws_context (for RNG access)
  72  * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement
  73  *                     struct lws_ec_curves array, terminated by an entry with
  74  *                     .name = NULL, of curves you want to whitelist
  75  *
  76  * Initializes a genecdh
  77  */
  78 LWS_VISIBLE int
  79 lws_genecdh_create(struct lws_genec_ctx *ctx, struct lws_context *context,
  80                    const struct lws_ec_curves *curve_table);
  81
  82 /** lws_genecdh_set_key() - Apply an EC key to our or theirs side
  83  *
  84  * \param ctx: your genecdh context
  85  * \param el: your key elements
  86  * \param side: LDHS_OURS or LDHS_THEIRS
  87  *
  88  * Applies an EC key to one side or the other of an ECDH ctx
  89  */
  90 LWS_VISIBLE LWS_EXTERN int
  91 lws_genecdh_set_key(struct lws_genec_ctx *ctx, struct lws_gencrypto_keyelem *el,
  92                     enum enum_lws_dh_side side);
  93
  94 /** lws_genecdh_new_keypair() - Create a genec with a new public / private key
  95  *
  96  * \param ctx: your genec context
  97  * \param side: LDHS_OURS or LDHS_THEIRS
  98  * \param curve_name: an EC curve name, like "P-256"
  99  * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elems to take the new key
 100  *
 101  * Creates a genecdh with a newly minted EC public / private key
 102  */
 103 LWS_VISIBLE LWS_EXTERN int
 104 lws_genecdh_new_keypair(struct lws_genec_ctx *ctx, enum enum_lws_dh_side side,
 105                         const char *curve_name, struct lws_gencrypto_keyelem *el);
 106
 107 LWS_VISIBLE LWS_EXTERN int
 108 lws_genecdh_compute_shared_secret(struct lws_genec_ctx *ctx, uint8_t *ss,
 109                   int *ss_len);
 110
 111
 112 /* ECDSA-specific apis */
 113
 114 /** lws_genecdsa_create() - Create a genecdsa and
 115  *
 116  * \param ctx: your genec context
 117  * \param context: your lws_context (for RNG access)
 118  * \param curve_table: NULL, enabling P-256, P-384 and P-521, or a replacement
 119  *                     struct lws_ec_curves array, terminated by an entry with
 120  *                     .name = NULL, of curves you want to whitelist
 121  *
 122  * Initializes a genecdh
 123  */
 124 LWS_VISIBLE int
 125 lws_genecdsa_create(struct lws_genec_ctx *ctx, struct lws_context *context,
 126                     const struct lws_ec_curves *curve_table);
 127
 128 /** lws_genecdsa_new_keypair() - Create a genecdsa with a new public / private key
 129  *
 130  * \param ctx: your genec context
 131  * \param curve_name: an EC curve name, like "P-256"
 132  * \param el: array pf LWS_GENCRYPTO_EC_KEYEL_COUNT key elements to take the new key
 133  *
 134  * Creates a genecdsa with a newly minted EC public / private key
 135  */
 136 LWS_VISIBLE LWS_EXTERN int
 137 lws_genecdsa_new_keypair(struct lws_genec_ctx *ctx, const char *curve_name,
 138                          struct lws_gencrypto_keyelem *el);
 139
 140 /** lws_genecdsa_set_key() - Apply an EC key to an ecdsa context
 141  *
 142  * \param ctx: your genecdsa context
 143  * \param el: your key elements
 144  *
 145  * Applies an EC key to an ecdsa context
 146  */
 147 LWS_VISIBLE LWS_EXTERN int
 148 lws_genecdsa_set_key(struct lws_genec_ctx *ctx,
 149                      struct lws_gencrypto_keyelem *el);
 150
 151 /** lws_genecdsa_hash_sig_verify_jws() - Verifies a JWS ECDSA signature on a given hash
 152  *
 153  * \param ctx: your struct lws_genrsa_ctx
 154  * \param in: unencrypted payload (usually a recomputed hash)
 155  * \param hash_type: one of LWS_GENHASH_TYPE_
 156  * \param keybits: number of bits in the crypto key
 157  * \param sig: pointer to the signature we received with the payload
 158  * \param sig_len: length of the signature we are checking in bytes
 159  *
 160  * This just looks at the signed hash... that's why there's no input length
 161  * parameter, it's decided by the choice of hash.  It's up to you to confirm
 162  * separately the actual payload matches the hash that was confirmed by this to
 163  * be validly signed.
 164  *
 165  * Returns <0 for error, or 0 if signature matches the hash + key..
 166  *
 167  * The JWS ECDSA signature verification algorithm differs to generic ECDSA
 168  * signatures and they're not interoperable.
 169  *
 170  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 171  */
 172 LWS_VISIBLE LWS_EXTERN int
 173 lws_genecdsa_hash_sig_verify_jws(struct lws_genec_ctx *ctx, const uint8_t *in,
 174                                  enum lws_genhash_types hash_type, int keybits,
 175                                  const uint8_t *sig, size_t sig_len);
 176
 177 /** lws_genecdsa_hash_sign_jws() - Creates a JWS ECDSA signature for a hash you provide
 178  *
 179  * \param ctx: your struct lws_genrsa_ctx
 180  * \param in: precomputed hash
 181  * \param hash_type: one of LWS_GENHASH_TYPE_
 182  * \param keybits: number of bits in the crypto key
 183  * \param sig: pointer to buffer to take signature
 184  * \param sig_len: length of the buffer (must be >= length of key N)
 185  *
 186  * Returns <0 for error, or 0 for success.
 187  *
 188  * This creates a JWS ECDSA signature for a hash you already computed and provide.
 189  *
 190  * The JWS ECDSA signature generation algorithm differs to generic ECDSA
 191  * signatures and they're not interoperable.
 192  *
 193  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 194  */
 195 LWS_VISIBLE LWS_EXTERN int
 196 lws_genecdsa_hash_sign_jws(struct lws_genec_ctx *ctx, const uint8_t *in,
 197                            enum lws_genhash_types hash_type, int keybits,
 198                            uint8_t *sig, size_t sig_len);
 199
 200
 201 /* Apis that apply to both ECDH and ECDSA */
 202
 203 LWS_VISIBLE LWS_EXTERN void
 204 lws_genec_destroy(struct lws_genec_ctx *ctx);
 205
 206 LWS_VISIBLE LWS_EXTERN void
 207 lws_genec_destroy_elements(struct lws_gencrypto_keyelem *el);
 208
 209 LWS_VISIBLE LWS_EXTERN int
 210 lws_genec_dump(struct lws_gencrypto_keyelem *el);