libwebsockets
Lightweight C library for HTML5 websockets
Generic RSA

Data Structures

struct  lws_genrsa_ctx
 

Enumerations

enum  enum_genrsa_mode { LGRSAM_PKCS1_1_5 , LGRSAM_PKCS1_OAEP_PSS , LGRSAM_COUNT }
 

Functions

LWS_VISIBLE LWS_EXTERN int lws_genrsa_create (struct lws_genrsa_ctx *ctx, const struct lws_gencrypto_keyelem *el, struct lws_context *context, enum enum_genrsa_mode mode, enum lws_genhash_types oaep_hashid)
 
LWS_VISIBLE LWS_EXTERN void lws_genrsa_destroy_elements (struct lws_gencrypto_keyelem *el)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_new_keypair (struct lws_context *context, struct lws_genrsa_ctx *ctx, enum enum_genrsa_mode mode, struct lws_gencrypto_keyelem *el, int bits)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_encrypt (struct lws_genrsa_ctx *ctx, const uint8_t *in, size_t in_len, uint8_t *out)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_private_encrypt (struct lws_genrsa_ctx *ctx, const uint8_t *in, size_t in_len, uint8_t *out)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_decrypt (struct lws_genrsa_ctx *ctx, const uint8_t *in, size_t in_len, uint8_t *out, size_t out_max)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_private_decrypt (struct lws_genrsa_ctx *ctx, const uint8_t *in, size_t in_len, uint8_t *out, size_t out_max)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_hash_sig_verify (struct lws_genrsa_ctx *ctx, const uint8_t *in, enum lws_genhash_types hash_type, const uint8_t *sig, size_t sig_len)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_hash_sign (struct lws_genrsa_ctx *ctx, const uint8_t *in, enum lws_genhash_types hash_type, uint8_t *sig, size_t sig_len)
 
LWS_VISIBLE LWS_EXTERN void lws_genrsa_destroy (struct lws_genrsa_ctx *ctx)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_render_pkey_asn1 (struct lws_genrsa_ctx *ctx, int _private, uint8_t *pkey_asn1, size_t pkey_asn1_len)
 

Detailed Description

Generic RSA related functions

Lws provides generic RSA functions that abstract the ones provided by whatever OpenSSL library you are linking against.

It lets you use the same code if you build against mbedtls or OpenSSL for example.


Data Structure Documentation

◆ lws_genrsa_ctx

struct lws_genrsa_ctx

Definition at line 45 of file lws-genrsa.h.

+ Collaboration diagram for lws_genrsa_ctx:
Data Fields
BIGNUM * bn[LWS_GENCRYPTO_RSA_KEYEL_COUNT]
EVP_PKEY_CTX * ctx
RSA * rsa
struct lws_context * context
enum enum_genrsa_mode mode

Enumeration Type Documentation

◆ enum_genrsa_mode

#include <include/libwebsockets/lws-genrsa.h>

Enumerator
LGRSAM_PKCS1_1_5 
LGRSAM_PKCS1_OAEP_PSS 
LGRSAM_COUNT 

Definition at line 38 of file lws-genrsa.h.

38  {
41 
43 };
@ LGRSAM_PKCS1_OAEP_PSS
Definition: lws-genrsa.h:40
@ LGRSAM_PKCS1_1_5
Definition: lws-genrsa.h:39
@ LGRSAM_COUNT
Definition: lws-genrsa.h:42

Function Documentation

◆ lws_genrsa_create()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_create ( struct lws_genrsa_ctx ctx,
const struct lws_gencrypto_keyelem el,
struct lws_context *  context,
enum enum_genrsa_mode  mode,
enum lws_genhash_types  oaep_hashid 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_public_decrypt_create() - Create RSA public decrypt context

Parameters
ctxyour struct lws_genrsa_ctx
elstruct prepared with key element data
contextlws_context for RNG
modeRSA mode, one of LGRSAM_ constants
oaep_hashidthe lws genhash id for the hash used in MFG1 hash used in OAEP mode - normally, SHA1

Creates an RSA context with a public key associated with it, formed from the key elements in el.

Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses. It's recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.

Returns 0 for OK or nonzero for error.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_destroy_elements()

LWS_VISIBLE LWS_EXTERN void lws_genrsa_destroy_elements ( struct lws_gencrypto_keyelem el)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_destroy_elements() - Free allocations in genrsa_elements

Parameters
elyour struct lws_gencrypto_keyelem

This is a helper for user code making use of struct lws_gencrypto_keyelem where the elements are allocated on the heap, it frees any non-NULL buf element and sets the buf to NULL.

NB: lws_genrsa_public_... apis do not need this as they take care of the key creation and destruction themselves.

◆ lws_genrsa_new_keypair()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_new_keypair ( struct lws_context *  context,
struct lws_genrsa_ctx ctx,
enum enum_genrsa_mode  mode,
struct lws_gencrypto_keyelem el,
int  bits 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_new_keypair() - Create new RSA keypair

Parameters
contextyour struct lws_context (may be used for RNG)
ctxyour struct lws_genrsa_ctx
modeRSA mode, one of LGRSAM_ constants
elstruct to get the new key element data allocated into it
bitskey size, eg, 4096

Creates a new RSA context and generates a new keypair into it, with bits bits.

Returns 0 for OK or nonzero for error.

Mode LGRSAM_PKCS1_1_5 is in widespread use but has weaknesses. It's recommended to use LGRSAM_PKCS1_OAEP_PSS for new implementations.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_public_encrypt()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_encrypt ( struct lws_genrsa_ctx ctx,
const uint8_t in,
size_t  in_len,
uint8_t out 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_public_encrypt() - Perform RSA public key encryption

Parameters
ctxyour struct lws_genrsa_ctx
inplaintext input
in_lenlength of plaintext input
outencrypted output

Performs PKCS1 v1.5 Encryption

Returns <0 for error, or length of decrypted data.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_private_encrypt()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_private_encrypt ( struct lws_genrsa_ctx ctx,
const uint8_t in,
size_t  in_len,
uint8_t out 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_private_encrypt() - Perform RSA private key encryption

Parameters
ctxyour struct lws_genrsa_ctx
inplaintext input
in_lenlength of plaintext input
outencrypted output

Performs PKCS1 v1.5 Encryption

Returns <0 for error, or length of decrypted data.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_public_decrypt()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_decrypt ( struct lws_genrsa_ctx ctx,
const uint8_t in,
size_t  in_len,
uint8_t out,
size_t  out_max 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_public_decrypt() - Perform RSA public key decryption

Parameters
ctxyour struct lws_genrsa_ctx
inencrypted input
in_lenlength of encrypted input
outdecrypted output
out_maxsize of output buffer

Performs PKCS1 v1.5 Decryption

Returns <0 for error, or length of decrypted data.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_private_decrypt()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_private_decrypt ( struct lws_genrsa_ctx ctx,
const uint8_t in,
size_t  in_len,
uint8_t out,
size_t  out_max 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_private_decrypt() - Perform RSA private key decryption

Parameters
ctxyour struct lws_genrsa_ctx
inencrypted input
in_lenlength of encrypted input
outdecrypted output
out_maxsize of output buffer

Performs PKCS1 v1.5 Decryption

Returns <0 for error, or length of decrypted data.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_hash_sig_verify()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_hash_sig_verify ( struct lws_genrsa_ctx ctx,
const uint8_t in,
enum lws_genhash_types  hash_type,
const uint8_t sig,
size_t  sig_len 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_hash_sig_verify() - Verifies RSA signature on a given hash

Parameters
ctxyour struct lws_genrsa_ctx
ininput to be hashed
hash_typeone of LWS_GENHASH_TYPE_
sigpointer to the signature we received with the payload
sig_lenlength of the signature we are checking in bytes

Returns <0 for error, or 0 if signature matches the payload + key.

This just looks at a hash... that's why there's no input length parameter, it's decided by the choice of hash. It's up to you to confirm separately the actual payload matches the hash that was confirmed by this to be validly signed.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_hash_sign()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_hash_sign ( struct lws_genrsa_ctx ctx,
const uint8_t in,
enum lws_genhash_types  hash_type,
uint8_t sig,
size_t  sig_len 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_hash_sign() - Creates an ECDSA signature for a hash you provide

Parameters
ctxyour struct lws_genrsa_ctx
ininput to be hashed and signed
hash_typeone of LWS_GENHASH_TYPE_
sigpointer to buffer to take signature
sig_lenlength of the buffer (must be >= length of key N)

Returns <0 for error, or sig_len for success.

This creates an RSA signature for a hash you already computed and provide. You should have created the hash before calling this by iterating over the actual payload you need to confirm.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_destroy()

LWS_VISIBLE LWS_EXTERN void lws_genrsa_destroy ( struct lws_genrsa_ctx ctx)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_public_decrypt_destroy() - Destroy RSA public decrypt context

Parameters
ctxyour struct lws_genrsa_ctx

Destroys any allocations related to ctx.

This and related APIs operate identically with OpenSSL or mbedTLS backends.

◆ lws_genrsa_render_pkey_asn1()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_render_pkey_asn1 ( struct lws_genrsa_ctx ctx,
int  _private,
uint8_t pkey_asn1,
size_t  pkey_asn1_len 
)

#include <include/libwebsockets/lws-genrsa.h>

lws_genrsa_render_pkey_asn1() - Exports public or private key to ASN1/DER

Parameters
ctxyour struct lws_genrsa_ctx
_private0 = public part only, 1 = all parts of the key
pkey_asn1pointer to buffer to take the ASN1
pkey_asn1_lenmax size of the pkey_asn1_len

Returns length of pkey_asn1 written, or -1 for error.