JSON Web Signature

Data Structures
struct	lws_jws_map
struct	lws_jws
struct	lws_jwt_sign_info

Macros
#define	LWS_JWS_MAX_SIGS   3

Enumerations
enum	enum_jws_sig_elements {   LJWS_JOSE , LJWS_PYLD , LJWS_SIG , LJWS_UHDR ,   LJWE_JOSE = 0 , LJWE_EKEY , LJWE_IV , LJWE_CTXT ,   LJWE_ATAG , LJWE_AAD , LWS_JWS_MAX_COMPACT_BLOCKS }

Functions
LWS_VISIBLE LWS_EXTERN void	lws_jws_init (struct lws_jws *jws, struct lws_jwk *jwk, struct lws_context *context)
LWS_VISIBLE LWS_EXTERN void	lws_jws_destroy (struct lws_jws *jws)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sig_confirm_compact (struct lws_jws_map *map, struct lws_jwk *jwk, struct lws_context *context, char *temp, int *temp_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sig_confirm_compact_b64_map (struct lws_jws_map *map_b64, struct lws_jwk *jwk, struct lws_context *context, char *temp, int *temp_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sig_confirm_compact_b64 (const char *in, size_t len, struct lws_jws_map *map, struct lws_jwk *jwk, struct lws_context *context, char *temp, int *temp_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sig_confirm (struct lws_jws_map *map_b64, struct lws_jws_map *map, struct lws_jwk *jwk, struct lws_context *context)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sign_from_b64 (struct lws_jose *jose, struct lws_jws *jws, char *b64_sig, size_t sig_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_compact_decode (const char *in, int len, struct lws_jws_map *map, struct lws_jws_map *map_b64, char *out, int *out_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_compact_encode (struct lws_jws_map *map_b64, const struct lws_jws_map *map, char *buf, int *out_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_sig_confirm_json (const char *in, size_t len, struct lws_jws *jws, struct lws_jwk *jwk, struct lws_context *context, char *temp, int *temp_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_write_flattened_json (struct lws_jws *jws, char *flattened, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_write_compact (struct lws_jws *jws, char *compact, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_dup_element (struct lws_jws_map *map, int idx, char *temp, int *temp_len, const void *in, size_t in_len, size_t actual_alloc)
LWS_VISIBLE LWS_EXTERN int	lws_jws_randomize_element (struct lws_context *context, struct lws_jws_map *map, int idx, char *temp, int *temp_len, size_t random_len, size_t actual_alloc)
LWS_VISIBLE LWS_EXTERN int	lws_jws_alloc_element (struct lws_jws_map *map, int idx, char *temp, int *temp_len, size_t len, size_t actual_alloc)
LWS_VISIBLE LWS_EXTERN int	lws_jws_encode_b64_element (struct lws_jws_map *map, int idx, char *temp, int *temp_len, const void *in, size_t in_len)
LWS_VISIBLE LWS_EXTERN int	lws_jws_b64_compact_map (const char *in, int len, struct lws_jws_map *map)
LWS_VISIBLE LWS_EXTERN int	lws_jws_base64_enc (const char *in, size_t in_len, char *out, size_t out_max)
LWS_VISIBLE LWS_EXTERN int	lws_jws_encode_section (const char *in, size_t in_len, int first, char **p, char *end)
LWS_VISIBLE LWS_EXTERN int	lws_jwt_signed_validate (struct lws_context *ctx, struct lws_jwk *jwk, const char *alg_list, const char *com, size_t len, char *temp, int tl, char *out, size_t *out_len)
LWS_VISIBLE LWS_EXTERN int	lws_jwt_sign_compact (struct lws_context *ctx, struct lws_jwk *jwk, const char *alg, char *out, size_t *out_len, char *temp, int tl, const char *format,...) LWS_FORMAT(8)
LWS_VISIBLE LWS_EXTERN int	lws_jwt_sign_via_info (struct lws_context *ctx, struct lws_jwk *jwk, const struct lws_jwt_sign_info *info, const char *format,...) LWS_FORMAT(4)
LWS_VISIBLE LWS_EXTERN int	lws_jwt_token_sanity (const char *in, size_t in_len, const char *iss, const char *aud, const char *csrf_in, char *sub, size_t sub_len, unsigned long *exp_unix_time)

Detailed Description

JSON Web Signature API

Lws provides an API to check and create RFC7515 JSON Web Signatures

SHA256/384/512 HMAC, and RSA 256/384/512 are supported.

The API uses your TLS library crypto, but works exactly the same no matter what your TLS backend is.

---

Data Structure Documentation

lws_jws_map

struct lws_jws_map

Definition at line 61 of file lws-jws.h.

Collaboration diagram for lws_jws_map:

Data Fields
const char *	buf[LWS_JWS_MAX_COMPACT_BLOCKS]
uint32_t	len[LWS_JWS_MAX_COMPACT_BLOCKS]

lws_jws

struct lws_jws

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

Collaboration diagram for lws_jws:

Data Fields
struct lws_jwk *	jwk
struct lws_context *	context
struct lws_jws_map map	map_b64

lws_jwt_sign_info

struct lws_jwt_sign_info

Definition at line 460 of file lws-jws.h.

Collaboration diagram for lws_jwt_sign_info:

Data Fields
const char *	alg	entry: signing alg name, like "RS256"
const char *	jose_hdr	entry: optional JOSE hdr; if present, alg field is ignored; instead the whole claim object has to be provided in this parameter
size_t	jose_hdr_len	entry: if jose_hdr is not NULL, JOSE header length without terminating '\0'
char *	out	exit: signed JWT in compact form
size_t *	out_len	entry,exit: buffer size of out; actual size of JWT on exit
char *	temp	exit undefined content, used by the function as a temporary scratchpad; MUST be large enogh to store various intermediate representations
int	tl	entry: size of temp buffer

Macro Definition Documentation

LWS_JWS_MAX_SIGS

#define LWS_JWS_MAX_SIGS   3

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

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

Enumeration Type Documentation

enum_jws_sig_elements

enum enum_jws_sig_elements

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

Enumerator
LJWS_JOSE
LJWS_PYLD
LJWS_SIG
LJWS_UHDR
LJWE_JOSE
LJWE_EKEY
LJWE_IV
LJWE_CTXT
LJWE_ATAG
LJWE_AAD
LWS_JWS_MAX_COMPACT_BLOCKS

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

                           {
 
        /* JWS block namespace */
        LJWS_JOSE,
        LJWS_PYLD,
        LJWS_SIG,
        LJWS_UHDR,
 
        /* JWE block namespace */
        LJWE_JOSE = 0,
        LJWE_EKEY,
        LJWE_IV,
        LJWE_CTXT,
        LJWE_ATAG,
        LJWE_AAD,
 
        LWS_JWS_MAX_COMPACT_BLOCKS
};

Function Documentation

lws_jws_init()

LWS_VISIBLE LWS_EXTERN void lws_jws_init	(	struct lws_jws *	jws,
		struct lws_jwk *	jwk,
		struct lws_context *	context
	)

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

lws_jws_init() - initialize a jws for use

Parameters

jws	pointer to the jws to initialize
jwk	the jwk to use with this jws
context	the lws_context to use

lws_jws_destroy()

LWS_VISIBLE LWS_EXTERN void lws_jws_destroy

(

struct lws_jws *

jws

)

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

lws_jws_destroy() - scrub a jws

Parameters

jws	pointer to the jws to destroy

Call before the jws goes out of scope.

Elements defined in the jws are zeroed.

lws_jws_sig_confirm_compact()

LWS_VISIBLE LWS_EXTERN int lws_jws_sig_confirm_compact	(	struct lws_jws_map *	map,
		struct lws_jwk *	jwk,
		struct lws_context *	context,
		char *	temp,
		int *	temp_len
	)

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

lws_jws_sig_confirm_compact() - check signature

Parameters

map	pointers and lengths for each of the unencoded JWS elements
jwk	public key
context	lws_context
temp	scratchpad
temp_len	length of scratchpad

Confirms the signature on a JWS. Use if you have non-b64 plain JWS elements in a map... it'll make a temp b64 version needed for comparison. See below for other variants.

Returns 0 on match, else nonzero.

lws_jws_sig_confirm_compact_b64_map()

LWS_VISIBLE LWS_EXTERN int lws_jws_sig_confirm_compact_b64_map	(	struct lws_jws_map *	map_b64,
		struct lws_jwk *	jwk,
		struct lws_context *	context,
		char *	temp,
		int *	temp_len
	)

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

lws_jws_sig_confirm_compact_b64()

LWS_VISIBLE LWS_EXTERN int lws_jws_sig_confirm_compact_b64	(	const char *	in,
		size_t	len,
		struct lws_jws_map *	map,
		struct lws_jwk *	jwk,
		struct lws_context *	context,
		char *	temp,
		int *	temp_len
	)

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

lws_jws_sig_confirm_compact_b64() - check signature on b64 compact JWS

Parameters

in	pointer to b64 jose.payload[.hdr].sig
len	bytes available at in
map	map to take decoded non-b64 content
jwk	public key
context	lws_context
temp	scratchpad
temp_len	size of scratchpad

Confirms the signature on a JWS. Use if you have you have b64 compact layout (jose.payload.hdr.sig) as an aggregated string... it'll make a temp plain version needed for comparison.

Returns 0 on match, else nonzero.

lws_jws_sig_confirm()

LWS_VISIBLE LWS_EXTERN int lws_jws_sig_confirm	(	struct lws_jws_map *	map_b64,
		struct lws_jws_map *	map,
		struct lws_jwk *	jwk,
		struct lws_context *	context
	)

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

lws_jws_sig_confirm() - check signature on plain + b64 JWS elements

Parameters

map_b64	pointers and lengths for each of the b64-encoded JWS elements
map	pointers and lengths for each of the unencoded JWS elements
jwk	public key
context	lws_context

Confirms the signature on a JWS. Use if you have you already have both b64 compact layout (jose.payload.hdr.sig) and decoded JWS elements in maps.

If you had the b64 string and called lws_jws_compact_decode() on it, you will end up with both maps, and can use this api version, saving needlessly regenerating any temp map.

Returns 0 on match, else nonzero.

lws_jws_sign_from_b64()

LWS_VISIBLE LWS_EXTERN int lws_jws_sign_from_b64	(	struct lws_jose *	jose,
		struct lws_jws *	jws,
		char *	b64_sig,
		size_t	sig_len
	)

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

lws_jws_sign_from_b64() - add b64 sig to b64 hdr + payload

Parameters

jose	jose header information
jws	information to include in the signature
b64_sig	output buffer for b64 signature
sig_len	size of b64_sig output buffer

This adds a b64-coded JWS signature of the b64-encoded protected header and b64-encoded payload, at b64_sig. The signature will be as large as the N element of the RSA key when the RSA key is used, eg, 512 bytes for a 4096-bit key, and then b64-encoding on top.

In some special cases, there is only payload to sign and no header, in that case b64_hdr may be NULL, and only the payload will be hashed before signing.

If successful, returns the length of the encoded signature written to b64_sig. If the jose signing type is unknown, 0 is returned. Otherwise -1 indicates failure.

lws_jws_compact_decode()

LWS_VISIBLE LWS_EXTERN int lws_jws_compact_decode	(	const char *	in,
		int	len,
		struct lws_jws_map *	map,
		struct lws_jws_map *	map_b64,
		char *	out,
		int *	out_len
	)

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

lws_jws_compact_decode() - converts and maps compact serialization b64 sections

Parameters

in	the incoming compact serialized b64
len	the length of the incoming compact serialized b64
map	pointer to the results structure
map_b64	NULL, or pointer to a second results structure taking block information about the undecoded b64
out	buffer to hold decoded results
out_len	size of out in bytes

Returns number of sections (2 if "none", else 3), or -1 if illegal.

map is set to point to the start and hold the length of each decoded block. If map_b64 is non-NULL, then it's set with information about the input b64 blocks.

lws_jws_compact_encode()

LWS_VISIBLE LWS_EXTERN int lws_jws_compact_encode	(	struct lws_jws_map *	map_b64,
		const struct lws_jws_map *	map,
		char *	buf,
		int *	out_len
	)

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

lws_jws_sig_confirm_json()

LWS_VISIBLE LWS_EXTERN int lws_jws_sig_confirm_json	(	const char *	in,
		size_t	len,
		struct lws_jws *	jws,
		struct lws_jwk *	jwk,
		struct lws_context *	context,
		char *	temp,
		int *	temp_len
	)

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

lws_jws_write_flattened_json()

LWS_VISIBLE LWS_EXTERN int lws_jws_write_flattened_json	(	struct lws_jws *	jws,
		char *	flattened,
		size_t	len
	)

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

lws_jws_write_flattened_json() - create flattened JSON sig

Parameters

jws	information to include in the signature
flattened	output buffer for JSON
len	size of flattened output buffer

lws_jws_write_compact()

LWS_VISIBLE LWS_EXTERN int lws_jws_write_compact	(	struct lws_jws *	jws,
		char *	compact,
		size_t	len
	)

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

lws_jws_write_compact() - create flattened JSON sig

Parameters

jws	information to include in the signature
compact	output buffer for compact format
len	size of flattened output buffer

lws_jws_dup_element()

LWS_VISIBLE LWS_EXTERN int lws_jws_dup_element	(	struct lws_jws_map *	map,
		int	idx,
		char *	temp,
		int *	temp_len,
		const void *	in,
		size_t	in_len,
		size_t	actual_alloc
	)

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

lws_jws_dup_element() - allocate space for an element and copy data into it

Parameters

map	map to create the element in
idx	index of element in the map to create
temp	space to allocate in
temp_len	available space at temp
in	data to duplicate into element
in_len	length of data to duplicate
actual_alloc	0 for same as in_len, else actual allocation size

Copies in_len from in to temp, if temp_len is sufficient.

Returns 0 or -1 if not enough space in temp / temp_len.

Over-allocation can be acheived by setting actual_alloc to the real allocation desired... in_len will be copied into it.

*temp_len is reduced by actual_alloc if successful.

lws_jws_randomize_element()

LWS_VISIBLE LWS_EXTERN int lws_jws_randomize_element	(	struct lws_context *	context,
		struct lws_jws_map *	map,
		int	idx,
		char *	temp,
		int *	temp_len,
		size_t	random_len,
		size_t	actual_alloc
	)

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

lws_jws_randomize_element() - create an element and fill with random

Parameters

context	lws_context used for random
map	map to create the element in
idx	index of element in the map to create
temp	space to allocate in
temp_len	available space at temp
random_len	length of data to fill with random
actual_alloc	0 for same as random_len, else actual allocation size

Randomize random_len bytes at temp, if temp_len is sufficient.

Returns 0 or -1 if not enough space in temp / temp_len.

Over-allocation can be acheived by setting actual_alloc to the real allocation desired... the first random_len will be filled with random.

*temp_len is reduced by actual_alloc if successful.

lws_jws_alloc_element()

LWS_VISIBLE LWS_EXTERN int lws_jws_alloc_element	(	struct lws_jws_map *	map,
		int	idx,
		char *	temp,
		int *	temp_len,
		size_t	len,
		size_t	actual_alloc
	)

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

lws_jws_alloc_element() - create an element and reserve space for content

Parameters

map	map to create the element in
idx	index of element in the map to create
temp	space to allocate in
temp_len	available space at temp
len	logical length of element
actual_alloc	0 for same as len, else actual allocation size

Allocate len bytes at temp, if temp_len is sufficient.

Returns 0 or -1 if not enough space in temp / temp_len.

Over-allocation can be acheived by setting actual_alloc to the real allocation desired... the element logical length will be set to len.

*temp_len is reduced by actual_alloc if successful.

lws_jws_encode_b64_element()

LWS_VISIBLE LWS_EXTERN int lws_jws_encode_b64_element	(	struct lws_jws_map *	map,
		int	idx,
		char *	temp,
		int *	temp_len,
		const void *	in,
		size_t	in_len
	)

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

lws_jws_encode_b64_element() - create an b64-encoded element

Parameters

map	map to create the element in
idx	index of element in the map to create
temp	space to allocate in
temp_len	available space at temp
in	pointer to unencoded input
in_len	length of unencoded input

Allocate len bytes at temp, if temp_len is sufficient.

Returns 0 or -1 if not enough space in temp / temp_len.

Over-allocation can be acheived by setting actual_alloc to the real allocation desired... the element logical length will be set to len.

*temp_len is reduced by actual_alloc if successful.

lws_jws_b64_compact_map()

LWS_VISIBLE LWS_EXTERN int lws_jws_b64_compact_map	(	const char *	in,
		int	len,
		struct lws_jws_map *	map
	)

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

lws_jws_b64_compact_map() - find block starts and lengths in compact b64

Parameters

in	pointer to b64 jose.payload[.hdr].sig
len	bytes available at in
map	output struct with pointers and lengths for each JWS element

Scans a jose.payload[.hdr].sig b64 string and notes where the blocks start and their length into map.

Returns number of blocks if OK. May return <0 if malformed. May not fill all map entries.

lws_jws_base64_enc()

LWS_VISIBLE LWS_EXTERN int lws_jws_base64_enc	(	const char *	in,
		size_t	in_len,
		char *	out,
		size_t	out_max
	)

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

lws_jws_base64_enc() - encode input data into b64url data

Parameters

in	the incoming plaintext
in_len	the length of the incoming plaintext in bytes
out	the buffer to store the b64url encoded data to
out_max	the length of out in bytes

Returns either -1 if problems, or the number of bytes written to out.

lws_jws_encode_section()

LWS_VISIBLE LWS_EXTERN int lws_jws_encode_section	(	const char *	in,
		size_t	in_len,
		int	first,
		char **	p,
		char *	end
	)

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

lws_jws_encode_section() - encode input data into b64url data, prepending . if not first

Parameters

in	the incoming plaintext
in_len	the length of the incoming plaintext in bytes
first	nonzero if the first section
p	the buffer to store the b64url encoded data to
end	just past the end of p

Returns either -1 if problems, or the number of bytes written to out. If the section is not the first one, '.' is prepended.

lws_jwt_signed_validate()

LWS_VISIBLE LWS_EXTERN int lws_jwt_signed_validate	(	struct lws_context *	ctx,
		struct lws_jwk *	jwk,
		const char *	alg_list,
		const char *	com,
		size_t	len,
		char *	temp,
		int	tl,
		char *	out,
		size_t *	out_len
	)

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

lws_jwt_signed_validate() - check a compact JWT against a key and alg

Parameters

ctx	the lws_context
jwk	the key for checking the signature
alg_list	the expected alg name, like "ES512"
com	the compact JWT
len	the length of com
temp	a temp scratchpad
tl	available length of temp scratchpad
out	the output buffer to hold the validated plaintext
out_len	on entry, max length of out; on exit, used length of out

Returns nonzero if the JWT cannot be validated or the plaintext can't fit the provided output buffer, or 0 if it is validated as being signed by the provided jwk.

If validated, the plaintext in the JWT is copied into out and out_len set to the used length.

temp can be discarded or reused after the call returned, it's used to hold transformations of the B64 JWS in the JWT.

lws_jwt_sign_compact()

LWS_VISIBLE LWS_EXTERN int lws_jwt_sign_compact	(	struct lws_context *	ctx,
		struct lws_jwk *	jwk,
		const char *	alg,
		char *	out,
		size_t *	out_len,
		char *	temp,
		int	tl,
		const char *	format,
			...
	)

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

lws_jwt_sign_compact() - generate a compact JWT using a key and alg

Parameters

ctx	the lws_context
jwk	the signing key
alg	the signing alg name, like "ES512"
out	the output buffer to hold the signed JWT in compact form
out_len	on entry, the length of out; on exit, the used amount of out
temp	a temp scratchpad
tl	available length of temp scratchpad
format	a printf style format specification
...	zero or more args for the format specification

Creates a JWT in a single step, from the format string and args through to outputting a well-formed compact JWT representation in out.

Returns 0 if all is well and *out_len is the amount of data in out, else nonzero if failed. Temp must be large enough to hold various intermediate representations.

lws_jwt_sign_via_info()

LWS_VISIBLE LWS_EXTERN int lws_jwt_sign_via_info	(	struct lws_context *	ctx,
		struct lws_jwk *	jwk,
		const struct lws_jwt_sign_info *	info,
		const char *	format,
			...
	)

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

lws_jwt_sign_via_info() - generate a compact JWT using a key and JOSE header

Parameters

ctx	the lws_context
jwk	the signing key
info	info describing the JWT's content and output/temp buffers
format	a printf style format specification of the claims object
...	zero or more args for the format specification

Creates a JWT in a single step, from the format string and args through to outputting a well-formed compact JWT representation in out. The provided JOSE header's syntax is checked before it is added to the JWT.

Returns 0 if all is well and *out_len is the amount of data in out, else nonzero if failed. Temp must be large enough to hold various intermediate representations.

lws_jwt_token_sanity()

LWS_VISIBLE LWS_EXTERN int lws_jwt_token_sanity	(	const char *	in,
		size_t	in_len,
		const char *	iss,
		const char *	aud,
		const char *	csrf_in,
		char *	sub,
		size_t	sub_len,
		unsigned long *	exp_unix_time
	)

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

lws_jwt_token_sanity() - check a validated jwt payload for sanity

Parameters

in	the JWT payload
in_len	the length of the JWT payload
iss	the expected issuer of the token
aud	the expected audience of the token
csrf_in	NULL, or the csrf token that came in on a URL
sub	a buffer to hold the subject name in the JWT (eg, account name)
sub_len	the max length of the sub buffer
secs_left	set to the number of seconds of valid auth left if valid

This performs some generic sanity tests on validated JWT payload...

• the issuer is as expected
• the audience is us
• current time is OK for nbf ("not before") in the token
• current time is OK for exp ("expiry") in the token
• if csrf_in is not NULL, that the JWK has a csrf and it matches it
• if sub is not NULL, that the JWK provides a subject (and copies it to sub)

If the tests pass, *secs_left is set to the number of remaining seconds the auth is valid.

Returns 0 if no inconsistency, else nonzero.