CJOSE 0.6.2.3
Loading...
Searching...
No Matches
jwk.h File Reference

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"

Go to the source code of this file.

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_tcjose_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_tcjose_jwk_create_RSA_random (size_t keysize, const uint8_t *e, size_t elen, cjose_err *err)
 
cjose_jwk_tcjose_jwk_create_RSA_spec (const cjose_jwk_rsa_keyspec *spec, cjose_err *err)
 
cjose_jwk_tcjose_jwk_create_EC_random (cjose_jwk_ec_curve crv, cjose_err *err)
 
cjose_jwk_tcjose_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_tcjose_jwk_create_oct_random (size_t size, cjose_err *err)
 
cjose_jwk_tcjose_jwk_create_oct_spec (const uint8_t *data, size_t len, cjose_err *err)
 
cjose_jwk_tcjose_jwk_import (const char *json, size_t len, cjose_err *err)
 
cjose_jwk_tcjose_jwk_import_json (cjose_header_t *json, cjose_err *err)
 
cjose_jwk_tcjose_jwk_derive_ecdh_ephemeral_key (const cjose_jwk_t *jwk_self, const cjose_jwk_t *jwk_peer, const uint8_t *salt, size_t salt_len, cjose_err *err)
 
cjose_jwk_tcjose_jwk_derive_ecdh_secret (const cjose_jwk_t *jwk_self, const cjose_jwk_t *jwk_peer, const uint8_t *salt, size_t salt_len, 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

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

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
crvThe 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
specThe 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
sizeThe 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
dataThe key value.
lenThe 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
keysizeThe keysize, in bits
eThe public exponent
elenThe 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
specThe 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,
const uint8_t * salt,
size_t salt_len,
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.
salt[in] An optional salt to apply to the HMAC calculation. Unless FIPS mode is required this can be empty.
salt_len[in] The length of the optional salt.
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,
const uint8_t * salt,
size_t salt_len,
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
jwkThe 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
jwkThe 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
jwkThe 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
jwkThe 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
jsonA JSON document conforming to the Jose JWK specification.
lenThe 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
jsonA 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
ktyThe 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
jwkThe 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
jwkThe 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
jwkThe JWK object
kidThe new kid value
lenThe 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
jwkThe JWK to serialize.
privtrue 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