AES

Data Structures
struct	lws_genaes_ctx
struct	lws_chacha_ctx
struct	lws_genchacha_ctx

Macros
#define	LWS_AES_BLOCKSIZE   128
#define	LWS_AES_CBC_BLOCKLEN   16
#define	LWS_CHACHA_MINKEYLEN   16
#define	LWS_CHACHA_NONCELEN   8
#define	LWS_CHACHA_CTRLEN   8
#define	LWS_CHACHA_STATELEN   (LWS_CHACHA_NONCELEN+LWS_CHACHA_CTRLEN)
#define	LWS_CHACHA_BLOCKLEN   64
#define	LWS_POLY1305_TAGLEN   16
#define	LWS_POLY1305_KEYLEN   32

Enumerations
enum	enum_aes_modes {   LWS_GAESM_CBC , LWS_GAESM_CFB128 , LWS_GAESM_CFB8 , LWS_GAESM_CTR ,   LWS_GAESM_ECB , LWS_GAESM_OFB , LWS_GAESM_XTS , LWS_GAESM_GCM ,   LWS_GAESM_KW }
enum	enum_aes_operation { LWS_GAESO_ENC , LWS_GAESO_DEC }
enum	enum_aes_padding { LWS_GAESP_NO_PADDING , LWS_GAESP_WITH_PADDING }

Functions
LWS_VISIBLE LWS_EXTERN int	lws_genaes_create (struct lws_genaes_ctx *ctx, enum enum_aes_operation op, enum enum_aes_modes mode, struct lws_gencrypto_keyelem *el, enum enum_aes_padding padding, void *engine)
LWS_VISIBLE LWS_EXTERN int	lws_genaes_destroy (struct lws_genaes_ctx *ctx, unsigned char *tag, size_t tlen)
LWS_VISIBLE LWS_EXTERN int	lws_genaes_crypt (struct lws_genaes_ctx *ctx, const uint8_t *in, size_t len, uint8_t *out, uint8_t *iv_or_nonce_ctr_or_data_unit_16, uint8_t *stream_block_16, size_t *nc_or_iv_off, int taglen)
LWS_VISIBLE LWS_EXTERN void	lws_chacha_keysetup (struct lws_chacha_ctx *x, const uint8_t *k, uint32_t kbits)
LWS_VISIBLE LWS_EXTERN void	lws_chacha_ivsetup (struct lws_chacha_ctx *x, const uint8_t *iv, const uint8_t *counter)
LWS_VISIBLE LWS_EXTERN void	lws_chacha_ivsetup_ietf (struct lws_chacha_ctx *x, const uint8_t *nonce, uint32_t counter)
LWS_VISIBLE LWS_EXTERN void	lws_chacha_encrypt_bytes (struct lws_chacha_ctx *x, const uint8_t *m, uint8_t *c, uint32_t bytes)
LWS_VISIBLE LWS_EXTERN void	lws_poly1305_auth (uint8_t out[LWS_POLY1305_TAGLEN], const uint8_t *m, size_t inlen, const uint8_t key[LWS_POLY1305_KEYLEN])
LWS_VISIBLE LWS_EXTERN int	lws_genchacha_create (struct lws_genchacha_ctx *ctx, enum enum_aes_operation op, struct lws_gencrypto_keyelem *el, void *engine)
LWS_VISIBLE LWS_EXTERN int	lws_genchacha_destroy (struct lws_genchacha_ctx *ctx)
LWS_VISIBLE LWS_EXTERN int	lws_genchacha_crypt (struct lws_genchacha_ctx *ctx, const uint8_t *in, size_t len, uint8_t *out, const uint8_t *nonce, const uint8_t *aad, size_t aad_len, uint8_t *tag, size_t tag_len)
LWS_VISIBLE LWS_EXTERN int	lws_genchacha_stream (struct lws_genchacha_ctx *ctx, const uint8_t *in, size_t len, uint8_t *out, const uint8_t *nonce, size_t nonce_len)

Detailed Description

Generic AES related functions

Lws provides generic AES functions 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 ChaCha20 and Poly1305 related functions

Lws provides generic ChaCha20 and Poly1305 functions.

---

Data Structure Documentation

lws_genaes_ctx

struct lws_genaes_ctx

Definition at line 68 of file lws-genaes.h.

Collaboration diagram for lws_genaes_ctx:

Data Fields
EVP_CIPHER_CTX *	ctx
const EVP_CIPHER *	cipher
ENGINE *	engine
char	init
unsigned char	tag[16]
struct lws_gencrypto_keyelem *	k
enum enum_aes_operation	op
enum enum_aes_modes	mode
enum enum_aes_padding	padding
int	taglen
char	underway
unsigned char	buf[16]
int	buf_len

lws_chacha_ctx

struct lws_chacha_ctx

Definition at line 47 of file lws-genchacha.h.

Collaboration diagram for lws_chacha_ctx:

Data Fields
uint32_t	input[16]

lws_genchacha_ctx

struct lws_genchacha_ctx

Definition at line 107 of file lws-genchacha.h.

Collaboration diagram for lws_genchacha_ctx:

Data Fields
struct lws_chacha_ctx	native_ctx
struct lws_gencrypto_keyelem *	k
enum enum_aes_operation	op
void *	engine

Macro Definition Documentation

LWS_AES_BLOCKSIZE

#define LWS_AES_BLOCKSIZE   128

#include <lws-genaes.h>

Definition at line 65 of file lws-genaes.h.

LWS_AES_CBC_BLOCKLEN

#define LWS_AES_CBC_BLOCKLEN   16

#include <lws-genaes.h>

Definition at line 66 of file lws-genaes.h.

LWS_CHACHA_MINKEYLEN

#define LWS_CHACHA_MINKEYLEN   16

#include <lws-genchacha.h>

Definition at line 41 of file lws-genchacha.h.

LWS_CHACHA_NONCELEN

#define LWS_CHACHA_NONCELEN   8

#include <lws-genchacha.h>

Definition at line 42 of file lws-genchacha.h.

LWS_CHACHA_CTRLEN

#define LWS_CHACHA_CTRLEN   8

#include <lws-genchacha.h>

Definition at line 43 of file lws-genchacha.h.

LWS_CHACHA_STATELEN

#define LWS_CHACHA_STATELEN   (LWS_CHACHA_NONCELEN+LWS_CHACHA_CTRLEN)

#include <lws-genchacha.h>

Definition at line 44 of file lws-genchacha.h.

LWS_CHACHA_BLOCKLEN

#define LWS_CHACHA_BLOCKLEN   64

#include <lws-genchacha.h>

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

LWS_POLY1305_TAGLEN

#define LWS_POLY1305_TAGLEN   16

#include <lws-genchacha.h>

Definition at line 93 of file lws-genchacha.h.

Referenced by lws_poly1305_auth().

LWS_POLY1305_KEYLEN

#define LWS_POLY1305_KEYLEN   32

#include <lws-genchacha.h>

Definition at line 94 of file lws-genchacha.h.

Referenced by lws_poly1305_auth().

Enumeration Type Documentation

enum_aes_modes

enum enum_aes_modes

#include <lws-genaes.h>

Enumerator
LWS_GAESM_CBC
LWS_GAESM_CFB128
LWS_GAESM_CFB8
LWS_GAESM_CTR
LWS_GAESM_ECB
LWS_GAESM_OFB
LWS_GAESM_XTS
LWS_GAESM_GCM
LWS_GAESM_KW

Definition at line 41 of file lws-genaes.h.

                    {
        LWS_GAESM_CBC,
        LWS_GAESM_CFB128,
        LWS_GAESM_CFB8,
        LWS_GAESM_CTR,
        LWS_GAESM_ECB,
        LWS_GAESM_OFB,
        LWS_GAESM_XTS,          /* care... requires double-length key */
        LWS_GAESM_GCM,
        LWS_GAESM_KW,
};

enum_aes_operation

enum enum_aes_operation

#include <lws-genaes.h>

Enumerator
LWS_GAESO_ENC
LWS_GAESO_DEC

Definition at line 53 of file lws-genaes.h.

                        {
        LWS_GAESO_ENC,
        LWS_GAESO_DEC
};

enum_aes_padding

enum enum_aes_padding

#include <lws-genaes.h>

Enumerator
LWS_GAESP_NO_PADDING
LWS_GAESP_WITH_PADDING

Definition at line 58 of file lws-genaes.h.

                      {
        LWS_GAESP_NO_PADDING,
        LWS_GAESP_WITH_PADDING
};

Function Documentation

lws_genaes_create()

LWS_VISIBLE LWS_EXTERN int lws_genaes_create	(	struct lws_genaes_ctx *	ctx,
		enum enum_aes_operation	op,
		enum enum_aes_modes	mode,
		struct lws_gencrypto_keyelem *	el,
		enum enum_aes_padding	padding,
		void *	engine )

#include <lws-genaes.h>

lws_genaes_create() - Create genaes AES context

Parameters

ctx	your struct lws_genaes_ctx
op	LWS_GAESO_ENC or LWS_GAESO_DEC
mode	one of LWS_GAESM_
el	struct prepared with key element data
padding	0 = no padding, 1 = padding
engine	if openssl engine used, pass the pointer here

Creates an AES context with a 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.

References LWS_EXTERN, and LWS_VISIBLE.

lws_genaes_destroy()

LWS_VISIBLE LWS_EXTERN int lws_genaes_destroy	(	struct lws_genaes_ctx *	ctx,
		unsigned char *	tag,
		size_t	tlen )

#include <lws-genaes.h>

lws_genaes_destroy() - Destroy genaes AES context

Parameters

ctx	your struct lws_genaes_ctx
tag	NULL, or, GCM-only: buffer to receive tag
tlen	0, or, GCM-only: length of tag buffer

Destroys any allocations related to ctx.

For GCM only, up to tlen bytes of tag buffer will be set on exit.

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

References LWS_EXTERN, and LWS_VISIBLE.

lws_genaes_crypt()

LWS_VISIBLE LWS_EXTERN int lws_genaes_crypt	(	struct lws_genaes_ctx *	ctx,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	out,
		uint8_t *	iv_or_nonce_ctr_or_data_unit_16,
		uint8_t *	stream_block_16,
		size_t *	nc_or_iv_off,
		int	taglen )

#include <lws-genaes.h>

lws_genaes_crypt() - Encrypt or decrypt

Parameters

ctx	your struct lws_genaes_ctx
in	input plaintext or ciphertext
len	length of input (which is always length of output)
out	output plaintext or ciphertext
iv_or_nonce_ctr_or_data_unit_16	NULL, iv, nonce_ctr16, or data_unit16
stream_block_16	pointer to 16-byte stream block for CTR mode only
nc_or_iv_off	NULL or pointer to nc, or iv_off
taglen	length of tag

Encrypts or decrypts using the AES mode set when the ctx was created. The last three arguments have different meanings depending on the mode:

                          KW   CBC  CFB128 CFB8 CTR    ECB  OFB    XTS

iv_or_nonce_ct.._unit_16 : iv iv iv iv nonce NULL iv dataunt stream_block_16 : NULL NULL NULL NULL stream NULL NULL NULL nc_or_iv_off : NULL NULL iv_off NULL nc_off NULL iv_off NULL

For GCM:

iv_or_nonce_ctr_or_data_unit_16 : iv stream_block_16 : pointer to tag nc_or_iv_off : set pointed-to size_t to iv length in : first call: additional data, subsequently : input data len : first call: add data length, subsequently : input / output length

The length of the optional arg is always 16 if used, regardless of the mode.

Returns 0 for OK or nonzero for error.

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

lws_chacha_keysetup()

LWS_VISIBLE LWS_EXTERN void lws_chacha_keysetup	(	struct lws_chacha_ctx *	x,
		const uint8_t *	k,
		uint32_t	kbits )

#include <lws-genchacha.h>

lws_chacha_keysetup() - Setup ChaCha20 context with key

Parameters

x	your struct lws_chacha_ctx
k	key bytes
kbits	key size in bits (usually 256)

References LWS_EXTERN, and LWS_VISIBLE.

lws_chacha_ivsetup()

LWS_VISIBLE LWS_EXTERN void lws_chacha_ivsetup	(	struct lws_chacha_ctx *	x,
		const uint8_t *	iv,
		const uint8_t *	counter )

#include <lws-genchacha.h>

lws_chacha_ivsetup() - Setup ChaCha20 context with IV and counter (DJB 64-bit style)

Parameters

x	your struct lws_chacha_ctx
iv	8-byte initialization vector
counter	optional 8-byte counter (can be NULL)

References LWS_EXTERN, and LWS_VISIBLE.

lws_chacha_ivsetup_ietf()

LWS_VISIBLE LWS_EXTERN void lws_chacha_ivsetup_ietf	(	struct lws_chacha_ctx *	x,
		const uint8_t *	nonce,
		uint32_t	counter )

#include <lws-genchacha.h>

lws_chacha_ivsetup_ietf() - Setup ChaCha20 context with IV and counter (IETF 96-bit style)

Parameters

x	your struct lws_chacha_ctx
nonce	12-byte nonce
counter	32-bit counter

References LWS_EXTERN, and LWS_VISIBLE.

lws_chacha_encrypt_bytes()

LWS_VISIBLE LWS_EXTERN void lws_chacha_encrypt_bytes	(	struct lws_chacha_ctx *	x,
		const uint8_t *	m,
		uint8_t *	c,
		uint32_t	bytes )

#include <lws-genchacha.h>

lws_chacha_encrypt_bytes() - Encrypt/Decrypt bytes using ChaCha20

Parameters

x	your struct lws_chacha_ctx
m	input data
c	output data
bytes	number of bytes to process

lws_poly1305_auth()

LWS_VISIBLE LWS_EXTERN void lws_poly1305_auth	(	uint8_t	out[LWS_POLY1305_TAGLEN],
		const uint8_t *	m,
		size_t	inlen,
		const uint8_t	key[LWS_POLY1305_KEYLEN] )

#include <lws-genchacha.h>

lws_poly1305_auth() - Poly1305 one-shot authenticator

Parameters

out	16-byte output tag
m	input message
inlen	length of input message
key	32-byte key

References LWS_POLY1305_KEYLEN, and LWS_POLY1305_TAGLEN.

lws_genchacha_create()

LWS_VISIBLE LWS_EXTERN int lws_genchacha_create	(	struct lws_genchacha_ctx *	ctx,
		enum enum_aes_operation	op,
		struct lws_gencrypto_keyelem *	el,
		void *	engine )

#include <lws-genchacha.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_genchacha_destroy()

LWS_VISIBLE LWS_EXTERN int lws_genchacha_destroy

(

struct lws_genchacha_ctx *

ctx

)

#include <lws-genchacha.h>

References LWS_EXTERN, and LWS_VISIBLE.

lws_genchacha_crypt()

LWS_VISIBLE LWS_EXTERN int lws_genchacha_crypt	(	struct lws_genchacha_ctx *	ctx,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	out,
		const uint8_t *	nonce,
		const uint8_t *	aad,
		size_t	aad_len,
		uint8_t *	tag,
		size_t	tag_len )

#include <lws-genchacha.h>

lws_genchacha_crypt() - One-shot AEAD encrypt/decrypt

Parameters

ctx	your struct lws_genchacha_ctx
in	input plaintext or ciphertext
len	length of input
out	output plaintext or ciphertext
nonce	12-byte nonce
aad	additional authenticated data
aad_len	length of aad
tag	tag buffer (written on enc, checked on dec)
tag_len	usually 16

Returns 0 for OK or nonzero for error.

References LWS_EXTERN, and LWS_VISIBLE.

lws_genchacha_stream()

LWS_VISIBLE LWS_EXTERN int lws_genchacha_stream	(	struct lws_genchacha_ctx *	ctx,
		const uint8_t *	in,
		size_t	len,
		uint8_t *	out,
		const uint8_t *	nonce,
		size_t	nonce_len )

#include <lws-genchacha.h>

lws_genchacha_stream() - Raw ChaCha20 keystream

Parameters

ctx	your struct lws_genchacha_ctx
in	input plaintext or ciphertext
len	length of input
out	output plaintext or ciphertext
nonce	12-byte or 16-byte nonce/counter
nonce_len	length of nonce

Returns 0 for OK or nonzero for error.