include/libwebsockets/lws-genrsa.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   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 /*! \defgroup genericRSA Generic RSA
  25  * ## Generic RSA related functions
  26  *
  27  * Lws provides generic RSA functions that abstract the ones
  28  * provided by whatever OpenSSL library you are linking against.
  29  *
  30  * It lets you use the same code if you build against mbedtls or OpenSSL
  31  * for example.
  32  */
  33 ///@{
  34
  35 /* include/libwebsockets/lws-jwk.h must be included before this */
  36
  37 enum enum_genrsa_mode {
  38         LGRSAM_PKCS1_1_5,
  39         LGRSAM_PKCS1_OAEP_PSS,
  40
  41         LGRSAM_COUNT
  42 };
  43
  44 struct lws_genrsa_ctx {
  45 #if defined(LWS_WITH_MBEDTLS)
  46         mbedtls_rsa_context *ctx;
  47 #else
  48         BIGNUM *bn[LWS_GENCRYPTO_RSA_KEYEL_COUNT];
  49         EVP_PKEY_CTX *ctx;
  50         RSA *rsa;
  51 #endif
  52         struct lws_context *context;
  53         enum enum_genrsa_mode mode;
  54 };
  55
  56 /** lws_genrsa_public_decrypt_create() - Create RSA public decrypt context
  57  *
  58  * \param ctx: your struct lws_genrsa_ctx
  59  * \param el: struct prepared with key element data
  60  * \param context: lws_context for RNG
  61  * \param mode: RSA mode, one of LGRSAM_ constants
  62  * \param oaep_hashid: the lws genhash id for the hash used in MFG1 hash
  63  *                      used in OAEP mode - normally, SHA1
  64  *
  65  * Creates an RSA context with a public key associated with it, formed from
  66  * the key elements in \p el.
  67  *
  68  * Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses.  It's
  69  * recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.
  70  *
  71  * Returns 0 for OK or nonzero for error.
  72  *
  73  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
  74  */
  75 LWS_VISIBLE LWS_EXTERN int
  76 lws_genrsa_create(struct lws_genrsa_ctx *ctx, struct lws_gencrypto_keyelem *el,
  77                   struct lws_context *context, enum enum_genrsa_mode mode,
  78                   enum lws_genhash_types oaep_hashid);
  79
  80 /** lws_genrsa_destroy_elements() - Free allocations in genrsa_elements
  81  *
  82  * \param el: your struct lws_gencrypto_keyelem
  83  *
  84  * This is a helper for user code making use of struct lws_gencrypto_keyelem
  85  * where the elements are allocated on the heap, it frees any non-NULL
  86  * buf element and sets the buf to NULL.
  87  *
  88  * NB: lws_genrsa_public_... apis do not need this as they take care of the key
  89  * creation and destruction themselves.
  90  */
  91 LWS_VISIBLE LWS_EXTERN void
  92 lws_genrsa_destroy_elements(struct lws_gencrypto_keyelem *el);
  93
  94 /** lws_genrsa_new_keypair() - Create new RSA keypair
  95  *
  96  * \param context: your struct lws_context (may be used for RNG)
  97  * \param ctx: your struct lws_genrsa_ctx
  98  * \param mode: RSA mode, one of LGRSAM_ constants
  99  * \param el: struct to get the new key element data allocated into it
 100  * \param bits: key size, eg, 4096
 101  *
 102  * Creates a new RSA context and generates a new keypair into it, with \p bits
 103  * bits.
 104  *
 105  * Returns 0 for OK or nonzero for error.
 106  *
 107  * Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses.  It's
 108  * recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.
 109  *
 110  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 111  */
 112 LWS_VISIBLE LWS_EXTERN int
 113 lws_genrsa_new_keypair(struct lws_context *context, struct lws_genrsa_ctx *ctx,
 114                        enum enum_genrsa_mode mode, struct lws_gencrypto_keyelem *el,
 115                        int bits);
 116
 117 /** lws_genrsa_public_encrypt() - Perform RSA public key encryption
 118  *
 119  * \param ctx: your struct lws_genrsa_ctx
 120  * \param in: plaintext input
 121  * \param in_len: length of plaintext input
 122  * \param out: encrypted output
 123  *
 124  * Performs PKCS1 v1.5 Encryption
 125  *
 126  * Returns <0 for error, or length of decrypted data.
 127  *
 128  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 129  */
 130 LWS_VISIBLE LWS_EXTERN int
 131 lws_genrsa_public_encrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 132                           size_t in_len, uint8_t *out);
 133
 134 /** lws_genrsa_private_encrypt() - Perform RSA private key encryption
 135  *
 136  * \param ctx: your struct lws_genrsa_ctx
 137  * \param in: plaintext input
 138  * \param in_len: length of plaintext input
 139  * \param out: encrypted output
 140  *
 141  * Performs PKCS1 v1.5 Encryption
 142  *
 143  * Returns <0 for error, or length of decrypted data.
 144  *
 145  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 146  */
 147 LWS_VISIBLE LWS_EXTERN int
 148 lws_genrsa_private_encrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 149                            size_t in_len, uint8_t *out);
 150
 151 /** lws_genrsa_public_decrypt() - Perform RSA public key decryption
 152  *
 153  * \param ctx: your struct lws_genrsa_ctx
 154  * \param in: encrypted input
 155  * \param in_len: length of encrypted input
 156  * \param out: decrypted output
 157  * \param out_max: size of output buffer
 158  *
 159  * Performs PKCS1 v1.5 Decryption
 160  *
 161  * Returns <0 for error, or length of decrypted data.
 162  *
 163  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 164  */
 165 LWS_VISIBLE LWS_EXTERN int
 166 lws_genrsa_public_decrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 167                           size_t in_len, uint8_t *out, size_t out_max);
 168
 169 /** lws_genrsa_private_decrypt() - Perform RSA private key decryption
 170  *
 171  * \param ctx: your struct lws_genrsa_ctx
 172  * \param in: encrypted input
 173  * \param in_len: length of encrypted input
 174  * \param out: decrypted output
 175  * \param out_max: size of output buffer
 176  *
 177  * Performs PKCS1 v1.5 Decryption
 178  *
 179  * Returns <0 for error, or length of decrypted data.
 180  *
 181  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 182  */
 183 LWS_VISIBLE LWS_EXTERN int
 184 lws_genrsa_private_decrypt(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 185                            size_t in_len, uint8_t *out, size_t out_max);
 186
 187 /** lws_genrsa_hash_sig_verify() - Verifies RSA signature on a given hash
 188  *
 189  * \param ctx: your struct lws_genrsa_ctx
 190  * \param in: input to be hashed
 191  * \param hash_type: one of LWS_GENHASH_TYPE_
 192  * \param sig: pointer to the signature we received with the payload
 193  * \param sig_len: length of the signature we are checking in bytes
 194  *
 195  * Returns <0 for error, or 0 if signature matches the payload + key.
 196  *
 197  * This just looks at a hash... that's why there's no input length
 198  * parameter, it's decided by the choice of hash.   It's up to you to confirm
 199  * separately the actual payload matches the hash that was confirmed by this to
 200  * be validly signed.
 201  *
 202  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 203  */
 204 LWS_VISIBLE LWS_EXTERN int
 205 lws_genrsa_hash_sig_verify(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 206                            enum lws_genhash_types hash_type,
 207                            const uint8_t *sig, size_t sig_len);
 208
 209 /** lws_genrsa_hash_sign() - Creates an ECDSA signature for a hash you provide
 210  *
 211  * \param ctx: your struct lws_genrsa_ctx
 212  * \param in: input to be hashed and signed
 213  * \param hash_type: one of LWS_GENHASH_TYPE_
 214  * \param sig: pointer to buffer to take signature
 215  * \param sig_len: length of the buffer (must be >= length of key N)
 216  *
 217  * Returns <0 for error, or 0 for success.
 218  *
 219  * This creates an RSA signature for a hash you already computed and provide.
 220  * You should have created the hash before calling this by iterating over the
 221  * actual payload you need to confirm.
 222  *
 223  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 224  */
 225 LWS_VISIBLE LWS_EXTERN int
 226 lws_genrsa_hash_sign(struct lws_genrsa_ctx *ctx, const uint8_t *in,
 227                      enum lws_genhash_types hash_type,
 228                      uint8_t *sig, size_t sig_len);
 229
 230 /** lws_genrsa_public_decrypt_destroy() - Destroy RSA public decrypt context
 231  *
 232  * \param ctx: your struct lws_genrsa_ctx
 233  *
 234  * Destroys any allocations related to \p ctx.
 235  *
 236  * This and related APIs operate identically with OpenSSL or mbedTLS backends.
 237  */
 238 LWS_VISIBLE LWS_EXTERN void
 239 lws_genrsa_destroy(struct lws_genrsa_ctx *ctx);
 240
 241 /** lws_genrsa_render_pkey_asn1() - Exports public or private key to ASN1/DER
 242  *
 243  * \param ctx: your struct lws_genrsa_ctx
 244  * \param _private: 0 = public part only, 1 = all parts of the key
 245  * \param pkey_asn1: pointer to buffer to take the ASN1
 246  * \param pkey_asn1_len: max size of the pkey_asn1_len
 247  *
 248  * Returns length of pkey_asn1 written, or -1 for error.
 249  */
 250 LWS_VISIBLE LWS_EXTERN int
 251 lws_genrsa_render_pkey_asn1(struct lws_genrsa_ctx *ctx, int _private,
 252                             uint8_t *pkey_asn1, size_t pkey_asn1_len);
 253 ///@}