libwebsockets
Lightweight C library for HTML5 websockets
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
jwkthe 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
jwkthe JWK object to set
keythe JWK object to destroy
lenthe 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
jwkthe JWK object to export
flagscontrol export options
pthe buffer to write the exported JWK to
lenthe 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
contextthe struct lws_context used for RNG
jwkthe JWK object to fingerprint
ktyOne of the LWS_GENCRYPTO_KTY_ key types
bitsfor OCT and RSA keys, the number of bits
curvefor EC keys, the name of the curve

Returns 0 for OK or -1 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
jwkthe JWK object to create
cbcallback for each jwk-processed key, or NULL if importing a single key with no parent "keys" JSON
userpointer to be passed to the callback, otherwise ignored by lws. NULL if importing a single key with no parent "keys" JSON
ina single JWK JSON stanza in utf-8
lenthe 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
jwkthe JWK object to load into
filenamefilename to load from
cboptional callback for each key
useropaque 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
jwkthe JWK object to fingerprint
digest32buffer 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
jwkthe JWK object to save from
filenamefilename 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
jwkthe JWK object to fingerprint
idxJWK_META_ element index
instring to copy
lenlength of string to copy

Returns 0 for OK or -1 for failure