apr_jose_cb_t Struct Reference

#include <apr_jose.h>

Data Fields
apr_status_t(*	encrypt )(apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_recipient_t *recipient, apr_jose_encryption_t *encryption, void *ctx, apr_pool_t *pool)
apr_status_t(*	decrypt )(apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_recipient_t *recipient, apr_jose_encryption_t *encryption, apr_json_value_t *header, apr_jose_text_t *ph64, apr_jose_text_t *aad64, void *ctx, int *dflags, apr_pool_t *pool)
apr_status_t(*	sign )(apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_signature_t *signature, void *ctx, apr_pool_t *pool)
apr_status_t(*	verify )(apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_signature_t *signature, void *ctx, int *vflags, apr_pool_t *pool)
void *	ctx

Detailed Description

Callbacks for encryption, decryption, signing and verifying.

Field Documentation

ctx

void* apr_jose_cb_t::ctx

Context to be passed to the callback.

decrypt

apr_status_t(* apr_jose_cb_t::decrypt) (apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_recipient_t *recipient, apr_jose_encryption_t *encryption, apr_json_value_t *header, apr_jose_text_t *ph64, apr_jose_text_t *aad64, void *ctx, int *dflags, apr_pool_t *pool)

Callback that decrypts the ciphertext based on the parameters provided by the recipient and encryption parameters, and writes the resulting decrypted value to the bucket brigade. Base64url versions of the protected header and the aad are provided as part of the JWE decryption mechanism.

For security reasons, this callback MUST verify that the algorithm present in the JWE matches the algorithm expected by the decoder.

The decrypt function is expected to perform some or all of the following steps:

1. Determine the Key Management Mode employed by the algorithm specified by the "alg" (algorithm) Header Parameter.
2. Verify that the JWE uses a key known to the recipient.
3. When Direct Key Agreement or Key Agreement with Key Wrapping are employed, use the key agreement algorithm to compute the value of the agreed upon key. When Direct Key Agreement is employed, let the CEK be the agreed upon key. When Key Agreement with Key Wrapping is employed, the agreed upon key will be used to decrypt the JWE Encrypted Key.
4. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping are employed, decrypt the JWE Encrypted Key to produce the CEK. The CEK MUST have a length equal to that required for the content encryption algorithm. Note that when there are multiple recipients, each recipient will only be able to decrypt JWE Encrypted Key values that were encrypted to a key in that recipient's possession. It is therefore normal to only be able to decrypt one of the per-recipient JWE Encrypted Key values to obtain the CEK value. Also, see Section 11.5 for security considerations on mitigating timing attacks.
   1. When Direct Key Agreement or Direct Encryption are employed, verify that the JWE Encrypted Key value is an empty octet sequence.
   2. When Direct Encryption is employed, let the CEK be the shared symmetric key.
   3. Record whether the CEK could be successfully determined for this recipient or not.
   4. If the JWE JSON Serialization is being used, repeat this process (steps 4-12) for each recipient contained in the representation.
   5. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE Protected Header)). If the JWE Protected Header is not present (which can only happen when using the JWE JSON Serialization and no "protected" member is present), let this value be the empty string.
   6. Let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header). However, if a JWE AAD value is present (which can only be the case when using the JWE JSON Serialization), instead let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)).
   7. Decrypt the JWE Ciphertext using the CEK, the JWE Initialization Vector, the Additional Authenticated Data value, and the JWE Authentication Tag (which is the Authentication Tag input to the calculation) using the specified content encryption algorithm, returning the decrypted plaintext and validating the JWE Authentication Tag in the manner specified for the algorithm, rejecting the input without emitting any decrypted output if the JWE Authentication Tag is incorrect.
   8. If a "zip" parameter was included, uncompress the decrypted plaintext using the specified compression algorithm.

Parameters

bb	Brigade where decrypted data is to be written.
jose	The JOSE structure.
recipient	Structure containing details of the recipient of this message, to be used to decrypt the message.
encryption	Structure containing the encrypted message.
header	The JOSE protected header.
p64	The JOSE protected header in original BASE64URL format, for use during decryption.
aad64	The JOSE additional authenticated data in original BASE64URL format, for use during decryption.
ctx	A context.
dflags	A pointer to a flag. Set to APR_JOSE_FLAG_NONE for decryption to continue to the next recipient in the JWE, or APR_JOSE_FLAG_BREAK to stop decrypting further recipients.
pool	The pool to use.

Returns

APR_SUCCESS if decrypted successfully, APR_ENOTIMPL if decryption is not supported, or any other suitable error. The jose->result structure may be filled out with further details of any error.

encrypt

apr_status_t(* apr_jose_cb_t::encrypt) (apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_recipient_t *recipient, apr_jose_encryption_t *encryption, void *ctx, apr_pool_t *pool)

Callback that encrypts the content of the bucket brigade bb based on the parameters provided by the jwe->protected_header, and writes the resulting encrypted key to recipient->ekey, the initialisation vector to encryption->iv, the additional authentication data to encryption->aad, the cipher text to encryption->cipher, and the tag to encryption->tag.

The encrypt function is expected to perform some or all of the following steps:

1. Determine the Key Management Mode employed by the algorithm used to determine the Content Encryption Key value. (This is the algorithm recorded in the "alg" (algorithm) Header Parameter of the resulting JWE.)
2. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping are employed, generate a random CEK value. See RFC 4086 [RFC4086] for considerations on generating random values. The CEK MUST have a length equal to that required for the content encryption algorithm.
3. When Direct Key Agreement or Key Agreement with Key Wrapping are employed, use the key agreement algorithm to compute the value of the agreed upon key. When Direct Key Agreement is employed, let the CEK be the agreed upon key. When Key Agreement with Key Wrapping is employed, the agreed upon key will be used to wrap the CEK.
4. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping are employed, encrypt the CEK to the recipient and let the result be the JWE Encrypted Key.
5. When Direct Key Agreement or Direct Encryption are employed, let the JWE Encrypted Key be the empty octet sequence.
6. When Direct Encryption is employed, let the CEK be the shared symmetric key.
7. If the JWE JSON Serialization is being used, repeat this process (steps 1-7) for each recipient.
8. Generate a random JWE Initialization Vector of the correct size for the content encryption algorithm (if required for the algorithm); otherwise, let the JWE Initialization Vector be the empty octet sequence.
9. If a "zip" parameter was included, compress the plaintext using the specified compression algorithm and let M be the octet sequence representing the compressed plaintext; otherwise, let M be the octet sequence representing the plaintext.
10. Create the JSON object(s) containing the desired set of Header Parameters, which together comprise the JOSE Header: one or more of the JWE Protected Header, the JWE Shared Unprotected Header, and the JWE Per-Recipient Unprotected Header.
11. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE Protected Header)). If the JWE Protected Header is not present (which can only happen when using the JWE JSON Serialization and no "protected" member is present), let this value be the empty string.
12. Let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header). However, if a JWE AAD value is present (which can only be the case when using the JWE JSON Serialization), instead let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)).
13. Encrypt M using the CEK, the JWE Initialization Vector, and the Additional Authenticated Data value using the specified content encryption algorithm to create the JWE Ciphertext value and the JWE Authentication Tag (which is the Authentication Tag output from the encryption operation).

Parameters

bb	Brigade containing data to be encrypted.
jose	The JOSE structure.
recipient	Structure containing details of the recipient of this message.
encryption	Structure to be filled out by the callback containing the encrypted message.
ctx	A context.
pool	The pool to use.

Returns

APR_SUCCESS if encrypted successfully, APR_ENOTIMPL if encryption is not supported, or any other suitable error. The jose->result structure may be filled out with further details of any error.

sign

apr_status_t(* apr_jose_cb_t::sign) (apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_signature_t *signature, void *ctx, apr_pool_t *pool)

Callback that signs the content of the bucket brigade bb based on the parameters provided by the signature protected header, and writes the resulting binary signature to signature->sig.

The sign function is expected to perform some or all of the following steps:

1. Compute the JWS Signature in the manner defined for the particular algorithm being used over the JWS Signing Input ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)). The "alg" (algorithm) Header Parameter MUST be present in the JOSE Header, with the algorithm value accurately representing the algorithm used to construct the JWS Signature.

Parameters

bb	Brigade containing data to be signed.
jose	The JOSE structure.
signature	Structure to be filled out by the callback containing the signature of the message.
ctx	A context.
pool	The pool to use.

Returns

APR_SUCCESS if signed successfully, APR_ENOTIMPL if signing is not supported, or any other suitable error. The jose->result structure may be filled out with further details of any error.

verify

apr_status_t(* apr_jose_cb_t::verify) (apr_bucket_brigade *bb, apr_jose_t *jose, apr_jose_signature_t *signature, void *ctx, int *vflags, apr_pool_t *pool)

Callback that verifies the content of the bucket brigade bb based on the parameters provided by the signature protected header and signature->sig.

For security reasons, this callback MUST verify that the algorithm present in the JWS matches the algorithm expected by the decoder.

The verify function is expected to perform some or all of the following steps:

1. Validate the JWS Signature against the JWS Signing Input ASCII(BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload)) in the manner defined for the algorithm being used, which MUST be accurately represented by the value of the "alg" (algorithm) Header Parameter, which MUST be present. See Section 10.6 for security considerations on algorithm validation. Record whether the validation succeeded or not.
2. If the JWS JSON Serialization is being used, repeat this process (steps 4-8) for each digital signature or MAC value contained in the representation.
3. If none of the validations in step 9 succeeded, then the JWS MUST be considered invalid. Otherwise, in the JWS JSON Serialization case, return a result to the application indicating which of the validations succeeded and failed. In the JWS Compact Serialization case, the result can simply indicate whether or not the JWS was successfully validated.

Parameters

bb	Brigade containing data to be verified.
jose	The JOSE structure.
signature	Structure containing the signature to be verified.
ctx	A context.
dflags	A pointer to a flag. Set to APR_JOSE_FLAG_NONE for verification to continue to the next recipient in the JWE, or APR_JOSE_FLAG_BREAK to stop verifying further recipients.
pool	The pool to use.

Returns

APR_SUCCESS if verified successfully, APR_ENOTIMPL if verification is not supported, or any other suitable error. The jose->result structure may be filled out with further details of any error.

---

The documentation for this struct was generated from the following file:

• srclib/apr/include/apr_jose.h