Builder

Create and encrypt JWE tokens. More...

Collaboration diagram for Builder:

Typedefs
typedef struct jwe_builder	jwe_builder_t
	Opaque JWE Builder (encryption) object.
typedef struct jwe_recipient	jwe_recipient_t
	Opaque JWE recipient handle.

Functions
jwe_builder_t *	jwe_builder_new (void)
	Create a new JWE builder instance.
void	jwe_builder_free (jwe_builder_t *builder)
	Free a previously created JWE builder object.
int	jwe_builder_error (const jwe_builder_t *builder)
	Check error state of a JWE builder object.
const char *	jwe_builder_error_msg (const jwe_builder_t *builder)
	Get the error message contained in a JWE builder object.
void	jwe_builder_error_clear (jwe_builder_t *builder)
	Clear error state in a JWE builder object.
int	jwe_builder_setkey (jwe_builder_t *builder, jwe_key_alg_t alg, jwe_enc_t enc, const jwk_item_t *key)
	Set the key and algorithms for a JWE builder.
int	jwe_builder_set_partyinfo (jwe_builder_t *builder, const unsigned char *apu, size_t apu_len, const unsigned char *apv, size_t apv_len)
	Set the ECDH-ES PartyUInfo / PartyVInfo.
jwe_recipient_t *	jwe_builder_add_recipient (jwe_builder_t *builder, jwe_key_alg_t alg, const jwk_item_t *key)
	Add a recipient to a General JSON Serialization JWE.
int	jwe_recipient_set_partyinfo (jwe_recipient_t *recipient, const unsigned char *apu, size_t apu_len, const unsigned char *apv, size_t apv_len)
	Set the ECDH-ES PartyUInfo / PartyVInfo for one recipient.
int	jwe_recipient_add_header_json (jwe_recipient_t *recipient, const char *key, const char *value_json)
	Add a parameter to one recipient's unprotected header.
int	jwe_builder_set_format (jwe_builder_t *builder, jwe_serialization_t format)
	Select the serialization jwe_builder_generate produces.
int	jwe_builder_add_protected_json (jwe_builder_t *builder, const char *key, const char *value_json)
	Add a parameter to the JWE Protected Header.
int	jwe_builder_add_unprotected_json (jwe_builder_t *builder, const char *key, const char *value_json)
	Add a parameter to the shared JWE Unprotected Header.
int	jwe_builder_set_aad (jwe_builder_t *builder, const unsigned char *aad, size_t aad_len)
	Set the JWE Additional Authenticated Data.
char *	jwe_builder_generate (jwe_builder_t *builder, const unsigned char *plaintext, size_t plaintext_len)
	Encrypt a plaintext into a JWE.

Detailed Description

Create and encrypt JWE tokens.

Creating a JWE token mirrors the JWS builder: create a jwe_builder_t, configure it with a recipient key plus a key management ("alg") and content encryption ("enc") algorithm, then generate encrypted tokens.

Typedef Documentation

jwe_builder_t

typedef struct jwe_builder jwe_builder_t

Opaque JWE Builder (encryption) object.

jwe_recipient_t

typedef struct jwe_recipient jwe_recipient_t

Opaque JWE recipient handle.

Returned by jwe_builder_add_recipient to address one recipient of a General JSON Serialization. The handle is borrowed: it is owned by the builder and valid until the builder is freed; do not free it directly.

RFC-7516 Sec 7.2.1

Function Documentation

jwe_builder_add_protected_json()

int jwe_builder_add_protected_json	(	jwe_builder_t *	builder,
		const char *	key,
		const char *	value_json )

Add a parameter to the JWE Protected Header.

Adds an application-defined member to the integrity-protected JWE header (the protected member of the JSON serializations, and part of the AAD). The library sets "enc" (and, for the Compact Serialization, "alg" and the ECDH-ES parameters) itself; those reserved names are rejected here.

value_json is parsed as JSON, so a string value must include its quotes (the four-byte fragment quote-p-r-o-d-quote for the string prod); objects, arrays, numbers and booleans are accepted as written. The same parameter name must not also appear in the shared unprotected or any per-recipient header (RFC-7516 Sec 7.2.1).

Parameters

builder	Pointer to a JWE builder object
key	The header parameter name
value_json	The parameter value as a JSON fragment

Returns

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

jwe_builder_add_recipient()

jwe_recipient_t * jwe_builder_add_recipient	(	jwe_builder_t *	builder,
		jwe_key_alg_t	alg,
		const jwk_item_t *	key )

Add a recipient to a General JSON Serialization JWE.

The plaintext is encrypted once with a single CEK; each recipient wraps or encrypts that same CEK independently with its own key management algorithm and key. The first recipient may equivalently be configured with jwe_builder_setkey; this call appends further ones. Adding more than one recipient forces JWE_FORMAT_JSON_GENERAL.

The shared content encryption algorithm ("enc") must be set via jwe_builder_setkey. dir and ECDH-ES Direct (JWE_ALG_ECDH_ES) dictate the CEK from the key, so they cannot be combined with any other recipient.

Parameters

builder	Pointer to a JWE builder object
alg	The recipient's key management algorithm ("alg" header)
key	The recipient's key (a JWK)

Returns

A borrowed recipient handle (owned by the builder, valid until it is freed) on success, or NULL on error (with the error set in the builder)

RFC-7516 Sec 7.2.1

jwe_builder_add_unprotected_json()

int jwe_builder_add_unprotected_json	(	jwe_builder_t *	builder,
		const char *	key,
		const char *	value_json )

Add a parameter to the shared JWE Unprotected Header.

Adds an application-defined member to the shared (not integrity-protected) JWE header, emitted as the unprotected member of the JSON serializations. Only the JSON serializations can carry it. value_json is parsed as JSON (see jwe_builder_add_protected_json). The same parameter name must not also appear in the protected or any per-recipient header.

Parameters

builder	Pointer to a JWE builder object
key	The header parameter name
value_json	The parameter value as a JSON fragment

Returns

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

RFC-7516 Sec 7.2.1

jwe_builder_error()

int jwe_builder_error

(

const jwe_builder_t *

builder

)

Check error state of a JWE builder object.

Parameters

builder

Pointer to a JWE builder object

Returns

0 if no errors exist, non-zero otherwise

jwe_builder_error_clear()

void jwe_builder_error_clear

(

jwe_builder_t *

builder

)

Clear error state in a JWE builder object.

Parameters

builder

Pointer to a JWE builder object

jwe_builder_error_msg()

const char * jwe_builder_error_msg

(

const jwe_builder_t *

builder

)

Get the error message contained in a JWE builder object.

Parameters

builder

Pointer to a JWE builder object

Returns

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

jwe_builder_free()

void jwe_builder_free

(

jwe_builder_t *

builder

)

Free a previously created JWE builder object.

Parameters

builder

Pointer to a JWE builder object

jwe_builder_generate()

char * jwe_builder_generate	(	jwe_builder_t *	builder,
		const unsigned char *	plaintext,
		size_t	plaintext_len )

Encrypt a plaintext into a JWE.

Produces a JWE using the key and algorithms configured with jwe_builder_setkey. The serialization is the Compact Serialization (a five-part string) unless changed with jwe_builder_set_format.

Parameters

builder	Pointer to a JWE builder object
plaintext	The bytes to encrypt
plaintext_len	Length of plaintext in bytes

Returns

A newly allocated, nil-terminated JWE string the caller must free, or NULL on error (with the error set in the builder)

jwe_builder_new()

jwe_builder_t * jwe_builder_new

(

void

)

Create a new JWE builder instance.

Returns

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

jwe_builder_set_aad()

int jwe_builder_set_aad	(	jwe_builder_t *	builder,
		const unsigned char *	aad,
		size_t	aad_len )

Set the JWE Additional Authenticated Data.

Sets the optional application AAD emitted as the aad member of the JSON serializations. It is authenticated (bound into the AEAD tag) but not encrypted. Per RFC-7516 Sec 5.1 the AEAD AAD becomes ASCII(BASE64URL(protected)) || '.' || BASE64URL(aad). Only the JSON serializations can carry it. Pass NULL (with length 0) to clear it.

Parameters

builder	Pointer to a JWE builder object
aad	The AAD octets, or NULL
aad_len	Length of aad in bytes

Returns

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

jwe_builder_set_format()

int jwe_builder_set_format	(	jwe_builder_t *	builder,
		jwe_serialization_t	format )

Select the serialization jwe_builder_generate produces.

The default is JWE_FORMAT_COMPACT (the five-part string). Selecting JWE_FORMAT_JSON_FLAT or JWE_FORMAT_JSON_GENERAL produces the Flattened or General JSON Serialization respectively. The JSON serializations are required to carry a shared unprotected header (jwe_builder_add_unprotected_json), a per-recipient header, or a JWE AAD member (jwe_builder_set_aad); the Compact Serialization supports none of these.

Parameters

builder	Pointer to a JWE builder object
format	The serialization to emit

Returns

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

RFC-7516 Sec 7

jwe_builder_set_partyinfo()

int jwe_builder_set_partyinfo	(	jwe_builder_t *	builder,
		const unsigned char *	apu,
		size_t	apu_len,
		const unsigned char *	apv,
		size_t	apv_len )

Set the ECDH-ES PartyUInfo / PartyVInfo.

For ECDH-ES key agreement (JWE_ALG_ECDH_ES and the +A*KW variants), these optional octet strings are bound into the Concat KDF and emitted as the "apu" and "apv" header parameters. They have no effect for non-ECDH-ES algorithms. Pass NULL (with length 0) to leave one unset. Calling this again replaces any previous values.

Parameters

builder	Pointer to a JWE builder object
apu	PartyUInfo octets, or NULL
apu_len	Length of apu in bytes
apv	PartyVInfo octets, or NULL
apv_len	Length of apv in bytes

Returns

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

jwe_builder_setkey()

int jwe_builder_setkey	(	jwe_builder_t *	builder,
		jwe_key_alg_t	alg,
		jwe_enc_t	enc,
		const jwk_item_t *	key )

Set the key and algorithms for a JWE builder.

Parameters

builder	Pointer to a JWE builder object
alg	The JWE key management algorithm ("alg" header)
enc	The JWE content encryption algorithm ("enc" header)
key	The recipient key (a JWK) used for key management

Returns

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

jwe_recipient_add_header_json()

int jwe_recipient_add_header_json	(	jwe_recipient_t *	recipient,
		const char *	key,
		const char *	value_json )

Add a parameter to one recipient's unprotected header.

Adds an application-defined member to the per-recipient (unprotected) header emitted for recipient. value_json is parsed as JSON (see jwe_builder_add_protected_json). The library-managed names (alg/enc/epk/apu/apv) and a duplicate name are rejected; the same name must not also appear in the protected or shared unprotected header (RFC-7516 Sec 7.2.1).

Parameters

recipient	A recipient handle from jwe_builder_add_recipient
key	The header parameter name
value_json	The parameter value as a JSON fragment

Returns

0 on success, non-zero otherwise

jwe_recipient_set_partyinfo()

int jwe_recipient_set_partyinfo	(	jwe_recipient_t *	recipient,
		const unsigned char *	apu,
		size_t	apu_len,
		const unsigned char *	apv,
		size_t	apv_len )

Set the ECDH-ES PartyUInfo / PartyVInfo for one recipient.

The per-recipient equivalent of jwe_builder_set_partyinfo, addressing the recipient identified by recipient. Has no effect for non-ECDH-ES algorithms. Pass NULL (with length 0) to leave one unset.

Parameters

recipient	A recipient handle from jwe_builder_add_recipient
apu	PartyUInfo octets, or NULL
apu_len	Length of apu in bytes
apv	PartyVInfo octets, or NULL
apv_len	Length of apv in bytes

Returns

0 on success, non-zero otherwise