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.


Data Structure Documentation

◆ lws_jwk

struct lws_jwk

Definition at line 50 of file lws-jwk.h.

+ Collaboration diagram for lws_jwk:
Data Fields
struct lws_gencrypto_keyelem e[LWS_GENCRYPTO_MAX_KEYEL_COUNT]
struct lws_gencrypto_keyelem meta[LWS_COUNT_JWK_ELEMENTS]
int kty

one of LWS_GENCRYPTO_KTY_

char private_key

◆ lws_jwk_parse_state

struct lws_jwk_parse_state

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

+ Collaboration diagram for lws_jwk_parse_state:
Data Fields
struct lws_jwk * jwk
char b64[(((8192/8) *4)/3)+1]
lws_jwk_key_import_callback per_key_cb
void * user
int pos
int cose_state
int seen
unsigned short possible

Macro Definition Documentation

◆ LWSJWKF_EXPORT_PRIVATE

#define LWSJWKF_EXPORT_PRIVATE   (1 << 0)

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

Definition at line 120 of file lws-jwk.h.

◆ LWSJWKF_EXPORT_NOCRLF

#define LWSJWKF_EXPORT_NOCRLF   (1 << 1)

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

Definition at line 121 of file lws-jwk.h.

Typedef Documentation

◆ lws_jwk_key_import_callback

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

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

Definition at line 59 of file lws-jwk.h.

Enumeration Type Documentation

◆ enum_jwk_meta_tok

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

Enumerator
JWK_META_KTY 
JWK_META_KID 
JWK_META_USE 
JWK_META_KEY_OPS 
JWK_META_X5C 
JWK_META_ALG 
LWS_COUNT_JWK_ELEMENTS 

Definition at line 39 of file lws-jwk.h.

39 {
46
48};
@ JWK_META_ALG
Definition: lws-jwk.h:45
@ JWK_META_X5C
Definition: lws-jwk.h:44
@ LWS_COUNT_JWK_ELEMENTS
Definition: lws-jwk.h:47
@ JWK_META_KTY
Definition: lws-jwk.h:40
@ JWK_META_KEY_OPS
Definition: lws-jwk.h:43
@ JWK_META_USE
Definition: lws-jwk.h:42
@ JWK_META_KID
Definition: lws-jwk.h:41

Function Documentation

◆ 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_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_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_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_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_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 nonzero for failure

◆ lws_jwk_dump()

LWS_VISIBLE LWS_EXTERN int lws_jwk_dump ( struct lws_jwk jwk)

◆ 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 nonzero for failure