Data Structures
struct	lws_genhash_ctx

struct	lws_genhmac_ctx

struct	lws_genrsa_ctx

struct	lws_genrsa_element

struct	lws_genrsa_elements

Macros
#define	LWS_GENHASH_LARGEST 64

#define	LWS_COUNT_RSA_ELEMENTS JWK_KTY

Enumerations
enum	lws_genhash_types { LWS_GENHASH_TYPE_SHA1, LWS_GENHASH_TYPE_SHA256, LWS_GENHASH_TYPE_SHA384, LWS_GENHASH_TYPE_SHA512 }

enum	lws_genhmac_types { LWS_GENHMAC_TYPE_SHA256, LWS_GENHMAC_TYPE_SHA384, LWS_GENHMAC_TYPE_SHA512 }

enum	enum_jwk_tok { JWK_KEY_E, JWK_KEY_N, JWK_KEY_D, JWK_KEY_P, JWK_KEY_Q, JWK_KEY_DP, JWK_KEY_DQ, JWK_KEY_QI, JWK_KTY, JWK_KEY }

Functions
LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT	lws_genhash_size (enum lws_genhash_types type)

LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT	lws_genhmac_size (enum lws_genhmac_types type)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_genhash_init (struct lws_genhash_ctx *ctx, enum lws_genhash_types type)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_genhash_update (struct lws_genhash_ctx ctx, const void in, size_t len)

LWS_VISIBLE LWS_EXTERN int	lws_genhash_destroy (struct lws_genhash_ctx ctx, void result)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_genhmac_init (struct lws_genhmac_ctx ctx, enum lws_genhmac_types type, const uint8_t key, size_t key_len)

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_genhmac_update (struct lws_genhmac_ctx ctx, const void in, size_t len)

LWS_VISIBLE LWS_EXTERN int	lws_genhmac_destroy (struct lws_genhmac_ctx ctx, void result)

LWS_VISIBLE LWS_EXTERN void	lws_jwk_destroy_genrsa_elements (struct lws_genrsa_elements *el)

LWS_VISIBLE LWS_EXTERN int	lws_genrsa_create (struct lws_genrsa_ctx ctx, struct lws_genrsa_elements el)

LWS_VISIBLE LWS_EXTERN int	lws_genrsa_new_keypair (struct lws_context context, struct lws_genrsa_ctx ctx, struct lws_genrsa_elements *el, int bits)

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_public_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_public_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 Hash related functions

Lws provides generic hash / digest accessors 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.

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.

Function Documentation

◆ lws_genhash_destroy()

LWS_VISIBLE LWS_EXTERN int lws_genhash_destroy	(	struct lws_genhash_ctx *	ctx,
		void *	result
	)

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

lws_genhash_destroy() - copy out the result digest and destroy the ctx

Parameters

ctx	your struct lws_genhash_ctx
result	NULL, or where to copy the result hash

Finalizes the hash and copies out the digest. Destroys any allocations such that ctx can safely go out of scope after calling this.

NULL result is supported so that you can destroy the ctx cleanly on error conditions, where there is no valid result.

◆ lws_genhash_init()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_genhash_init	(	struct lws_genhash_ctx *	ctx,
		enum lws_genhash_types	type
	)

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

lws_genhash_init() - prepare your struct lws_genhash_ctx for use

Parameters

ctx	your struct lws_genhash_ctx
type	one of LWS_GENHASH_TYPE_...

Initializes the hash context for the type you requested

◆ lws_genhash_size()

LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT lws_genhash_size ( enum lws_genhash_types type )

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

lws_genhash_size() - get hash size in bytes

Parameters

type	one of LWS_GENHASH_TYPE_...

Returns number of bytes in this type of hash

◆ lws_genhash_update()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_genhash_update	(	struct lws_genhash_ctx *	ctx,
		const void *	in,
		size_t	len
	)

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

lws_genhash_update() - digest len bytes of the buffer starting at in

Parameters

ctx	your struct lws_genhash_ctx
in	start of the bytes to digest
len	count of bytes to digest

Updates the state of your hash context to reflect digesting len bytes from in

◆ lws_genhmac_destroy()

LWS_VISIBLE LWS_EXTERN int lws_genhmac_destroy	(	struct lws_genhmac_ctx *	ctx,
		void *	result
	)

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

lws_genhmac_destroy() - copy out the result digest and destroy the ctx

Parameters

ctx	your struct lws_genhmac_ctx
result	NULL, or where to copy the result hash

Finalizes the hash and copies out the digest. Destroys any allocations such that ctx can safely go out of scope after calling this.

NULL result is supported so that you can destroy the ctx cleanly on error conditions, where there is no valid result.

◆ lws_genhmac_init()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_genhmac_init	(	struct lws_genhmac_ctx *	ctx,
		enum lws_genhmac_types	type,
		const uint8_t *	key,
		size_t	key_len
	)

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

lws_genhmac_init() - prepare your struct lws_genhmac_ctx for use

Parameters

ctx	your struct lws_genhmac_ctx
type	one of LWS_GENHMAC_TYPE_...
key	pointer to the start of the HMAC key
key_len	length of the HMAC key

Initializes the hash context for the type you requested

If the return is nonzero, it failed and there is nothing needing to be destroyed.

◆ lws_genhmac_size()

LWS_VISIBLE LWS_EXTERN size_t LWS_WARN_UNUSED_RESULT lws_genhmac_size ( enum lws_genhmac_types type )

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

lws_genhmac_size() - get hash size in bytes

Parameters

type	one of LWS_GENHASH_TYPE_...

Returns number of bytes in this type of hmac

◆ lws_genhmac_update()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_genhmac_update	(	struct lws_genhmac_ctx *	ctx,
		const void *	in,
		size_t	len
	)

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

lws_genhmac_update() - digest len bytes of the buffer starting at in

Parameters

ctx	your struct lws_genhmac_ctx
in	start of the bytes to digest
len	count of bytes to digest

Updates the state of your hash context to reflect digesting len bytes from in

If the return is nonzero, it failed and needs destroying.

◆ lws_genrsa_create()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_create	(	struct lws_genrsa_ctx *	ctx,
		struct lws_genrsa_elements *	el
	)

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

lws_genrsa_public_decrypt_create() - Create RSA public decrypt context

Parameters

ctx	your struct lws_genrsa_ctx
el	struct prepared with key element data

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

Returns 0 for OK or nonzero for error.

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

ctx	your struct lws_genrsa_ctx

Destroys any allocations related to ctx.

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

◆ lws_genrsa_new_keypair()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_new_keypair	(	struct lws_context *	context,
		struct lws_genrsa_ctx *	ctx,
		struct lws_genrsa_elements *	el,
		int	bits
	)

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

lws_genrsa_new_keypair() - Create new RSA keypair

Parameters

context	your struct lws_context (may be used for RNG)
ctx	your struct lws_genrsa_ctx
el	struct to get the new key element data allocated into it
bits	key 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.

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 decryption

Parameters

ctx	your struct lws_genrsa_ctx
in	encrypted input
in_len	length of encrypted input
out	decrypted output
out_max	size of output buffer

Performs the decryption.

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

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

◆ lws_genrsa_public_sign()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_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_public_sign() - Create RSA signature

Parameters

ctx	your struct lws_genrsa_ctx
in	precomputed hash
hash_type	one of LWS_GENHASH_TYPE_
sig	pointer to buffer to take signature
sig_len	length of the buffer (must be >= length of key N)

Returns <0 for error, or 0 for success.

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

◆ lws_genrsa_public_verify()

LWS_VISIBLE LWS_EXTERN int lws_genrsa_public_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_public_verify() - Perform RSA public verification

Parameters

ctx	your struct lws_genrsa_ctx
in	unencrypted payload (usually a recomputed hash)
hash_type	one of LWS_GENHASH_TYPE_
sig	pointer to the signature we received with the payload
sig_len	length of the signature we are checking in bytes

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

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

ctx	your struct lws_genrsa_ctx
_private	0 = public part only, 1 = all parts of the key
pkey_asn1	pointer to buffer to take the ASN1
pkey_asn1_len	max size of the pkey_asn1_len

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

◆ lws_jwk_destroy_genrsa_elements()

LWS_VISIBLE LWS_EXTERN void lws_jwk_destroy_genrsa_elements ( struct lws_genrsa_elements * el )

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

lws_jwk_destroy_genrsa_elements() - Free allocations in genrsa_elements

Parameters

el	your struct lws_genrsa_elements

This is a helper for user code making use of struct lws_genrsa_elements 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.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Generic Hash related functions

Generic RSA related functions

Function Documentation

◆ lws_genhash_destroy()

◆ lws_genhash_init()

◆ lws_genhash_size()

◆ lws_genhash_update()

◆ lws_genhmac_destroy()

◆ lws_genhmac_init()

◆ lws_genhmac_size()

◆ lws_genhmac_update()

◆ lws_genrsa_create()

◆ lws_genrsa_destroy()

◆ lws_genrsa_new_keypair()

◆ lws_genrsa_public_decrypt()

◆ lws_genrsa_public_sign()

◆ lws_genrsa_public_verify()

◆ lws_genrsa_render_pkey_asn1()

◆ lws_jwk_destroy_genrsa_elements()