JSON Web Keys

Data Structures
struct	lws_jwk
struct	lws_jwk_parse_state

Macros
#define	LWSJWKF_EXPORT_PRIVATE   (1 << 0)
#define	LWSJWKF_EXPORT_NOCRLF   (1 << 1)

Typedefs
typedef int(*	lws_jwk_key_import_callback) (struct lws_jwk *s, void *user)

Enumerations
enum	enum_jwk_meta_tok {   JWK_META_KTY , JWK_META_KID , JWK_META_USE , JWK_META_KEY_OPS ,   JWK_META_X5C , JWK_META_ALG , LWS_COUNT_JWK_ELEMENTS }

Functions
LWS_VISIBLE LWS_EXTERN int	lws_jwk_import (struct lws_jwk *jwk, lws_jwk_key_import_callback cb, void *user, const char *in, size_t len)
LWS_VISIBLE LWS_EXTERN void	lws_jwk_destroy (struct lws_jwk *jwk)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_dup_oct (struct lws_jwk *jwk, const void *key, int len)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_export (struct lws_jwk *jwk, int flags, char *p, int *len)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_load (struct lws_jwk *jwk, const char *filename, lws_jwk_key_import_callback cb, void *user)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_save (struct lws_jwk *jwk, const char *filename)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_rfc7638_fingerprint (struct lws_jwk *jwk, char *digest32)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_strdup_meta (struct lws_jwk *jwk, enum enum_jwk_meta_tok idx, const char *in, int len)
LWS_VISIBLE LWS_EXTERN int	lws_jwk_dump (struct lws_jwk *jwk)
LWS_VISIBLE int	lws_jwk_generate (struct lws_context *context, struct lws_jwk *jwk, enum lws_gencrypto_kty kty, int bits, const char *curve)

Detailed Description

JSON Web Keys API

Lws provides an API to parse JSON Web Keys into a struct lws_gencrypto_keyelem.

"oct" and "RSA" type keys are supported. For "oct" keys, they are held in the "e" member of the struct lws_gencrypto_keyelem.

Keys elements are allocated on the heap. You must destroy the allocations in the struct lws_gencrypto_keyelem by calling lws_genrsa_destroy_elements() when you are finished with it.

Function Documentation

lws_jwk_destroy()

LWS_VISIBLE LWS_EXTERN void lws_jwk_destroy

(

struct lws_jwk *

jwk

)

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

lws_jwk_destroy() - Destroy a JSON Web key

Parameters

jwk	the JWK object to destroy

All allocations in the lws_jwk are destroyed

lws_jwk_dup_oct()

LWS_VISIBLE LWS_EXTERN int lws_jwk_dup_oct	(	struct lws_jwk *	jwk,
		const void *	key,
		int	len
	)

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

lws_jwk_dup_oct() - Set a jwk to a dup'd binary OCT key

Parameters

jwk	the JWK object to set
key	the JWK object to destroy
len	the JWK object to destroy

Sets the kty to OCT, allocates len bytes for K and copies len bytes of key into the allocation.

lws_jwk_export()

LWS_VISIBLE LWS_EXTERN int lws_jwk_export	(	struct lws_jwk *	jwk,
		int	flags,
		char *	p,
		int *	len
	)

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

lws_jwk_export() - Export a JSON Web key to a textual representation

Parameters

jwk	the JWK object to export
flags	control export options
p	the buffer to write the exported JWK to
len	the length of the buffer p in bytes... reduced by used amount

Returns length of the used part of the buffer if OK, or -1 for error.

flags can be OR-ed together

LWSJWKF_EXPORT_PRIVATE: default is only public part, set this to also export the private part

LWSJWKF_EXPORT_NOCRLF: normally adds a CRLF at the end of the export, if you need to suppress it, set this flag

Serializes the content of the JWK into a char buffer.

lws_jwk_generate()

LWS_VISIBLE int lws_jwk_generate	(	struct lws_context *	context,
		struct lws_jwk *	jwk,
		enum lws_gencrypto_kty	kty,
		int	bits,
		const char *	curve
	)

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

lws_jwk_generate() - create a new key of given type and characteristics

Parameters

context	the struct lws_context used for RNG
jwk	the JWK object to fingerprint
kty	One of the LWS_GENCRYPTO_KTY_ key types
bits	for OCT and RSA keys, the number of bits
curve	for EC keys, the name of the curve

Returns 0 for OK or nonzero for failure

lws_jwk_import()

LWS_VISIBLE LWS_EXTERN int lws_jwk_import	(	struct lws_jwk *	jwk,
		lws_jwk_key_import_callback	cb,
		void *	user,
		const char *	in,
		size_t	len
	)

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

lws_jwk_import() - Create a JSON Web key from the textual representation

Parameters

jwk	the JWK object to create
cb	callback for each jwk-processed key, or NULL if importing a single key with no parent "keys" JSON
user	pointer to be passed to the callback, otherwise ignored by lws. NULL if importing a single key with no parent "keys" JSON
in	a single JWK JSON stanza in utf-8
len	the length of the JWK JSON stanza in bytes

Creates an lws_jwk struct filled with data from the JSON representation.

There are two ways to use this... with some protocols a single jwk is delivered with no parent "keys": [] array. If you call this with cb and user as NULL, then the input will be interpreted like that and the results placed in s.

The second case is that you are dealing with a "keys":[] array with one or more keys in it. In this case, the function iterates through the keys using s as a temporary jwk, and calls the user-provided callback for each key in turn while it return 0 (nonzero return from the callback terminates the iteration through any further keys).

lws_jwk_load()

LWS_VISIBLE LWS_EXTERN int lws_jwk_load	(	struct lws_jwk *	jwk,
		const char *	filename,
		lws_jwk_key_import_callback	cb,
		void *	user
	)

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

lws_jwk_load() - Import a JSON Web key from a file

Parameters

jwk	the JWK object to load into
filename	filename to load from
cb	optional callback for each key
user	opaque user pointer passed to cb if given

Returns 0 for OK or -1 for failure

There are two ways to use this... with some protocols a single jwk is delivered with no parent "keys": [] array. If you call this with cb and user as NULL, then the input will be interpreted like that and the results placed in s.

The second case is that you are dealing with a "keys":[] array with one or more keys in it. In this case, the function iterates through the keys using s as a temporary jwk, and calls the user-provided callback for each key in turn while it return 0 (nonzero return from the callback terminates the iteration through any further keys, leaving the last one in s).

lws_jwk_rfc7638_fingerprint()

LWS_VISIBLE LWS_EXTERN int lws_jwk_rfc7638_fingerprint	(	struct lws_jwk *	jwk,
		char *	digest32
	)

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

lws_jwk_rfc7638_fingerprint() - jwk to RFC7638 compliant fingerprint

Parameters

jwk	the JWK object to fingerprint
digest32	buffer to take 32-byte digest

Returns 0 for OK or -1 for failure

lws_jwk_save()

LWS_VISIBLE LWS_EXTERN int lws_jwk_save	(	struct lws_jwk *	jwk,
		const char *	filename
	)

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

lws_jwk_save() - Export a JSON Web key to a file

Parameters

jwk	the JWK object to save from
filename	filename to save to

Returns 0 for OK or -1 for failure

lws_jwk_strdup_meta()

LWS_VISIBLE LWS_EXTERN int lws_jwk_strdup_meta	(	struct lws_jwk *	jwk,
		enum enum_jwk_meta_tok	idx,
		const char *	in,
		int	len
	)

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

lws_jwk_strdup_meta() - allocate a duplicated string meta element

Parameters

jwk	the JWK object to fingerprint
idx	JWK_META_ element index
in	string to copy
len	length of string to copy

Returns 0 for OK or nonzero for failure