Cipher operations

General Description

Cipher operations definitions.

Macros
#define	IFX_SE_CIPHER_OPERATION_INIT   {0}
	The initial value of the Cipher operation context.

Typedefs
typedef struct ifx_se_cipher_operation_s	ifx_se_cipher_operation_t
	The type of the state data structure for multipart cipher operations. More...

Functions
ifx_se_status_t	ifx_se_cipher_encrypt (ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, const ifx_se_fih_ptr_t iv, ifx_se_fih_t iv_length, 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 a message using a symmetric cipher with provided IV. More...
ifx_se_status_t	ifx_se_cipher_decrypt (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 output, ifx_se_fih_t output_size, ifx_se_fih_ptr_t output_length, void *ctx)
	Decrypt a message using a symmetric cipher. More...
ifx_se_status_t	ifx_se_cipher_encrypt_setup (ifx_se_cipher_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set the key for a multipart symmetric encryption operation. More...
ifx_se_status_t	ifx_se_cipher_decrypt_setup (ifx_se_cipher_operation_t *operation, ifx_se_key_id_fih_t key, ifx_se_alg_fih_t alg, void *ctx)
	Set the key for a multipart symmetric decryption operation. More...
ifx_se_status_t	ifx_se_cipher_generate_iv (ifx_se_cipher_operation_t *operation, ifx_se_fih_ptr_t iv, ifx_se_fih_t iv_size, ifx_se_fih_ptr_t iv_length, void *ctx)
	Generate an IV for a symmetric encryption operation. More...
ifx_se_status_t	ifx_se_cipher_set_iv (ifx_se_cipher_operation_t *operation, const ifx_se_fih_ptr_t iv, ifx_se_fih_t iv_length, void *ctx)
	Set the IV for a symmetric encryption or decryption operation. More...
ifx_se_status_t	ifx_se_cipher_update (ifx_se_cipher_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 cipher operation. More...
ifx_se_status_t	ifx_se_cipher_finish (ifx_se_cipher_operation_t *operation, ifx_se_fih_ptr_t output, ifx_se_fih_t output_size, ifx_se_fih_ptr_t output_length, void *ctx)
	Finish encrypting or decrypting a message in a cipher operation. More...
ifx_se_status_t	ifx_se_cipher_abort (ifx_se_cipher_operation_t *operation, void *ctx)
	Abort a cipher operation. More...
static struct ifx_se_cipher_operation_s	ifx_se_cipher_operation_init (void)
	Initialize the Cipher operation context. More...

Typedef Documentation

ifx_se_cipher_operation_t

typedef struct ifx_se_cipher_operation_s ifx_se_cipher_operation_t

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

ifx_se_status_t ifx_se_cipher_encrypt	(	ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		const ifx_se_fih_ptr_t	iv,
		ifx_se_fih_t	iv_length,
		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 a message using a symmetric cipher with provided IV.

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 cipher algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_CIPHER(alg) is true).
[in]	iv	Buffer containing the IV to use (encoded pointer to input data).
[in]	iv_length	Size of the IV in bytes (size_t).
[in]	input	Buffer containing the message to encrypt (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).
[out]	output_length	On success, the number of bytes that make up the 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_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 cipher algorithm.
IFX_SE_ERROR_BUFFER_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_cipher_decrypt()

ifx_se_status_t ifx_se_cipher_decrypt	(	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	output,
		ifx_se_fih_t	output_size,
		ifx_se_fih_ptr_t	output_length,
		void *	ctx
	)

Decrypt a message using a symmetric cipher.

This function decrypts a message encrypted with a symmetric cipher.

Parameters

[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 cipher algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_CIPHER(alg) is true).
[in]	input	Buffer containing the message to decrypt (encoded pointer to input data). This consists of the IV followed by the ciphertext proper.
[in]	input_length	Size of the input buffer in bytes (size_t).
[out]	output	Buffer where the plaintext is to be written (encoded pointer to output buffer).
[in]	output_size	Size of the output buffer in bytes (size_t).
[out]	output_length	On success, the number of bytes that make up the 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_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 cipher algorithm.
IFX_SE_ERROR_BUFFER_TOO_SMALL
IFX_SE_ERROR_INSUFFICIENT_MEMORY
IFX_SE_ERROR_COMMUNICATION_FAILURE
IFX_SE_ERROR_HARDWARE_FAILURE
IFX_SE_ERROR_STORAGE_FAILURE
IFX_SE_ERROR_CORRUPTION_DETECTED

ifx_se_cipher_encrypt_setup()

ifx_se_status_t ifx_se_cipher_encrypt_setup	(	ifx_se_cipher_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set the key for a multipart symmetric encryption operation.

The sequence of operations to encrypt a message with a symmetric cipher 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_cipher_operation_t, e.g. IFX_SE_CIPHER_OPERATION_INIT.
3. Call ifx_se_cipher_encrypt_setup() to specify the algorithm and key.
4. Call either ifx_se_cipher_generate_iv() or ifx_se_cipher_set_iv() to generate or set the IV (initialization vector). You should use ifx_se_cipher_generate_iv() unless the protocol you are implementing requires a specific IV value.
5. Call ifx_se_cipher_update() zero, one or more times, passing a fragment of the message each time.
6. Call ifx_se_cipher_finish().

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

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

• A successful call to ifx_se_cipher_finish().
• A call to ifx_se_cipher_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_cipher_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 cipher algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_CIPHER(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 cipher 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 inactive).

ifx_se_cipher_decrypt_setup()

ifx_se_status_t ifx_se_cipher_decrypt_setup	(	ifx_se_cipher_operation_t *	operation,
		ifx_se_key_id_fih_t	key,
		ifx_se_alg_fih_t	alg,
		void *	ctx
	)

Set the key for a multipart symmetric decryption operation.

The sequence of operations to decrypt a message with a symmetric cipher 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_cipher_operation_t, e.g. IFX_SE_CIPHER_OPERATION_INIT.
3. Call ifx_se_cipher_decrypt_setup() to specify the algorithm and key.
4. Call ifx_se_cipher_set_iv() with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call ifx_se_cipher_update() on a buffer containing the IV followed by the beginning of the message.
5. Call ifx_se_cipher_update() zero, one or more times, passing a fragment of the message each time.
6. Call ifx_se_cipher_finish().

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

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

• A successful call to ifx_se_cipher_finish().
• A call to ifx_se_cipher_abort().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for ifx_se_cipher_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 cipher algorithm to compute (IFX_SE_ALG_XXX value such that IFX_SE_ALG_IS_CIPHER(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 cipher 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 inactive).

ifx_se_cipher_generate_iv()

ifx_se_status_t ifx_se_cipher_generate_iv	(	ifx_se_cipher_operation_t *	operation,
		ifx_se_fih_ptr_t	iv,
		ifx_se_fih_t	iv_size,
		ifx_se_fih_ptr_t	iv_length,
		void *	ctx
	)

Generate an IV for a symmetric encryption operation.

This function generates a random IV (initialization vector), nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.

The application must call ifx_se_cipher_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_cipher_abort().

Parameters

[in,out]	operation	Active cipher operation.
[out]	iv	Buffer where the generated IV is to be written (encoded pointer to output buffer).
[in]	iv_size	Size of the iv buffer in bytes (size_t).
[out]	iv_length	On success, the number of bytes of the generated IV (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 iv 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 active, with no IV set).

ifx_se_cipher_set_iv()

ifx_se_status_t ifx_se_cipher_set_iv	(	ifx_se_cipher_operation_t *	operation,
		const ifx_se_fih_ptr_t	iv,
		ifx_se_fih_t	iv_length,
		void *	ctx
	)

Set the IV for a symmetric encryption or decryption operation.

This function sets the IV (initialization vector), nonce or initial counter value for the encryption or decryption operation.

The application must call ifx_se_cipher_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_cipher_abort().

Note

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

Parameters

[in,out]	operation	Active cipher operation.
[in]	iv	Buffer containing the IV to use (encoded pointer to input data).
[in]	iv_length	Size of the IV 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 iv is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.
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 cipher encrypt operation, with no IV set).

ifx_se_cipher_update()

ifx_se_status_t ifx_se_cipher_update	(	ifx_se_cipher_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 cipher operation.

Before calling this function, you must:

1. Call either ifx_se_cipher_encrypt_setup() or ifx_se_cipher_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
2. If the algorithm requires an IV, call ifx_se_cipher_generate_iv() (recommended when encrypting) or ifx_se_cipher_set_iv().

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

Parameters

[in,out]	operation	Active cipher 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).
[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_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 an IV set if required for the algorithm).

ifx_se_cipher_finish()

ifx_se_status_t ifx_se_cipher_finish	(	ifx_se_cipher_operation_t *	operation,
		ifx_se_fih_ptr_t	output,
		ifx_se_fih_t	output_size,
		ifx_se_fih_ptr_t	output_length,
		void *	ctx
	)

Finish encrypting or decrypting a message in a cipher operation.

The application must call ifx_se_cipher_encrypt_setup() or ifx_se_cipher_decrypt_setup() before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.

This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to ifx_se_cipher_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_cipher_abort().

Parameters

[in,out]	operation	Active cipher operation.
[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).
[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_INVALID_ARGUMENT	The total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.
IFX_SE_ERROR_INVALID_PADDING	This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.
IFX_SE_ERROR_BUFFER_TOO_SMALL	The size of the output 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 active, with an IV set if required for the algorithm).

ifx_se_cipher_abort()

ifx_se_status_t ifx_se_cipher_abort	(	ifx_se_cipher_operation_t *	operation,
		void *	ctx
	)

Abort a cipher 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_cipher_encrypt_setup() or ifx_se_cipher_decrypt_setup() again.

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

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

Parameters

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

static struct ifx_se_cipher_operation_s ifx_se_cipher_operation_init ( void  )

inlinestatic

Initialize the Cipher operation context.

Returns

ifx_se_cipher_operation_s structure