libwebsockets
Lightweight C library for HTML5 websockets
|
Data Structures | |
struct | lws_jws_map |
struct | lws_jws |
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 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.
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
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_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
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_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
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_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
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_VISIBLE LWS_EXTERN void lws_jws_destroy | ( | struct lws_jws * | jws | ) |
#include <include/libwebsockets/lws-jws.h>
lws_jws_destroy() - scrub a jws
jws | pointer to the jws to destroy |
Call before the jws goes out of scope.
Elements defined in the jws are zeroed.
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
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_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
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_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
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_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
jws | pointer to the jws to initialize |
jwk | the jwk to use with this jws |
context | the lws_context to use |
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
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_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
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.
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
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.
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
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.
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
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.
Returns the length of the encoded signature written to b64_sig
, or -1.
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
jws | information to include in the signature |
compact | output buffer for compact format |
len | size of flattened output buffer |
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
jws | information to include in the signature |
flattened | output buffer for JSON |
len | size of flattened output buffer |