libwebsockets
Lightweight C library for HTML5 websockets
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.

Function Documentation

◆ 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
mapmap to create the element in
idxindex of element in the map to create
tempspace to allocate in
temp_lenavailable space at temp
lenlogical length of element
actual_alloc0 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_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
inpointer to b64 jose.payload[.hdr].sig
lenbytes available at in
mapoutput 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
inthe incoming plaintext
in_lenthe length of the incoming plaintext in bytes
outthe buffer to store the b64url encoded data to
out_maxthe length of out in bytes

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

◆ 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
inthe incoming compact serialized b64
lenthe length of the incoming compact serialized b64
mappointer to the results structure
map_b64NULL, or pointer to a second results structure taking block information about the undecoded b64
outbuffer to hold decoded results
out_lensize 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_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
jwspointer to the jws to destroy

Call before the jws goes out of scope.

Elements defined in the jws are zeroed.

◆ 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
mapmap to create the element in
idxindex of element in the map to create
tempspace to allocate in
temp_lenavailable space at temp
indata to duplicate into element
in_lenlength of data to duplicate
actual_alloc0 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_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
mapmap to create the element in
idxindex of element in the map to create
tempspace to allocate in
temp_lenavailable space at temp
inpointer to unencoded input
in_lenlength 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_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
inthe incoming plaintext
in_lenthe length of the incoming plaintext in bytes
firstnonzero if the first section
pthe buffer to store the b64url encoded data to
endjust 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_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
jwspointer to the jws to initialize
jwkthe jwk to use with this jws
contextthe lws_context to use

◆ 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
contextlws_context used for random
mapmap to create the element in
idxindex of element in the map to create
tempspace to allocate in
temp_lenavailable space at temp
random_lenlength of data to fill with random
actual_alloc0 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_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_b64pointers and lengths for each of the b64-encoded JWS elements
mappointers and lengths for each of the unencoded JWS elements
jwkpublic key
contextlws_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.

◆ 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
mappointers and lengths for each of the unencoded JWS elements
jwkpublic key
contextlws_context
tempscratchpad
temp_lenlength 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.

◆ 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
inpointer to b64 jose.payload[.hdr].sig
lenbytes available at in
mapmap to take decoded non-b64 content
jwkpublic key
contextlws_context
tempscratchpad
temp_lensize 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.

◆ 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
josejose header information
jwsinformation to include in the signature
b64_sigoutput buffer for b64 signature
sig_lensize 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.

Returns the length of the encoded signature written to b64_sig, or -1.

◆ 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
jwsinformation to include in the signature
compactoutput buffer for compact format
lensize of flattened output buffer

◆ 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
jwsinformation to include in the signature
flattenedoutput buffer for JSON
lensize of flattened output buffer

◆ 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
ctxthe lws_context
jwkthe signing key
algthe signing alg name, like "ES512"
outthe output buffer to hold the signed JWT in compact form
out_lenon entry, the length of out; on exit, the used amount of out
tempa temp scratchpad
tlavailable length of temp scratchpad
formata 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_compact() - generate a compact JWT using a key and JOSE header

Parameters
ctxthe lws_context
jwkthe signing key
infoinfo describing the JWT's content and output/temp buffers
formata 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_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
ctxthe lws_context
jwkthe key for checking the signature
alg_listthe expected alg name, like "ES512"
comthe compact JWT
lenthe length of com
tempa temp scratchpad
tlavailable length of temp scratchpad
outthe output buffer to hold the validated plaintext
out_lenon 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_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
inthe JWT payload
in_lenthe length of the JWT payload
issthe expected issuer of the token
audthe expected audience of the token
csrf_inNULL, or the csrf token that came in on a URL
suba buffer to hold the subject name in the JWT (eg, account name)
sub_lenthe max length of the sub buffer
secs_leftset 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.