Functions and data structures for interacting with JSON Web Key (JWK) objects. More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include <openssl/obj_mac.h>
#include "cjose/error.h"
#include "cjose/header.h"

Classes
struct	cjose_jwk_rsa_keyspec

struct	cjose_jwk_ec_keyspec

Typedefs
typedef struct _cjose_jwk_int	cjose_jwk_t

Enumerations
enum	cjose_jwk_kty_t { CJOSE_JWK_KTY_RSA = 1, CJOSE_JWK_KTY_EC, CJOSE_JWK_KTY_OCT }

enum	cjose_jwk_ec_curve { CJOSE_JWK_EC_P_256 = NID_X9_62_prime256v1, CJOSE_JWK_EC_P_384 = NID_secp384r1, CJOSE_JWK_EC_P_521 = NID_secp521r1, CJOSE_JWK_EC_INVALID = -1 }

Functions
const char *	cjose_jwk_name_for_kty (cjose_jwk_kty_t kty, cjose_err *err)

cjose_jwk_t *	cjose_jwk_retain (cjose_jwk_t jwk, cjose_err err)

bool	cjose_jwk_release (cjose_jwk_t *jwk)

cjose_jwk_kty_t	cjose_jwk_get_kty (const cjose_jwk_t jwk, cjose_err err)

size_t	cjose_jwk_get_keysize (const cjose_jwk_t jwk, cjose_err err)

void *	cjose_jwk_get_keydata (const cjose_jwk_t jwk, cjose_err err)

const char *	cjose_jwk_get_kid (const cjose_jwk_t jwk, cjose_err err)

bool	cjose_jwk_set_kid (cjose_jwk_t jwk, const char kid, size_t len, cjose_err *err)

char *	cjose_jwk_to_json (const cjose_jwk_t jwk, bool priv, cjose_err err)

cjose_jwk_t *	cjose_jwk_create_RSA_random (size_t keysize, const uint8_t e, size_t elen, cjose_err err)

cjose_jwk_t *	cjose_jwk_create_RSA_spec (const cjose_jwk_rsa_keyspec spec, cjose_err err)

cjose_jwk_t *	cjose_jwk_create_EC_random (cjose_jwk_ec_curve crv, cjose_err *err)

cjose_jwk_t *	cjose_jwk_create_EC_spec (const cjose_jwk_ec_keyspec spec, cjose_err err)

const cjose_jwk_ec_curve	cjose_jwk_EC_get_curve (const cjose_jwk_t jwk, cjose_err err)

cjose_jwk_t *	cjose_jwk_create_oct_random (size_t size, cjose_err *err)

cjose_jwk_t *	cjose_jwk_create_oct_spec (const uint8_t data, size_t len, cjose_err err)

cjose_jwk_t *	cjose_jwk_import (const char json, size_t len, cjose_err err)

cjose_jwk_t *	cjose_jwk_import_json (cjose_header_t json, cjose_err err)

cjose_jwk_t *	cjose_jwk_derive_ecdh_ephemeral_key (const cjose_jwk_t jwk_self, const cjose_jwk_t jwk_peer, cjose_err *err)

cjose_jwk_t *	cjose_jwk_derive_ecdh_secret (const cjose_jwk_t jwk_self, const cjose_jwk_t jwk_peer, cjose_err *err)

Detailed Description

Functions and data structures for interacting with JSON Web Key (JWK) objects.

Typedef Documentation

◆ cjose_jwk_t

typedef struct _cjose_jwk_int cjose_jwk_t

An instance of a JWK object.

Enumeration Type Documentation

◆ cjose_jwk_ec_curve

enum cjose_jwk_ec_curve

Enumeration of supported Elliptic-Curve types

Enumerator
CJOSE_JWK_EC_P_256	NIST P-256 Prime Curve (secp256r1)
CJOSE_JWK_EC_P_384	NIST P-384 Prime Curve (secp384r1)
CJOSE_JWK_EC_P_521	NIST P-521 Prime Curve (secp521r1)
CJOSE_JWK_EC_INVALID	Invalid Curve

◆ cjose_jwk_kty_t

enum cjose_jwk_kty_t

Enumeration of supported JSON Web Key (JWK) types

Enumerator
CJOSE_JWK_KTY_RSA	RSA Public (or Private) Key
CJOSE_JWK_KTY_EC	Elliptic Curve Public (or Private) Key
CJOSE_JWK_KTY_OCT	Octet String (Symmetric) Key

Function Documentation

◆ cjose_jwk_create_EC_random()

cjose_jwk_t* cjose_jwk_create_EC_random	(	cjose_jwk_ec_curve	crv,
		cjose_err *	err
	)

Creates a new Elliptic-Curve JWK, using a secure random number generator.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

Parameters

crv	The EC Curve to generate against
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The generated Elliptic Curve JWK object

◆ cjose_jwk_create_EC_spec()

cjose_jwk_t* cjose_jwk_create_EC_spec	(	const cjose_jwk_ec_keyspec *	spec,
		cjose_err *	err
	)

Creates a new Elliptic-Curve JWK, using the given the raw values for the private and/or public keys.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

NOTE: This function makes a copy of all provided data; the caller MUST free the memory for spec after calling this function.

Parameters

spec	The specified Elliptic Curve key properties
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The generated Elliptic Curve JWK object

◆ cjose_jwk_create_oct_random()

cjose_jwk_t* cjose_jwk_create_oct_random	(	size_t	size,
		cjose_err *	err
	)

Creates a new symmetric octet JWK, using a secure random number generator.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

Parameters

size	The keysize, in bits
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The generated symmetric JWK object.

◆ cjose_jwk_create_oct_spec()

cjose_jwk_t* cjose_jwk_create_oct_spec	(	const uint8_t *	data,
		size_t	len,
		cjose_err *	err
	)

Creates a new symmetric oct JWK, using the given raw key data.

NOTE: data is copied, so the caller MUST free its memory after calling this function.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

Parameters

data	The key value.
len	The length of `data`
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The symmetric JWK object for the given raw key data.

◆ cjose_jwk_create_RSA_random()

cjose_jwk_t* cjose_jwk_create_RSA_random	(	size_t	keysize,
		const uint8_t *	e,
		size_t	elen,
		cjose_err *	err
	)

Creates a new RSA JWK, using a secure random number generator.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

Parameters

size	The keysize, in bits
e	The public exponent
elen	The length of `e`
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The generated symmetric JWK object.

◆ cjose_jwk_create_RSA_spec()

cjose_jwk_t* cjose_jwk_create_RSA_spec	(	const cjose_jwk_rsa_keyspec *	spec,
		cjose_err *	err
	)

Creates a new RSA JWK, using the given raw value for the private and/or public keys.

NOTE: The caller MUST call cjose_jwk_release() to release the JWK's resources.

NOTE: This function makes a copy of all provided data; the caller MUST free the memory for spec after calling this function.

Parameters

spec	The specified RSA key properties
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The generated RSA JWK object

◆ cjose_jwk_derive_ecdh_ephemeral_key()

cjose_jwk_t* cjose_jwk_derive_ecdh_ephemeral_key	(	const cjose_jwk_t *	jwk_self,
		const cjose_jwk_t *	jwk_peer,
		cjose_err *	err
	)

Computes an ECDH ephemeral key as an HKDF hash of the derived shared secret from a local EC key-pair and a peer's EC public key. The result is returned in the form of a new JWK of type oct.

Note: on successful return of a jwk_ecdh_ephemeral_key, the caller becomes responsible for releasing that JWK wuth the cjose_jwk_release() command.

Parameters

jwk_self	[in] The caller's own EC key pair.
jwk_peer	[in] The peer's EC public key.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: A new JWK representing the ephemeral key, or NULL in the event of and error.

◆ cjose_jwk_derive_ecdh_secret()

cjose_jwk_t* cjose_jwk_derive_ecdh_secret	(	const cjose_jwk_t *	jwk_self,
		const cjose_jwk_t *	jwk_peer,
		cjose_err *	err
	)

Deprecated. Alias for cjose_jwk_derive_ecdh_ephemeral_key.

◆ cjose_jwk_EC_get_curve()

const cjose_jwk_ec_curve cjose_jwk_EC_get_curve	(	const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Obtains the curve for the given (EC) JWK.

Parameters

jwk	[in] The EC JWK to inspect
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The curve type

◆ cjose_jwk_get_keydata()

void* cjose_jwk_get_keydata	(	const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Retrieves the raw key data for this JWK.

WARNING: this is the raw data specific to the key type, and could contain private key material. NOTE: This key data will be released when the key is released.

Parameters

jwk	The JWK to retrieve key data from

Returns: The key data specific to the type of key

◆ cjose_jwk_get_keysize()

size_t cjose_jwk_get_keysize	(	const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Retrieves the keysize of this JWK (in bits).

Parameters

jwk	The JWK to retrieve the keysize of
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The keysize for this JWK, in bits

◆ cjose_jwk_get_kid()

const char* cjose_jwk_get_kid	(	const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Retrieves the key id for the given JWK object. The string returned by this call belongs to the JWK, caller should not attempt to free it.

Parameters

jwk	The JWK object
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: the current kid, or NULL if not set.

◆ cjose_jwk_get_kty()

cjose_jwk_kty_t cjose_jwk_get_kty	(	const cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Retrieves the key type for the given JWK object.

Parameters

jwk	The JWK object
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: the known key type

◆ cjose_jwk_import()

cjose_jwk_t* cjose_jwk_import	(	const char *	json,
		size_t	len,
		cjose_err *	err
	)

Instantiates a new JWK given a JSON document representation conforming to JSON Web Key (JWK) IETF ID draft-ietf-jose-json-web-key.

NOTE: A successful call returns a new cjose_jwk_t object. It is the caller's responsibility to call cjose_jwk_release() to release the JWK when it is no longer needed. Failure to do so will result in a memory leak.

Parameters

json	A JSON document conforming to the Jose JWK specification.
len	The length of the given JSON document.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: A JWK object corresponding to the given JSON document. In the event the given JSON document cannot be parsed, or is otherwise an invalid JWK representation, this will return NULL.

◆ cjose_jwk_import_json()

cjose_jwk_t* cjose_jwk_import_json	(	cjose_header_t *	json,
		cjose_err *	err
	)

Instantiates a new JWK given a JSON object conforming to JSON Web Key (JWK) IETF RFC 7518.

NOTE: A successful call returns a new cjose_jwk_t object. It is the caller's responsibility to call cjose_jwk_release() to release the JWK when it is no longer needed. Failure to do so will result in a memory leak.

Parameters

json	A JSON document conforming to the Jose JWK specification.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: A JWK object corresponding to the given JSON document. In the event the given JSON object is an invalid JWK representation, this will return NULL.

◆ cjose_jwk_name_for_kty()

const char* cjose_jwk_name_for_kty	(	cjose_jwk_kty_t	kty,
		cjose_err *	err
	)

Retrieves the string name for the given KTY enumeration.

Parameters

kty	The JWK key type
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The string name for kty

◆ cjose_jwk_release()

bool cjose_jwk_release ( cjose_jwk_t * jwk )

Releases a JWK object. For a newly-created key where cjose_jwk_retain() has not been called, the object is destroyed and its resources are released.

If cjose_jwk_retain() has been called on the given JWK object, an internal count is decremented but no other resources are released.

Parameters

jwk	The JWK object to release

Returns: true if the released JWK is still valid, or false if the JWK object's resources and memory have been freed.

◆ cjose_jwk_retain()

cjose_jwk_t* cjose_jwk_retain	(	cjose_jwk_t *	jwk,
		cjose_err *	err
	)

Retains a JWK object. The caller MUST call cjose_jwk_release() once the JWK object is no longer in use, or the program will leak memory.

Parameters

jwk	The JWK object to retain
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The retained JWK object

◆ cjose_jwk_set_kid()

bool cjose_jwk_set_kid	(	cjose_jwk_t *	jwk,
		const char *	kid,
		size_t	len,
		cjose_err *	err
	)

Sets a new value for the kid attribute of the JWK. The string will be copied to an internal buffer of the JWK and released when the JWK object is released.

Parameters

jwk	The JWK object
kid	The new kid value
len	The length of the kid string in bytes
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: True if successful, false otherwise.

◆ cjose_jwk_to_json()

char* cjose_jwk_to_json	(	const cjose_jwk_t *	jwk,
		bool	priv,
		cjose_err *	err
	)

Serializes the given JWK to a JSON string.

NOTE: The returned needs to be freed by the caller.

Parameters

jwk	The JWK to serialize.
priv	`true` to include private/secret fields
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The JSON string representation of jwk

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cjose_jwk_t

Enumeration Type Documentation

◆ cjose_jwk_ec_curve

◆ cjose_jwk_kty_t

Function Documentation

◆ cjose_jwk_create_EC_random()

◆ cjose_jwk_create_EC_spec()

◆ cjose_jwk_create_oct_random()

◆ cjose_jwk_create_oct_spec()

◆ cjose_jwk_create_RSA_random()

◆ cjose_jwk_create_RSA_spec()

◆ cjose_jwk_derive_ecdh_ephemeral_key()

◆ cjose_jwk_derive_ecdh_secret()

◆ cjose_jwk_EC_get_curve()

◆ cjose_jwk_get_keydata()

◆ cjose_jwk_get_keysize()

◆ cjose_jwk_get_kid()

◆ cjose_jwk_get_kty()

◆ cjose_jwk_import()

◆ cjose_jwk_import_json()

◆ cjose_jwk_name_for_kty()

◆ cjose_jwk_release()

◆ cjose_jwk_retain()

◆ cjose_jwk_set_kid()

◆ cjose_jwk_to_json()