libwebsockets
Lightweight C library for HTML5 websockets
hash

Data Structures

struct  lws_genhash_ctx
 
struct  lws_genhmac_ctx
 
struct  lws_genrsa_ctx
 

Macros

#define LWS_GENHASH_LARGEST   64
 

Enumerations

enum  lws_genhash_types {
  LWS_GENHASH_TYPE_UNKNOWN, LWS_GENHASH_TYPE_SHA1, LWS_GENHASH_TYPE_SHA256, LWS_GENHASH_TYPE_SHA384,
  LWS_GENHASH_TYPE_SHA512
}
 
enum  lws_genhmac_types { LWS_GENHMAC_TYPE_UNKNOWN, LWS_GENHMAC_TYPE_SHA256, LWS_GENHMAC_TYPE_SHA384, LWS_GENHMAC_TYPE_SHA512 }
 
enum  enum_genrsa_mode { LGRSAM_PKCS1_1_5, LGRSAM_PKCS1_OAEP_PSS, LGRSAM_COUNT }
 

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_genrsa_destroy_elements (struct lws_gencrypto_keyelem *el)
 
LWS_VISIBLE LWS_EXTERN int lws_genrsa_create (struct lws_genrsa_ctx *ctx, struct lws_gencrypto_keyelem *el, struct lws_context *context, enum enum_genrsa_mode mode)
 
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_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_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 Hash related functions

Lws provides generic hash / digest accessors that abstract the ones provided by whatever tls 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
ctxyour struct lws_genhash_ctx
resultNULL, 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
ctxyour struct lws_genhash_ctx
typeone 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
typeone 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
ctxyour struct lws_genhash_ctx
instart of the bytes to digest
lencount 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
ctxyour struct lws_genhmac_ctx
resultNULL, 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
ctxyour struct lws_genhmac_ctx
typeone of LWS_GENHMAC_TYPE_...
keypointer to the start of the HMAC key
key_lenlength 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
typeone 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
ctxyour struct lws_genhmac_ctx
instart of the bytes to digest
lencount 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_gencrypto_keyelem *  el,
struct lws_context *  context,
enum enum_genrsa_mode  mode 
)

#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

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()

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_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_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 0 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_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_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
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_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 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_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.