AEAD operations

General Description

AEAD operations definitions.

Macros
#define	IFX_SE_AEAD_OPERATION_INIT   {0}
	This only zeroes out the first byte in the union, the rest is unspecified.

Typedefs
typedef struct ifx_se_aead_operation_s	ifx_se_aead_operation_t
	The type of the state data structure for multipart AEAD operations. More...

Functions
ifx_se_status_t	ifx_se_aead_encrypt (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t nonce, ifx_se_fih_t nonce_length, const ifx_se_fih_ptr_t additional_data, ifx_se_fih_t additional_data_length, const ifx_se_fih_ptr_t plaintext, ifx_se_fih_t plaintext_length, const ifx_se_fih_ptr_t ciphertext, ifx_se_fih_t ciphertext_size, ifx_se_fih_ptr_t ciphertext_length, void *ctx)
	Process an authenticated encryption operation. More...
ifx_se_status_t	ifx_se_aead_decrypt (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t nonce, ifx_se_fih_t nonce_length, const ifx_se_fih_ptr_t additional_data, ifx_se_fih_t additional_data_length, const ifx_se_fih_ptr_t ciphertext, ifx_se_fih_t ciphertext_length, const ifx_se_fih_ptr_t plaintext, ifx_se_fih_t plaintext_size, ifx_se_fih_ptr_t plaintext_length, void *ctx)
	Process an authenticated decryption operation. More...
ifx_se_status_t	ifx_se_aead_encrypt_setup (ifx_se_aead_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set the key for a multipart authenticated encryption operation. More...
ifx_se_status_t	ifx_se_aead_decrypt_setup (ifx_se_aead_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set the key for a multipart authenticated decryption operation. More...
ifx_se_status_t	ifx_se_aead_generate_nonce (ifx_se_aead_operation_t *operation, ifx_se_fih_ptr_t nonce, ifx_se_fih_t nonce_size, ifx_se_fih_ptr_t nonce_length, void *ctx)
	Generate a random nonce for an authenticated encryption operation. More...
ifx_se_status_t	ifx_se_aead_set_nonce (ifx_se_aead_operation_t *operation, const ifx_se_fih_ptr_t nonce, ifx_se_fih_t nonce_length, void *ctx)
	Set the nonce for an authenticated encryption or decryption operation. More...
ifx_se_status_t	ifx_se_aead_set_lengths (ifx_se_aead_operation_t *operation, ifx_se_fih_t ad_length, ifx_se_fih_t plaintext_length, void *ctx)
	Declare the lengths of the message and additional data for AEAD. More...
ifx_se_status_t	ifx_se_aead_update_ad (ifx_se_aead_operation_t *operation, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, void *ctx)
	Pass additional data to an active AEAD operation. More...
ifx_se_status_t	ifx_se_aead_update (ifx_se_aead_operation_t *operation, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, ifx_se_fih_ptr_t output, ifx_se_fih_t output_size, ifx_se_fih_ptr_t output_length, void *ctx)
	Encrypt or decrypt a message fragment in an active AEAD operation. More...
ifx_se_status_t	ifx_se_aead_finish (ifx_se_aead_operation_t *operation, ifx_se_fih_ptr_t ciphertext, ifx_se_fih_t ciphertext_size, ifx_se_fih_ptr_t ciphertext_length, ifx_se_fih_ptr_t tag, ifx_se_fih_t tag_size, ifx_se_fih_ptr_t tag_length, void *ctx)
	Finish encrypting a message in an AEAD operation. More...
ifx_se_status_t	ifx_se_aead_verify (ifx_se_aead_operation_t *operation, ifx_se_fih_ptr_t plaintext, ifx_se_fih_t plaintext_size, ifx_se_fih_ptr_t plaintext_length, const ifx_se_fih_ptr_t tag, ifx_se_fih_t tag_length, void *ctx)
	Finish authenticating and decrypting a message in an AEAD operation. More...
ifx_se_status_t	ifx_se_aead_abort (ifx_se_aead_operation_t *operation, void *ctx)
	Abort an AEAD operation. More...
static struct ifx_se_aead_operation_s	ifx_se_aead_operation_init (void)
	Initialize the AEAD operation context. More...

Typedef Documentation

ifx_se_aead_operation_t

typedef struct ifx_se_aead_operation_s ifx_se_aead_operation_t

The type of the state data structure for multipart AEAD operations.

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Function Documentation

ifx_se_aead_encrypt()

ifx_se_status_t ifx_se_aead_encrypt	(	ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		const ifx_se_fih_ptr_t	nonce,
		ifx_se_fih_t	nonce_length,
		const ifx_se_fih_ptr_t	additional_data,
		ifx_se_fih_t	additional_data_length,
		const ifx_se_fih_ptr_t	plaintext,
		ifx_se_fih_t	plaintext_length,
		const ifx_se_fih_ptr_t	ciphertext,
		ifx_se_fih_t	ciphertext_size,
		ifx_se_fih_ptr_t	ciphertext_length,
		void *	ctx
	)

Process an authenticated encryption operation.

Parameters

[in]	key	Identifier of the key to use for the operation. It must allow the usage IFX_SE_KEY_USAGE_ENCRYPT.
[in]	alg	The AEAD algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_AEAD(alg) is true).
[in]	nonce	Nonce or IV to use (encoded pointer to input data).
[in]	nonce_length	Size of the nonce buffer in bytes (size_t).
[in]	additional_data	Additional data that will be authenticated but not encrypted (encoded pointer to input data).
[in]	additional_data_length	Size of additional_data in bytes (size_t).
[in]	plaintext	Data that will be authenticated and encrypted (encoded pointer to input data).
[in]	plaintext_length	Size of plaintext in bytes (size_t).
[out]	ciphertext	Output buffer for the authenticated and encrypted data (encoded pointer to output buffer). The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.
[in]	ciphertext_size	Size of the ciphertext buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: A sufficient output size is IFX_SE_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) where key_type is the type of key. IFX_SE_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) evaluates to the maximum ciphertext size of any supported AEAD encryption.
[out]	ciphertext_length	On success, the size of the output in the ciphertext buffer (encoded pointer to size_t variable).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_HANDLE
IFX_SE_ERROR_NOT_PERMITTED
IFX_SE_ERROR_INVALID_ARGUMENT	key is not compatible with alg.
IFX_SE_ERROR_NOT_SUPPORTED	alg is not supported or is not an AEAD algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_BUFFER_TOO_SMALL	ciphertext_size is too small. IFX_SE_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) or IFX_SE_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) can be used to determine the required buffer size.
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE

ifx_se_aead_decrypt()

ifx_se_status_t ifx_se_aead_decrypt	(	ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		const ifx_se_fih_ptr_t	nonce,
		ifx_se_fih_t	nonce_length,
		const ifx_se_fih_ptr_t	additional_data,
		ifx_se_fih_t	additional_data_length,
		const ifx_se_fih_ptr_t	ciphertext,
		ifx_se_fih_t	ciphertext_length,
		const ifx_se_fih_ptr_t	plaintext,
		ifx_se_fih_t	plaintext_size,
		ifx_se_fih_ptr_t	plaintext_length,
		void *	ctx
	)

Process an authenticated decryption operation.

Parameters

[in]	key	Identifier of the key to use for the operation. It must allow the usage IFX_SE_KEY_USAGE_DECRYPT.
[in]	alg	The AEAD algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_AEAD(alg) is true).
[in]	nonce	Nonce or IV to use (encoded pointer to input data).
[in]	nonce_length	Size of the nonce buffer in bytes (size_t).
[in]	additional_data	Additional data that has been authenticated but not encrypted (encoded pointer to input data).
[in]	additional_data_length	Size of additional_data in bytes (size_t).
[in]	ciphertext	Data that has been authenticated and encrypted (encoded pointer to input data). For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag.
[in]	ciphertext_length	Size of ciphertext in bytes (encoded pointer to input data).
[out]	plaintext	Output buffer for the decrypted data (encoded pointer to output buffer).
[in]	plaintext_size	Size of the plaintext buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: A sufficient output size is IFX_SE_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) where key_type is the type of key. IFX_SE_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) evaluates to the maximum plaintext size of any supported AEAD decryption.
[out]	plaintext_length	On success, the size of the output in the plaintext buffer (encoded pointer to size_t variable).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_HANDLE
IFX_SE_ERROR_INVALID_SIGNATURE	The ciphertext is not authentic.
IFX_SE_ERROR_NOT_PERMITTED
IFX_SE_ERROR_INVALID_ARGUMENT	key is not compatible with alg.
IFX_SE_ERROR_NOT_SUPPORTED	alg is not supported or is not an AEAD algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_BUFFER_TOO_SMALL	plaintext_size is too small. IFX_SE_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) or IFX_SE_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) can be used to determine the required buffer size.
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE

ifx_se_aead_encrypt_setup()

ifx_se_status_t ifx_se_aead_encrypt_setup	(	ifx_se_aead_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set the key for a multipart authenticated encryption operation.

The sequence of operations to encrypt a message with authentication is as follows:

1. Allocate an operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for ifx_se_aead_operation_t, e.g. IFX_SE_AEAD_OPERATION_INIT.
3. Call ifx_se_aead_encrypt_setup() to specify the algorithm and key.
4. If needed, call ifx_se_aead_set_lengths() to specify the length of the inputs to the subsequent calls to ifx_se_aead_update_ad() and ifx_se_aead_update(). See the documentation of ifx_se_aead_set_lengths() for details.
5. Call either ifx_se_aead_generate_nonce() or ifx_se_aead_set_nonce() to generate or set the nonce. You should use ifx_se_aead_generate_nonce() unless the protocol you are implementing requires a specific nonce value.
6. Call ifx_se_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
7. Call ifx_se_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time.
8. Call ifx_se_aead_finish().

If an error occurs at any step after a call to ifx_se_aead_encrypt_setup(), the operation will need to be reset by a call to ifx_se_aead_abort(). The application may call ifx_se_aead_abort() at any time after the operation has been initialized.

After a successful call to ifx_se_aead_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

• A successful call to ifx_se_aead_finish().
• A call to ifx_se_aead_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_aead_operation_t and not yet in use.
[in]	key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage IFX_SE_KEY_USAGE_ENCRYPT.
[in]	alg	The AEAD algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_AEAD(alg) is true).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be inactive), or the library has not been previously initialized by ifx_se_crypto_init().
IFX_SE_ERROR_INVALID_HANDLE
IFX_SE_ERROR_NOT_PERMITTED
IFX_SE_ERROR_INVALID_ARGUMENT	key is not compatible with alg.
IFX_SE_ERROR_NOT_SUPPORTED	alg is not supported or is not an AEAD algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE

ifx_se_aead_decrypt_setup()

ifx_se_status_t ifx_se_aead_decrypt_setup	(	ifx_se_aead_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set the key for a multipart authenticated decryption operation.

The sequence of operations to decrypt a message with authentication is as follows:

1. Allocate an operation object which will be passed to all the functions listed here.
2. Initialize the operation object with one of the methods described in the documentation for ifx_se_aead_operation_t, e.g. IFX_SE_AEAD_OPERATION_INIT.
3. Call ifx_se_aead_decrypt_setup() to specify the algorithm and key.
4. If needed, call ifx_se_aead_set_lengths() to specify the length of the inputs to the subsequent calls to ifx_se_aead_update_ad() and ifx_se_aead_update(). See the documentation of ifx_se_aead_set_lengths() for details.
5. Call ifx_se_aead_set_nonce() with the nonce for the decryption.
6. Call ifx_se_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
7. Call ifx_se_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each time.
8. Call ifx_se_aead_verify().

If an error occurs at any step after a call to ifx_se_aead_decrypt_setup(), the operation will need to be reset by a call to ifx_se_aead_abort(). The application may call ifx_se_aead_abort() at any time after the operation has been initialized.

After a successful call to ifx_se_aead_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

• A successful call to ifx_se_aead_verify().
• A call to ifx_se_aead_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_aead_operation_t and not yet in use.
[in]	key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage IFX_SE_KEY_USAGE_DECRYPT.
[in]	alg	The AEAD algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_AEAD(alg) is true).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_HANDLE
IFX_SE_ERROR_NOT_PERMITTED
IFX_SE_ERROR_INVALID_ARGUMENT	key is not compatible with alg.
IFX_SE_ERROR_NOT_SUPPORTED	alg is not supported or is not an AEAD algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE

ifx_se_aead_generate_nonce()

ifx_se_status_t ifx_se_aead_generate_nonce	(	ifx_se_aead_operation_t *	operation,
		ifx_se_fih_ptr_t	nonce,
		ifx_se_fih_t	nonce_size,
		ifx_se_fih_ptr_t	nonce_length,
		void *	ctx
	)

Generate a random nonce for an authenticated encryption operation.

This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.

The application must call ifx_se_aead_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Parameters

[in,out]	operation	Active AEAD operation.
[out]	nonce	Buffer where the generated nonce is to be written (encoded pointer to output buffer).
[in]	nonce_size	Size of the nonce buffer in bytes (size_t).
[out]	nonce_length	On success, the number of bytes of the generated nonce (encoded pointer to size_t variable).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_BUFFER_TOO_SMALL	The size of the nonce buffer is too small.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be an active AEAD encrypt operation, with no nonce set).

ifx_se_aead_set_nonce()

ifx_se_status_t ifx_se_aead_set_nonce	(	ifx_se_aead_operation_t *	operation,
		const ifx_se_fih_ptr_t	nonce,
		ifx_se_fih_t	nonce_length,
		void *	ctx
	)

Set the nonce for an authenticated encryption or decryption operation.

This function sets the nonce for the authenticated encryption or decryption operation.

The application must call ifx_se_aead_encrypt_setup() or ifx_se_aead_decrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Note

When encrypting, applications should use ifx_se_aead_generate_nonce() instead of this function, unless implementing a protocol that requires a non-random IV.

Parameters

[in,out]	operation	Active AEAD operation.
[in]	nonce	Buffer containing the nonce to use (encoded pointer to input data).
[in]	nonce_length	Size of the nonce in bytes (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_ARGUMENT	The size of nonce is not acceptable for the chosen algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be active, with no nonce set).

ifx_se_aead_set_lengths()

ifx_se_status_t ifx_se_aead_set_lengths	(	ifx_se_aead_operation_t *	operation,
		ifx_se_fih_t	ad_length,
		ifx_se_fih_t	plaintext_length,
		void *	ctx
	)

Declare the lengths of the message and additional data for AEAD.

The application must call this function before calling ifx_se_aead_update_ad() or ifx_se_aead_update() if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.

You may call this function before or after setting the nonce with ifx_se_aead_set_nonce() or ifx_se_aead_generate_nonce().

• For IFX_SE_ALG_CCM, calling this function is required.
• For the other AEAD algorithms defined in this specification, calling this function is not required.
• For vendor-defined algorithm, refer to the vendor documentation.

If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Parameters

[in,out]	operation	Active AEAD operation.
[in]	ad_length	Size of the non-encrypted additional authenticated data in bytes (size_t).
[in]	plaintext_length	Size of the plaintext to encrypt in bytes (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_ARGUMENT	At least one of the lengths is not acceptable for the chosen algorithm.
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be active, and ifx_se_aead_update_ad() and ifx_se_aead_update() must not have been called yet).

ifx_se_aead_update_ad()

ifx_se_status_t ifx_se_aead_update_ad	(	ifx_se_aead_operation_t *	operation,
		const ifx_se_fih_ptr_t	input,
		ifx_se_fih_t	input_length,
		void *	ctx
	)

Pass additional data to an active AEAD operation.

Additional data is authenticated, but not encrypted.

You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with ifx_se_aead_update().

Before calling this function, you must:

1. Call either ifx_se_aead_encrypt_setup() or ifx_se_aead_decrypt_setup().
2. Set the nonce with ifx_se_aead_generate_nonce() or ifx_se_aead_set_nonce().

If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Warning

When decrypting, until ifx_se_aead_verify() has returned IFX_SE_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called ifx_se_aead_verify() and it has returned IFX_SE_SUCCESS, treat the input as untrusted and prepare to undo any action that depends on the input if ifx_se_aead_verify() returns an error status.

Parameters

[in,out]	operation	Active AEAD operation.
[in]	input	Buffer containing the fragment of additional data (encoded pointer to input data).
[in]	input_length	Size of the input buffer in bytes (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_ARGUMENT	The total input length overflows the additional data length that was previously specified with ifx_se_aead_set_lengths().
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be active, have a nonce set, have lengths set if required by the algorithm, and ifx_se_aead_update() must not have been called yet).

ifx_se_aead_update()

ifx_se_status_t ifx_se_aead_update	(	ifx_se_aead_operation_t *	operation,
		const ifx_se_fih_ptr_t	input,
		ifx_se_fih_t	input_length,
		ifx_se_fih_ptr_t	output,
		ifx_se_fih_t	output_size,
		ifx_se_fih_ptr_t	output_length,
		void *	ctx
	)

Encrypt or decrypt a message fragment in an active AEAD operation.

Before calling this function, you must:

1. Call either ifx_se_aead_encrypt_setup() or ifx_se_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
2. Set the nonce with ifx_se_aead_generate_nonce() or ifx_se_aead_set_nonce().
3. Call ifx_se_aead_update_ad() to pass all the additional data.

If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Warning

When decrypting, until ifx_se_aead_verify() has returned IFX_SE_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called ifx_se_aead_verify() and it has returned IFX_SE_SUCCESS:

• Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key.
• In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to.

This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it may delay the end of the corresponding output until a subsequent call to ifx_se_aead_update(), ifx_se_aead_finish() or ifx_se_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by IFX_SE_AEAD_UPDATE_OUTPUT_SIZE.

Parameters

[in,out]	operation	Active AEAD operation.
[in]	input	Buffer containing the message fragment to encrypt or decrypt (encoded pointer to input data).
[in]	input_length	Size of the input buffer in bytes (size_t).
[out]	output	Buffer where the output is to be written (encoded pointer to output buffer).
[in]	output_size	Size of the output buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: A sufficient output size is IFX_SE_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) where key_type is the type of key and alg is the algorithm that were used to set up the operation. IFX_SE_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) evaluates to the maximum output size of any supported AEAD algorithm.
[out]	output_length	On success, the number of bytes that make up the returned output (encoded pointer to size_t variable).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_BUFFER_TOO_SMALL	The size of the output buffer is too small. IFX_SE_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) or IFX_SE_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) can be used to determine the required buffer size.
IFX_SE_ERROR_INVALID_ARGUMENT	The total length of input to ifx_se_aead_update_ad() so far is less than the additional data length that was previously specified with ifx_se_aead_set_lengths(), or the total input length overflows the plaintext length that was previously specified with ifx_se_aead_set_lengths().
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be active, have a nonce set, and have lengths set if required by the algorithm).

ifx_se_aead_finish()

ifx_se_status_t ifx_se_aead_finish	(	ifx_se_aead_operation_t *	operation,
		ifx_se_fih_ptr_t	ciphertext,
		ifx_se_fih_t	ciphertext_size,
		ifx_se_fih_ptr_t	ciphertext_length,
		ifx_se_fih_ptr_t	tag,
		ifx_se_fih_t	tag_size,
		ifx_se_fih_ptr_t	tag_length,
		void *	ctx
	)

Finish encrypting a message in an AEAD operation.

The operation must have been set up with ifx_se_aead_encrypt_setup().

This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to ifx_se_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to ifx_se_aead_update().

This function has two output buffers:

• ciphertext contains trailing ciphertext that was buffered from preceding calls to ifx_se_aead_update().
• tag contains the authentication tag.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Parameters

[in,out]	operation	Active AEAD operation.
[out]	ciphertext	Buffer where the last part of the ciphertext is to be written (encoded pointer to output buffer).
[in]	ciphertext_size	Size of the ciphertext buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: A sufficient output size is IFX_SE_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation. IFX_SE_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
[out]	ciphertext_length	On success, the number of bytes of returned ciphertext (encoded pointer to size_t variable).
[out]	tag	Buffer where the authentication tag is to be written (encoded pointer to output buffer).
[in]	tag_size	Size of the tag buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: The exact tag size is IFX_SE_AEAD_TAG_LENGTH(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size of the key, and alg is the algorithm that were used in the call to ifx_se_aead_encrypt_setup(). IFX_SE_AEAD_TAG_MAX_SIZE evaluates to the maximum tag size of any supported AEAD algorithm.
[out]	tag_length	On success, the number of bytes that make up the returned tag (encoded pointer to size_t variable).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_BUFFER_TOO_SMALL	The size of the ciphertext or tag buffer is too small. IFX_SE_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) or IFX_SE_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the required ciphertext buffer size. IFX_SE_AEAD_TAG_LENGTH(key_type, key_bits, alg) or IFX_SE_AEAD_TAG_MAX_SIZE can be used to determine the required tag buffer size.
IFX_SE_ERROR_INVALID_ARGUMENT	The total length of input to ifx_se_aead_update_ad() so far is less than the additional data length that was previously specified with ifx_se_aead_set_lengths(), or the total length of input to ifx_se_aead_update() so far is less than the plaintext length that was previously specified with ifx_se_aead_set_lengths().
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be an active encryption operation with a nonce set).

ifx_se_aead_verify()

ifx_se_status_t ifx_se_aead_verify	(	ifx_se_aead_operation_t *	operation,
		ifx_se_fih_ptr_t	plaintext,
		ifx_se_fih_t	plaintext_size,
		ifx_se_fih_ptr_t	plaintext_length,
		const ifx_se_fih_ptr_t	tag,
		ifx_se_fih_t	tag_length,
		void *	ctx
	)

Finish authenticating and decrypting a message in an AEAD operation.

The operation must have been set up with ifx_se_aead_decrypt_setup().

This function finishes the authenticated decryption of the message components:

• The additional data consisting of the concatenation of the inputs passed to preceding calls to ifx_se_aead_update_ad().
• The ciphertext consisting of the concatenation of the inputs passed to preceding calls to ifx_se_aead_update().
• The tag passed to this function call.

If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns IFX_SE_ERROR_INVALID_SIGNATURE.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling ifx_se_aead_abort().

Note

Implementations shall make the best effort to ensure that the comparison between the actual tag and the expected tag is performed in constant time.

Parameters

[in,out]	operation	Active AEAD operation.
[out]	plaintext	Buffer where the last part of the plaintext is to be written (encoded pointer to output buffer). This is the remaining data from previous calls to ifx_se_aead_update() that could not be processed until the end of the input.
[in]	plaintext_size	Size of the plaintext buffer in bytes (size_t). This must be appropriate for the selected algorithm and key: A sufficient output size is IFX_SE_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation. IFX_SE_AEAD_VERIFY_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
[out]	plaintext_length	On success, the number of bytes of returned plaintext (encoded pointer to size_t variable).
[in]	tag	Buffer containing the authentication tag (encoded pointer to input data).
[in]	tag_length	Size of the tag buffer in bytes (size_t).
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS	Success.
IFX_SE_ERROR_INVALID_SIGNATURE	The calculations were successful, but the authentication tag is not correct.
IFX_SE_ERROR_BUFFER_TOO_SMALL	The size of the plaintext buffer is too small. IFX_SE_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) or IFX_SE_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the required buffer size.
IFX_SE_ERROR_INVALID_ARGUMENT	The total length of input to ifx_se_aead_update_ad() so far is less than the additional data length that was previously specified with ifx_se_aead_set_lengths(), or the total length of input to ifx_se_aead_update() so far is less than the plaintext length that was previously specified with ifx_se_aead_set_lengths().
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be an active decryption operation with a nonce set).

ifx_se_aead_abort()

ifx_se_status_t ifx_se_aead_abort	(	ifx_se_aead_operation_t *	operation,
		void *	ctx
	)

Abort an AEAD operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling ifx_se_aead_encrypt_setup() or ifx_se_aead_decrypt_setup() again.

You may call this function any time after the operation object has been initialized as described in ifx_se_aead_operation_t.

In particular, calling ifx_se_aead_abort() after the operation has been terminated by a call to ifx_se_aead_abort(), ifx_se_aead_finish() or ifx_se_aead_verify() is safe and has no effect.

Parameters

[in,out]	operation	Initialized AEAD operation.
[in]	ctx	The pointer to the SE syscall context that contain a special syscall data (IPC release callback etc).

Return values

IFX_SE_SUCCESS
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED

ifx_se_aead_operation_init()

static struct ifx_se_aead_operation_s ifx_se_aead_operation_init ( void  )

inlinestatic

Initialize the AEAD operation context.

Returns

ifx_se_aead_operation_s structure