MAC operations

General Description

MAC operations definitions.

Macros
#define	IFX_SE_MAC_OPERATION_INIT   {0}
	The initial value of the MAC operation context.

Typedefs
typedef struct ifx_se_mac_operation_s	ifx_se_mac_operation_t
	The type of the state data structure for multipart MAC operations. More...

Functions
ifx_se_status_t	ifx_se_mac_sign_setup (ifx_se_mac_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set up a multipart MAC calculation operation. More...
ifx_se_status_t	ifx_se_mac_verify_setup (ifx_se_mac_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set up a multipart MAC verification operation. More...
ifx_se_status_t	ifx_se_mac_update (ifx_se_mac_operation_t *operation, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, void *ctx)
	Add a message fragment to a multipart MAC operation. More...
ifx_se_status_t	ifx_se_mac_sign_finish (ifx_se_mac_operation_t *operation, ifx_se_fih_ptr_t mac, ifx_se_fih_t mac_size, ifx_se_fih_ptr_t mac_length, void *ctx)
	Finish the calculation of the MAC of a message. More...
ifx_se_status_t	ifx_se_mac_verify_finish (ifx_se_mac_operation_t *operation, const ifx_se_fih_ptr_t mac, ifx_se_fih_t mac_length, void *ctx)
	Finish the calculation of the MAC of a message and compare it with an expected value. More...
ifx_se_status_t	ifx_se_mac_abort (ifx_se_mac_operation_t *operation, void *ctx)
	Abort a MAC operation. More...
ifx_se_status_t	ifx_se_mac_compute (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, ifx_se_fih_ptr_t mac, ifx_se_fih_t mac_size, ifx_se_fih_ptr_t mac_length, void *ctx)
	Calculate the MAC (message authentication code) of a message. More...
ifx_se_status_t	ifx_se_mac_verify (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t input, ifx_se_fih_t input_length, const ifx_se_fih_ptr_t mac, ifx_se_fih_t mac_length, void *ctx)
	Calculate the MAC of a message and compare it with a reference value. More...
static struct ifx_se_mac_operation_s	ifx_se_mac_operation_init (void)
	Initialize the MAC operation context. More...

Typedef Documentation

ifx_se_mac_operation_t

typedef struct ifx_se_mac_operation_s ifx_se_mac_operation_t

The type of the state data structure for multipart MAC 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_mac_sign_setup()

ifx_se_status_t ifx_se_mac_sign_setup	(	ifx_se_mac_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set up a multipart MAC calculation operation.

This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use ifx_se_mac_verify_setup() instead.

The sequence of operations to calculate a MAC 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_mac_operation_t, e.g. IFX_SE_MAC_OPERATION_INIT.
3. Call ifx_se_mac_sign_setup() to specify the algorithm and key.
4. Call ifx_se_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
5. At the end of the message, call ifx_se_mac_sign_finish() to finish calculating the MAC value and retrieve it.

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

After a successful call to ifx_se_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:

• A successful call to ifx_se_mac_sign_finish().
• A call to ifx_se_mac_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_mac_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_SIGN_MESSAGE.
[in]	alg	The MAC algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_MAC(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 a MAC 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	The key could not be retrieved from storage.
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be inactive).

ifx_se_mac_verify_setup()

ifx_se_status_t ifx_se_mac_verify_setup	(	ifx_se_mac_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set up a multipart MAC verification operation.

This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.

The sequence of operations to verify a MAC 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_mac_operation_t, e.g. IFX_SE_MAC_OPERATION_INIT.
3. Call ifx_se_mac_verify_setup() to specify the algorithm and key.
4. Call ifx_se_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
5. At the end of the message, call ifx_se_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.

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

After a successful call to ifx_se_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:

• A successful call to ifx_se_mac_verify_finish().
• A call to ifx_se_mac_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_mac_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_VERIFY_MESSAGE.
[in]	alg	The MAC algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_MAC(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 a MAC 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	The key could not be retrieved from storage.
IFX_SE_ERROR_BAD_STATE	The operation state is not valid (it must be inactive).

ifx_se_mac_update()

ifx_se_status_t ifx_se_mac_update	(	ifx_se_mac_operation_t *	operation,
		const ifx_se_fih_ptr_t	input,
		ifx_se_fih_t	input_length,
		void *	ctx
	)

Add a message fragment to a multipart MAC operation.

The application must call ifx_se_mac_sign_setup() or ifx_se_mac_verify_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_mac_abort().

Parameters

[in,out]	operation	Active MAC operation.
[in]	input	Buffer containing the message fragment to add to the MAC calculation (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_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).

ifx_se_mac_sign_finish()

ifx_se_status_t ifx_se_mac_sign_finish	(	ifx_se_mac_operation_t *	operation,
		ifx_se_fih_ptr_t	mac,
		ifx_se_fih_t	mac_size,
		ifx_se_fih_ptr_t	mac_length,
		void *	ctx
	)

Finish the calculation of the MAC of a message.

The application must call ifx_se_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to ifx_se_mac_update().

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_mac_abort().

Warning

Applications should not call this function if they expect a specific value for the MAC. Call ifx_se_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

[in,out]	operation	Active MAC operation.
[out]	mac	Buffer where the MAC value is to be written (encoded pointer to output buffer).
[in]	mac_size	Size of the mac buffer in bytes (size_t).
[out]	mac_length	On success, the number of bytes that make up the MAC value (encoded pointer to size_t variable). This is always IFX_SE_MAC_LENGTH(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of the key and alg is the MAC algorithm that is calculated.
[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 mac buffer is too small. You can determine a sufficient buffer size by calling IFX_SE_MAC_LENGTH().
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 mac sign operation).

ifx_se_mac_verify_finish()

ifx_se_status_t ifx_se_mac_verify_finish	(	ifx_se_mac_operation_t *	operation,
		const ifx_se_fih_ptr_t	mac,
		ifx_se_fih_t	mac_length,
		void *	ctx
	)

Finish the calculation of the MAC of a message and compare it with an expected value.

The application must call ifx_se_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to ifx_se_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function.

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_mac_abort().

Note

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

Parameters

[in,out]	operation	Active MAC operation.
[in]	mac	Buffer containing the expected MAC value (encoded pointer to input data).
[in]	mac_length	Size of the mac 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	The expected MAC is identical to the actual MAC of the message.
IFX_SE_ERROR_INVALID_SIGNATURE	The MAC of the message was calculated successfully, but it differs from the expected MAC.
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 mac verify operation).

ifx_se_mac_abort()

ifx_se_status_t ifx_se_mac_abort	(	ifx_se_mac_operation_t *	operation,
		void *	ctx
	)

Abort a MAC 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_mac_sign_setup() or ifx_se_mac_verify_setup() again.

You may call this function any time after the operation object has been initialized by one of the methods described in ifx_se_mac_operation_t.

In particular, calling ifx_se_mac_abort() after the operation has been terminated by a call to ifx_se_mac_abort(), ifx_se_mac_sign_finish() or ifx_se_mac_verify_finish() is safe and has no effect.

Parameters

[in,out]	operation	Initialized MAC 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_mac_compute()

ifx_se_status_t ifx_se_mac_compute	(	ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		const ifx_se_fih_ptr_t	input,
		ifx_se_fih_t	input_length,
		ifx_se_fih_ptr_t	mac,
		ifx_se_fih_t	mac_size,
		ifx_se_fih_ptr_t	mac_length,
		void *	ctx
	)

Calculate the MAC (message authentication code) of a message.

Note

To verify the MAC of a message against an expected value, use ifx_se_mac_verify() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

[in]	key	Identifier of the key to use for the operation. It must allow the usage IFX_SE_KEY_USAGE_SIGN_MESSAGE.
[in]	alg	The MAC algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_MAC(alg) is true).
[in]	input	Buffer containing the input message (encoded pointer to input data).
[in]	input_length	Size of the input buffer in bytes (size_t).
[out]	mac	Buffer where the MAC value is to be written (encoded pointer to output buffer).
[in]	mac_size	Size of the mac buffer in bytes (size_t).
[out]	mac_length	On success, the number of bytes that make up the MAC value (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 a MAC algorithm.
IFX_SE_ERROR_BUFFER_TOO_SMALL	mac_size 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	The key could not be retrieved from storage.

ifx_se_mac_verify()

ifx_se_status_t ifx_se_mac_verify	(	ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		const ifx_se_fih_ptr_t	input,
		ifx_se_fih_t	input_length,
		const ifx_se_fih_ptr_t	mac,
		ifx_se_fih_t	mac_length,
		void *	ctx
	)

Calculate the MAC of a message and compare it with a reference value.

Parameters

[in]	key	Identifier of the key to use for the operation. It must allow the usage IFX_SE_KEY_USAGE_VERIFY_MESSAGE.
[in]	alg	The MAC algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_MAC(alg) is true).
[in]	input	Buffer containing the input message (encoded pointer to input data).
[in]	input_length	Size of the input buffer in bytes (size_t).
[in]	mac	Buffer containing the expected MAC value (encoded pointer to input data).
[in]	mac_length	Size of the mac 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	The expected MAC is identical to the actual MAC of the input.
IFX_SE_ERROR_INVALID_SIGNATURE	The MAC of the message was calculated successfully, but it differs from the expected value.
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 a MAC 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	The key could not be retrieved from storage.

ifx_se_mac_operation_init()

static struct ifx_se_mac_operation_s ifx_se_mac_operation_init ( void  )

inlinestatic

Initialize the MAC operation context.

Returns

ifx_se_mac_operation_s structure