Functions and data structures for interacting with JSON Web Encryption (JWE) objects. More...

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "header.h"
#include "error.h"
#include "jwk.h"

Classes
struct	cjose_jwe_recipient_t

Typedefs
typedef struct _cjose_jwe_int	cjose_jwe_t

typedef const cjose_jwk_t (	cjose_key_locator) (cjose_jwe_t jwe, cjose_header_t hdr, void *)

Functions
cjose_jwe_t *	cjose_jwe_encrypt (const cjose_jwk_t jwk, cjose_header_t header, const uint8_t plaintext, size_t plaintext_len, cjose_err err)

cjose_jwe_t *	cjose_jwe_encrypt_multi (const cjose_jwe_recipient_t recipients, size_t recipient_count, cjose_header_t protected_header, cjose_header_t shared_unprotected_header, const uint8_t plaintext, size_t plaintext_len, cjose_err *err)

char *	cjose_jwe_export (cjose_jwe_t jwe, cjose_err err)

char *	cjose_jwe_export_json (cjose_jwe_t jwe, cjose_err err)

cjose_jwe_t *	cjose_jwe_import (const char compact, size_t compact_len, cjose_err err)

cjose_jwe_t *	cjose_jwe_import_json (const char json, size_t json_len, cjose_err err)

uint8_t *	cjose_jwe_decrypt (cjose_jwe_t jwe, const cjose_jwk_t jwk, size_t content_len, cjose_err err)

uint8_t *	cjose_jwe_decrypt_multi (cjose_jwe_t jwe, cjose_key_locator key_locator, void data, size_t content_len, cjose_err err)

cjose_header_t *	cjose_jwe_get_protected (cjose_jwe_t *jwe)

void	cjose_jwe_release (cjose_jwe_t *jwe)

Detailed Description

Functions and data structures for interacting with JSON Web Encryption (JWE) objects.

Typedef Documentation

◆ cjose_jwe_t

typedef struct _cjose_jwe_int cjose_jwe_t

An instance of a JWE object.

Function Documentation

◆ cjose_jwe_decrypt()

uint8_t* cjose_jwe_decrypt	(	cjose_jwe_t *	jwe,
		const cjose_jwk_t *	jwk,
		size_t *	content_len,
		cjose_err *	err
	)

Decrypts the JWE object using the given JWK. Returns the plaintext data of the JWE payload.

Parameters

jwe	[in] the JWE object to decrypt.
jwk	[in] the key to use for decrypting.
content_len	[out] The number of bytes in the returned buffer.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The decrypted content. Note the caller is responsible for free'ing this buffer when no longer in use. Failure to do so will result in a memory leak.

◆ cjose_jwe_decrypt_multi()

uint8_t* cjose_jwe_decrypt_multi	(	cjose_jwe_t *	jwe,
		cjose_key_locator	key_locator,
		void *	data,
		size_t *	content_len,
		cjose_err *	err
	)

Decrypts the JWE object using one or more provided JWKs. Returns the plaintext data of the JWE payload. The key to be used for decryption must be provided by the specified call back. The call back will be invoked for each recipient information in the JWE. If no key is available for a particular recipient information, NULL must be returned. More than one key can be returned, decryption is considered successful if the content decrypts and validates against all returned non-NULL keys, and at least one key was attempted.

Parameters

jwe	[in] the JWE object to decrypt.
jwk	[in] key_locator callback for finding keys
data	[in] custom data argument that is passed to the key locator callback.
content_len	[out] The number of bytes in the returned buffer.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: The decrypted content. Note the caller is responsible for free'ing this buffer when no longer in use. Failure to do so will result in a memory leak.

◆ cjose_jwe_encrypt()

cjose_jwe_t* cjose_jwe_encrypt	(	const cjose_jwk_t *	jwk,
		cjose_header_t *	header,
		const uint8_t *	plaintext,
		size_t	plaintext_len,
		cjose_err *	err
	)

Creates a new JWE by encrypting the given plaintext within the given header and JWK.

If the header provided indicates an algorithm requiring an asymmetric key (e.g. RSA-OAEP), the provided JWK must be asymmetric (e.g. RSA or EC).

If the header provided indicates an algorithm requiring a symmetric key (e.g. (dir), the provided JWK must be symmetric (e.g. oct).

Parameters

jwk	[in] the key to use for encrypting the JWE.
protected_header	[in] additional header values to include in the JWE protected header.
plaintext	[in] the plaintext to be encrypted in the JWE payload.
plaintext_len	[in] the length of the plaintext.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: a newly generated JWE with the given plaintext as the payload.

◆ cjose_jwe_encrypt_multi()

cjose_jwe_t* cjose_jwe_encrypt_multi	(	const cjose_jwe_recipient_t *	recipients,
		size_t	recipient_count,
		cjose_header_t *	protected_header,
		cjose_header_t *	shared_unprotected_header,
		const uint8_t *	plaintext,
		size_t	plaintext_len,
		cjose_err *	err
	)

Creates a new JWE by encrypting the given plaintext with multiple keys.

See also: cjose_jwe_encrypt for key requirements.

Parameters

recipients	[in] array of recipient objects. Each element must have the key of the recipient, and may have optional (not NULL) unprotected header. Unprotected header is retained by this function, and can be safely released by the caller if no longer needed. The key is only used within the scope of this function.
recipient_count	effective length of the recipients array, specifying how many recipients there is.
protected_header	[in] additional header values to include in the JWE protected header. The header is retained by JWE and should be released by the caller if no longer needed.
unprotected_header	[in] additional header values to include in the shared JWE unprotected header, can be NULL. The header is retained by JWE and should be released by the caller if no longer needed.
plaintext	[in] the plaintext to be encrypted in the JWE payload.
plaintext_len	[in] the length of the plaintext.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: a newly generated JWE with the given plaintext as the payload.

◆ cjose_jwe_export()

char* cjose_jwe_export	(	cjose_jwe_t *	jwe,
		cjose_err *	err
	)

Creates a compact serialization of the given JWE object.

Parameters

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

Returns: A pointer to a compact serialization of this JWE. Note the returned string pointer is owned by the caller, the caller must free it directly when no longer needed, or the memory will be leaked.

◆ cjose_jwe_export_json()

char* cjose_jwe_export_json	(	cjose_jwe_t *	jwe,
		cjose_err *	err
	)

Creates a JSON serialization of the given JWE object.

Parameters

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

Returns: A pointer to a JSON serialization of this JWE. Note the returned string pointer is owned by the caller, the caller must free it directly when no longer needed, or the memory will be leaked.

◆ cjose_jwe_get_protected()

cjose_header_t* cjose_jwe_get_protected ( cjose_jwe_t * jwe )

Returns the protected header of the JWE object.

NOTE: The returned header is still owned by the JWE object. Users must call cjose_header_retain() if it is expected to be valid after the owning cjose_jwe_t is released.

Parameters

jwe	[in] the JWE object for which the protected header is requested.

Returns: the (parsed) protected header

◆ cjose_jwe_import()

cjose_jwe_t* cjose_jwe_import	(	const char *	compact,
		size_t	compact_len,
		cjose_err *	err
	)

Creates a new JWE object from the given JWE compact serialization.

Note the current implementation only recognizes the JWE compact serialization format.

Parameters

compact	[in] a JWE in serialized form.
compact_len	[in] the length of the compact serialization.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: a newly generated JWE object from the given JWE serialization.

◆ cjose_jwe_import_json()

cjose_jwe_t* cjose_jwe_import_json	(	const char *	json,
		size_t	json_len,
		cjose_err *	err
	)

Creates a new JWE object from the given JWE compact serialization.

Note the current implementation only recognizes the JWE compact serialization format.

Parameters

json	[in] a JWE in a JSON serialized form.
json_len	[in] the length of the serialization.
err	[out] An optional error object which can be used to get additional information in the event of an error.

Returns: a newly generated JWE object from the given JWE JSON serialization.

◆ cjose_jwe_release()

void cjose_jwe_release ( cjose_jwe_t * jwe )

Releases the given JWE object.

Parameters

jwe	the JWE to be released. If null, this is a no-op.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cjose_jwe_t

Function Documentation

◆ cjose_jwe_decrypt()

◆ cjose_jwe_decrypt_multi()

◆ cjose_jwe_encrypt()

◆ cjose_jwe_encrypt_multi()

◆ cjose_jwe_export()

◆ cjose_jwe_export_json()

◆ cjose_jwe_get_protected()

◆ cjose_jwe_import()

◆ cjose_jwe_import_json()

◆ cjose_jwe_release()