Cipher operations

General Description

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

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

Functions
cy_p64_psa_status_t	cy_p64_psa_cipher_decrypt_setup (cy_p64_psa_cipher_operation_t *operation, cy_p64_psa_key_handle_t handle, cy_p64_psa_algorithm_t alg)
	Sets the key for a multipart symmetric decryption operation. More...
cy_p64_psa_status_t	cy_p64_psa_cipher_finish (cy_p64_psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)
	Finishes encrypting or decrypting a message in a cipher operation. More...
cy_p64_psa_status_t	cy_p64_psa_cipher_set_iv (cy_p64_psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)
	Set the IV for a symmetric decryption operation. More...
cy_p64_psa_status_t	cy_p64_psa_cipher_update (cy_p64_psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
	Decrypt a message fragment in an active cipher operation. More...
static struct cy_p64_psa_cipher_operation_s	cy_p64_psa_cipher_operation_init (void)
	Initialize the Cipher operation context.

Typedef Documentation

cy_p64_psa_cipher_operation_t

typedef struct cy_p64_psa_cipher_operation_s cy_p64_psa_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

cy_p64_psa_cipher_decrypt_setup()

cy_p64_psa_status_t cy_p64_psa_cipher_decrypt_setup	(	cy_p64_psa_cipher_operation_t *	operation,
		cy_p64_psa_key_handle_t	handle,
		cy_p64_psa_algorithm_t	alg
	)

Sets 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 cy_p64_psa_cipher_operation_t, e.g. CY_P64_PSA_CIPHER_OPERATION_INIT.
3. Call cy_p64_psa_cipher_decrypt_setup() to specify the algorithm and key.
4. Call cy_p64_psa_cipher_set_iv() with the IV (initialization vector) for the decryption. If the IV is prepended to the ciphertext, you can call cy_p64_psa_cipher_update() on a buffer containing the IV followed by the beginning of the message.
5. Call cy_p64_psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
6. Call cy_p64_psa_cipher_finish().

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

• A successful call to cy_p64_psa_cipher_finish().

Parameters

[in,out]	operation	The operation object to set up. It must have been initialized as per the documentation for cy_p64_psa_cipher_operation_t and not yet in use.
	handle	Handle to the key to use for the operation. It must remain valid until the operation terminates.
	alg	The cipher algorithm to compute (CY_P64_PSA_ALG_XXX value such that CY_P64_PSA_ALG_IS_CIPHER(alg) is true).

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_INVALID_HANDLE
CY_P64_PSA_ERROR_NOT_PERMITTED
CY_P64_PSA_ERROR_INVALID_ARGUMENT	handle is not compatible with alg.
CY_P64_PSA_ERROR_NOT_SUPPORTED	alg is not supported or is not a cipher algorithm.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be inactive).

cy_p64_psa_cipher_finish()

cy_p64_psa_status_t cy_p64_psa_cipher_finish	(	cy_p64_psa_cipher_operation_t *	operation,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Finishes encrypting or decrypting a message in a cipher operation.

The application must call cy_p64_psa_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 cy_p64_psa_cipher_update().

When this function returns successfully, the operation becomes inactive.

Parameters

[in,out]	operation	Active cipher operation.
[out]	output	The buffer to write the output in.
	output_size	The size of the output buffer in bytes.
[out]	output_length	On success, the number of bytes that make up the returned output.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_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.
CY_P64_PSA_ERROR_INVALID_PADDING	This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be active, with an IV set if required for the algorithm).
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL	The size of the output buffer is too small.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE

cy_p64_psa_cipher_set_iv()

cy_p64_psa_status_t cy_p64_psa_cipher_set_iv	(	cy_p64_psa_cipher_operation_t *	operation,
		const uint8_t *	iv,
		size_t	iv_length
	)

Set the IV for a symmetric decryption operation.

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

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

Parameters

[in,out]	operation	Active cipher operation.
[in]	iv	The buffer that contains the IV to use.
	iv_length	The size of the IV in bytes.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be an active cipher encrypt operation, with no IV set).
CY_P64_PSA_ERROR_INVALID_ARGUMENT	The size of iv is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE

cy_p64_psa_cipher_update()

cy_p64_psa_status_t cy_p64_psa_cipher_update	(	cy_p64_psa_cipher_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Decrypt a message fragment in an active cipher operation.

Before calling this function, you must:

1. Call cy_p64_psa_cipher_decrypt_setup().
2. If the algorithm requires an IV, call cy_p64_psa_cipher_set_iv().

Parameters

[in,out]	operation	Active cipher operation.
[in]	input	The buffer that contains the message fragment to encrypt or decrypt.
	input_length	The size of the input buffer in bytes.
[out]	output	The buffer to write the output in.
	output_size	The size of the output buffer in bytes.
[out]	output_length	On success, the number of bytes that make up the returned output.

Return values

CY_P64_PSA_SUCCESS	Success.
CY_P64_PSA_ERROR_BAD_STATE	The operation state is not valid (it must be active, with an IV set if required for the algorithm).
CY_P64_PSA_ERROR_BUFFER_TOO_SMALL	The size of the output buffer is too small.
CY_P64_PSA_ERROR_INSUFFICIENT_MEMORY
CY_P64_PSA_ERROR_COMMUNICATION_FAILURE
CY_P64_PSA_ERROR_HARDWARE_FAILURE
CY_P64_PSA_ERROR_CORRUPTION_DETECTED
CY_P64_PSA_ERROR_STORAGE_FAILURE