Checker

Decrypt and authenticate JWE tokens. More...

Collaboration diagram for Checker:

Typedefs
typedef struct jwe_checker	jwe_checker_t
	Opaque JWE Checker (decryption) object.

Functions
jwe_checker_t *	jwe_checker_new (void)
	Create a new JWE checker instance.
void	jwe_checker_free (jwe_checker_t *checker)
	Free a previously created JWE checker object.
int	jwe_checker_error (const jwe_checker_t *checker)
	Check error state of a JWE checker object.
const char *	jwe_checker_error_msg (const jwe_checker_t *checker)
	Get the error message contained in a JWE checker object.
void	jwe_checker_error_clear (jwe_checker_t *checker)
	Clear error state in a JWE checker object.
int	jwe_checker_setkey (jwe_checker_t *checker, jwe_key_alg_t alg, jwe_enc_t enc, const jwk_item_t *key)
	Set the key and algorithms for a JWE checker.
unsigned char *	jwe_checker_decrypt (jwe_checker_t *checker, const char *token, size_t *plaintext_len)
	Decrypt and authenticate a Compact Serialization JWE.
unsigned char *	jwe_checker_decrypt_all (jwe_checker_t *checker, const char *token, size_t *plaintext_len)
	Decrypt and authenticate a JWE in any serialization.
const unsigned char *	jwe_checker_get_aad (const jwe_checker_t *checker, size_t *aad_len)
	Get the JWE AAD recovered from a JSON-serialized token.

Detailed Description

Decrypt and authenticate JWE tokens.

Consuming a JWE token mirrors the JWS checker: create a jwe_checker_t, configure it with the key and the expected algorithms, then decrypt and authenticate tokens.

Typedef Documentation

jwe_checker_t

typedef struct jwe_checker jwe_checker_t

Opaque JWE Checker (decryption) object.

Function Documentation

jwe_checker_decrypt()

unsigned char * jwe_checker_decrypt	(	jwe_checker_t *	checker,
		const char *	token,
		size_t *	plaintext_len )

Decrypt and authenticate a Compact Serialization JWE.

Parses the five-part token, recovers the CEK using the configured key and algorithms (jwe_checker_setkey), and verifies the authentication tag.

Parameters

checker	Pointer to a JWE checker object
token	A nil-terminated compact JWE string
plaintext_len	If non-NULL, set to the length of the returned plaintext on success

Returns

A newly allocated buffer of decrypted plaintext the caller must free, or NULL on error (with the error set in the checker). The buffer is nil-terminated for convenience, but plaintext_len gives the true length.

jwe_checker_decrypt_all()

unsigned char * jwe_checker_decrypt_all	(	jwe_checker_t *	checker,
		const char *	token,
		size_t *	plaintext_len )

Decrypt and authenticate a JWE in any serialization.

Like jwe_checker_decrypt, but auto-detects the serialization: a token beginning with { is parsed as a JSON Serialization (Flattened or General), otherwise as the Compact Serialization. For a General JWE the checker selects the recipient matching its configured key and algorithm.

Parameters

checker	Pointer to a JWE checker object
token	A nil-terminated JWE string (compact or JSON)
plaintext_len	If non-NULL, set to the length of the returned plaintext on success

Returns

A newly allocated, nil-terminated buffer of decrypted plaintext the caller must free, or NULL on error (with the error set in the checker)

RFC-7516 Sec 7

jwe_checker_error()

int jwe_checker_error

(

const jwe_checker_t *

checker

)

Check error state of a JWE checker object.

Parameters

checker

Pointer to a JWE checker object

Returns

0 if no errors exist, non-zero otherwise

jwe_checker_error_clear()

void jwe_checker_error_clear

(

jwe_checker_t *

checker

)

Clear error state in a JWE checker object.

Parameters

checker

Pointer to a JWE checker object

jwe_checker_error_msg()

const char * jwe_checker_error_msg

(

const jwe_checker_t *

checker

)

Get the error message contained in a JWE checker object.

Parameters

checker

Pointer to a JWE checker object

Returns

Pointer to the error message string (empty if none). Never NULL.

jwe_checker_free()

void jwe_checker_free

(

jwe_checker_t *

checker

)

Free a previously created JWE checker object.

Parameters

checker

Pointer to a JWE checker object

jwe_checker_get_aad()

const unsigned char * jwe_checker_get_aad	(	const jwe_checker_t *	checker,
		size_t *	aad_len )

Get the JWE AAD recovered from a JSON-serialized token.

After a successful jwe_checker_decrypt_all on a JSON Serialization that carried an aad member, returns the authenticated application AAD octets. Returns NULL if the last token had no AAD member (or was compact). The returned buffer is owned by the checker and valid until the next decrypt or until the checker is freed.

Parameters

checker	Pointer to a JWE checker object
aad_len	If non-NULL, set to the length of the returned AAD in bytes

Returns

Pointer to the AAD octets, or NULL if none

jwe_checker_new()

jwe_checker_t * jwe_checker_new

(

void

)

Create a new JWE checker instance.

Returns

Pointer to a JWE checker object on success, NULL on failure

jwe_checker_setkey()

int jwe_checker_setkey	(	jwe_checker_t *	checker,
		jwe_key_alg_t	alg,
		jwe_enc_t	enc,
		const jwk_item_t *	key )

Set the key and algorithms for a JWE checker.

Parameters

checker	Pointer to a JWE checker object
alg	The expected JWE key management algorithm ("alg" header)
enc	The expected JWE content encryption algorithm ("enc" header)
key	The key (a JWK) used to recover the CEK

Returns

0 on success, non-zero otherwise with error set in the checker