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"
Go to the source code of this file.
|
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_iv (const cjose_jwk_t *jwk, cjose_header_t *header, const uint8_t *iv, size_t iv_len, 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) |
|
cjose_jwe_t * | cjose_jwe_encrypt_multi_iv (const cjose_jwe_recipient_t *recipients, size_t recipient_count, cjose_header_t *protected_header, cjose_header_t *shared_unprotected_header, const uint8_t *iv, size_t iv_len, 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) |
|
Functions and data structures for interacting with JSON Web Encryption (JWE) objects.
◆ cjose_jwe_t
An instance of a JWE object.
◆ cjose_jwe_decrypt()
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()
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_iv()
Creates a new JWE by encrypting the given plaintext within the given header and JWK, with a static IV.
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. |
iv | [in] the initialization vector for encrypting the JWE payload. If NULL, an IV will be automatically generated. The IV is copied. |
iv_len | [in] the length of the initialization vector, or 0 if iv is NULL. |
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()
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. |
shared_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_encrypt_multi_iv()
Creates a new JWE by encrypting the given plaintext with multiple keys and a static IV.
- See also
- cjose_jwe_encrypt for key requirements.
-
cjose_jwe_encrypt_multi to automatically generate an IV.
- 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. |
shared_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. |
iv | [in] the initialization vector for encrypting the JWE payload. If NULL, an IV will be automatically generated. |
iv_len | [in] the length of the initialization vector, or 0 if iv is NULL. |
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()
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()
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()
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()
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()
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()
Releases the given JWE object.
- Parameters
-
jwe | the JWE to be released. If null, this is a no-op. |