RTOS-integrated Crypto Cipher Framework Module. More...

Data Structures
struct	sf_crypto_cipher_instance_ctrl_t

Macros
#define	SF_CRYPTO_CIPHER_CODE_VERSION_MAJOR (2U)

#define	SF_CRYPTO_CIPHER_API_VERSION_MAJOR (1U)

#define	SF_CRYPTO_CIPHER_AES_128_XTS_KEY_SIZE (2 * (AES128_SECRET_KEY_SIZE_BYTES))

#define	SF_CRYPTO_CIPHER_AES_GCM_TAG_LENGTH_16_BYTES (16U)
	AES GCM tag of length 16 bytes.

#define	SF_CRYPTO_CIPHER_AES_IV_LENGTH_12_BYTES (12U)
	IV for AES operations - 16 bytes.

#define	SF_CRYPTO_CIPHER_AES_GCM_IV_PAD_4_BYTES (4U)
	4 byte padding for 96-bit IV.

#define	SF_CRYPTO_CIPHER_AES_IV_LENGTH_16_BYTES (16U)
	IV for AES operations - 16 bytes.

#define	SF_CRYPTO_CIPHER_AES_BLOCK_SIZE_BYTES (16U)
	AES block size = 16 bytes.

#define	SF_CRYPTO_CIPHER_BYTES_PER_WORD (4U)
	number of bytes in a WORD.

#define	SF_CRYPTO_CIPHER_RSA_1024_MODULUS_BITS (1024U)
	Modulus size of RSA 1024-bit key. More...

#define	SF_CRYPTO_CIPHER_RSA_2048_MODULUS_BITS (2048U)
	Modulus size of RSA 2048-bit key.

#define	SF_CRYPTO_PKCS_1_5_EB_START_BYTE (0U)
	Encryption Block start byte = 00.

#define	SF_CRYPTO_PKCS_1_5_BT_00 (0U)
	Encryption Block Type (BT) = 00.

#define	SF_CRYPTO_PKCS_1_5_BT_01 (1U)
	Encryption Block Type (BT) = 01.

#define	SF_CRYPTO_PKCS_1_5_BT_02 (2U)
	Encryption Block Type (BT) = 02.

#define	SF_CRYPTO_PKCS_1_5_EB_DATA_SEPARATOR (0U)
	EB Data separator (between PS and Data).

#define	SF_CRYPTO_PKCS_1_5_EB_START_BYTE_LENGTH (1U)
	Encryption Block Start Byte length.

#define	SF_CRYPTO_PKCS_1_5_EB_BT_BYTE_LENGTH (1U)
	Encryption Block Block Type field length.

#define	SF_CRYPTO_PKCS_1_5_EB_PS_MIN_LENGTH (8U)
	Encryption Block Padding String (PS) min length.

#define	SF_CRYPTO_PKCS_1_5_EB_DATA_SEPARATOR_LENGTH (1U)
	EB Data separator (between PS and Data)length.

#define	SF_CRYPTO_PKCS_1_5_EB_OVERHEAD

Enumerations
enum	sf_crypto_cipher_state_t { SF_CRYPTO_CIPHER_STATE_CLOSED, SF_CRYPTO_CIPHER_STATE_OPENED, SF_CRYPTO_CIPHER_STATE_INITIALIZED, SF_CRYPTO_CIPHER_STATE_UPDATED, SF_CRYPTO_CIPHER_STATE_FINALIZED }

Functions
void	sf_crypto_cipher_aes_interface_get (sf_crypto_cipher_instance_ctrl_t *const p_ctrl)
	Subroutine to get a pointer to the AES HAL API instance. More...

bool	sf_crypto_cipher_is_key_type_aes (sf_crypto_key_type_t key_type)
	Subroutine to check if the key type enum provided is a valid AES key type for cipher operation. More...

ssp_err_t	sf_crypto_cipher_aes_init (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_cipher_op_mode_t cipher_operation_mode, sf_crypto_key_t const const p_key, sf_crypto_cipher_algorithm_init_params_t *p_algorithm_specific_params)
	Subroutine to initialize the AES cipher operation. More...

ssp_err_t	sf_crypto_cipher_aes_update (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Subroutine to update the cipher AES operation. More...

ssp_err_t	sf_crypto_cipher_aes_validate_aad_update_params_context (sf_crypto_cipher_instance_ctrl_t *const p_ctrl)
	Subroutine to validate the context buffer parameters for the cipherAadUpdate operation. More...

ssp_err_t	sf_crypto_cipher_aes_aad_update (sf_crypto_cipher_instance_ctrl_t p_ctrl, sf_crypto_data_handle_t const const p_aad)
	Subroutine to update the AAD for the cipher operation. More...

ssp_err_t	sf_crypto_cipher_aes_encrypt_final (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Subroutine to finalize the cipher encrypt operation. More...

ssp_err_t	sf_crypto_cipher_aes_decrypt_final (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Subroutine to finalize the cipher decrypt operation. More...

ssp_err_t	sf_crypto_cipher_aes_final (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Sub-routine for Crypto Cipher Framework to call the appropriate routine for final encryption based on the algorithm for the cipherFinal operation. This function is called by SF_CRYPTO_CIPHER_CipherFinal(). More...

ssp_err_t	sf_crypto_cipher_initialize_aes_instance (sf_crypto_cipher_instance_ctrl_t p_ctrl, sf_crypto_cipher_cfg_t const const p_cfg)
	Allocates memory for the instance and opens the underlying HAL instance. More...

ssp_err_t	sf_crypto_cipher_deinitialize_aes_instance (sf_crypto_cipher_instance_ctrl_t *p_ctrl)
	closes the underlying HAL instance and releases the memory for the instance. More...

__STATIC_INLINE uint32_t	SF_CRYPTO_CIPHER_RSA_EB_SIZE_BYTES (uint32_t key_size_bits)
	Routine to calculate and return the Encryption block size based on the key size. More...

__STATIC_INLINE uint32_t	SF_CRYPTO_CIPHER_RSA_PKCS_1_5_EB_DATA_SIZE_BYTES (uint32_t key_size_bits)
	Routine to calculate and return the Encryption block size based on the key size. More...

void	sf_crypto_cipher_rsa_interface_get (sf_crypto_cipher_instance_ctrl_t *const p_ctrl)
	Subroutine to get a RSA HAL API instance. This function is called by sf_crypto_cipher_open_rsa(). More...

bool	sf_crypto_cipher_is_key_type_rsa (sf_crypto_key_type_t key_type)
	Subroutine to check if key type is RSA. More...

ssp_err_t	sf_crypto_cipher_rsa_init (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_cipher_op_mode_t cipher_operation_mode, sf_crypto_key_t const const p_key, sf_crypto_cipher_algorithm_init_params_t *p_algorithm_specific_params)
	Routine to handle the cipherInit RSA operation. More...

ssp_err_t	sf_crypto_cipher_rsa_update (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Subroutine to update the cipher RSA operation. This algorithm is only suitable for messages of limited length. The total number of input bytes processed during encryption may not be more than k-11, where k is the RSA key's modulus size in bytes. The encryption block(EB) during encryption with a Public key is built as follows: EB = 00 \|\| 02 \|\| PS \|\| 00 \|\| M :: M (input bytes) is the plaintext message :: PS is an octet string of length k-3-\|\|M\|\| of pseudo random nonzero octets. The length of PS must be at least 8 octets. :: k is the RSA modulus size. More...

ssp_err_t	sf_crypto_cipher_rsa_final (sf_crypto_cipher_instance_ctrl_t const p_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	Routine to process the final encryption / decryption operation for RSA. This function is called by SF_CRYPTO_CIPHER_CipherFinal(). More...

ssp_err_t	sf_crypto_cipher_initialize_rsa_instance (sf_crypto_cipher_instance_ctrl_t p_ctrl, sf_crypto_cipher_cfg_t const const p_cfg)
	Allocates memory for the instance and opens the underlying HAL instance. More...

ssp_err_t	sf_crypto_cipher_deinitialize_rsa_instance (sf_crypto_cipher_instance_ctrl_t *p_ctrl)
	closes the underlying HAL instance and releases the memory for the instance. More...

ssp_err_t	SF_CRYPTO_CIPHER_Open (sf_crypto_cipher_ctrl_t const p_api_ctrl, sf_crypto_cipher_cfg_t const const p_cfg)
	SSP Crypto Cipher Framework Open operation. More...

ssp_err_t	SF_CRYPTO_CIPHER_Close (sf_crypto_cipher_ctrl_t *const p_api_ctrl)
	SSP Crypto Cipher Framework Close operation. More...

ssp_err_t	SF_CRYPTO_CIPHER_VersionGet (ssp_version_t *const p_version)
	Gets driver version based on compile time macros. More...

ssp_err_t	SF_CRYPTO_CIPHER_CipherInit (sf_crypto_cipher_ctrl_t const p_api_ctrl, sf_crypto_cipher_op_mode_t cipher_operation_mode, sf_crypto_key_t const const p_key, sf_crypto_cipher_algorithm_init_params_t *const p_algorithm_specific_params)
	SSP Crypto Framework Cipher Init operation. The input parameters initialize the cipher operation. Some of the parameters are algorithm specific. The input parameters are validated and then copied into the context buffer. Refer to sf_crypto_cipher_aes_init_params_t or sf_crypto_cipher_rsa_init_params_t. More...

ssp_err_t	SF_CRYPTO_CIPHER_CipherUpdate (sf_crypto_cipher_ctrl_t const p_api_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	SSP Crypto Cipher Framework - Encrypts / Decrypts the input data and writes the cipher-text or plain-text to the output buffer. Can be called multiple times for chunks of data. More...

ssp_err_t	SF_CRYPTO_CIPHER_CipherAadUpdate (sf_crypto_cipher_ctrl_t const p_api_ctrl, sf_crypto_data_handle_t const const p_aad)
	Updates Additional Authenticated Data. This is applicable only to AES GCM. Can be called multiple times for chunks of data. More...

ssp_err_t	SF_CRYPTO_CIPHER_CipherFinal (sf_crypto_cipher_ctrl_t const p_api_ctrl, sf_crypto_data_handle_t const const p_data_in, sf_crypto_data_handle_t *const p_data_out)
	SSP Crypto Cipher Framework - Generates encrypted / decrypted output from all/last input data. This function processes any remaining input data buffered by one or more calls to the cipherUpdate()API as well as input data supplied in the input parameter. This function must be invoked to complete a cipher operation. More...

Detailed Description

RTOS-integrated Crypto Cipher Framework Module.

Macro Definition Documentation

◆ SF_CRYPTO_CIPHER_AES_128_XTS_KEY_SIZE

#define SF_CRYPTO_CIPHER_AES_128_XTS_KEY_SIZE (2 * (AES128_SECRET_KEY_SIZE_BYTES))

Macros for AES operations

◆ SF_CRYPTO_CIPHER_API_VERSION_MAJOR

#define SF_CRYPTO_CIPHER_API_VERSION_MAJOR (1U)

The API version of SSP Crypto CIPHER Framework

◆ SF_CRYPTO_CIPHER_CODE_VERSION_MAJOR

#define SF_CRYPTO_CIPHER_CODE_VERSION_MAJOR (2U)

The API version of SSP Crypto Cipher Framework

◆ SF_CRYPTO_CIPHER_RSA_1024_MODULUS_BITS

#define SF_CRYPTO_CIPHER_RSA_1024_MODULUS_BITS (1024U)

Modulus size of RSA 1024-bit key.

Macros for RSA operations EB = ENCRYPTION_BLOCK PS = Padding String PKCS_1_5 = RSAES-PKCS1-v1_5

◆ SF_CRYPTO_PKCS_1_5_EB_OVERHEAD

#define SF_CRYPTO_PKCS_1_5_EB_OVERHEAD

Value:

(SF_CRYPTO_PKCS_1_5_EB_START_BYTE_LENGTH +  \
                                         SF_CRYPTO_PKCS_1_5_EB_BT_BYTE_LENGTH +     \
                                         SF_CRYPTO_PKCS_1_5_EB_PS_MIN_LENGTH  +     \
                                         SF_CRYPTO_PKCS_1_5_EB_DATA_SEPARATOR_LENGTH)

Overhead for formatting the Encryption Block, in number of bytes

Enumeration Type Documentation

◆ sf_crypto_cipher_state_t

enum sf_crypto_cipher_state_t

States the SSP Crypto Cipher Framework module can go through.

Enumerator
SF_CRYPTO_CIPHER_STATE_CLOSED	The Cipher module is closed.
SF_CRYPTO_CIPHER_STATE_OPENED	The Cipher module is opened.
SF_CRYPTO_CIPHER_STATE_INITIALIZED	The cipher operation is initialized.
SF_CRYPTO_CIPHER_STATE_UPDATED	The cipher operation is updated.
SF_CRYPTO_CIPHER_STATE_FINALIZED	The cipher operation is finalized.

Function Documentation

◆ sf_crypto_cipher_aes_aad_update()

ssp_err_t sf_crypto_cipher_aes_aad_update	(	sf_crypto_cipher_instance_ctrl_t *	p_ctrl,
		sf_crypto_data_handle_t const *const	p_aad
	)

Subroutine to update the AAD for the cipher operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in]	p_aad	Pointer to the input data structure - has the pointer to input AAD and the data length

Return values

SSP_SUCCESS AAD was updated successfully.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

Check if there is data in the aad block buffer. If so first fill it from the input data

Update the number of bytes remaining in the input buffer to be processed.

If data is block length, encrypt it.

Check if the input data is a multiple of block size

Update the number of bytes remaining in the input buffer to be processed.

If any bytes remain that is less than the block size, copy to the partial buffer

Update the size of the data in the partial block

◆ sf_crypto_cipher_aes_decrypt_final()

ssp_err_t sf_crypto_cipher_aes_decrypt_final	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Subroutine to finalize the cipher decrypt operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in,out]	p_data_in	Pointer to the input data structure - has the pointer to input data and the data length
[in,out]	p_data_out	Pointer to the output data structure - has the pointer to output data and the data length.

Return values

SSP_SUCCESS	Cipher operation was finalized successfully.
SSP_ERR_INVALID_ARGUMENT	Input data is invalid.
SSP_ERR_INVALID_SIZE	The out buffer is inadequate to hold the output data.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

Validate the input parameters

Process the input data

If GCM check if there is any partial AAD remaining, if so call to update AAD

If GCM set the tag

For GCM compute and verify the tag - return error to indicate if the data is valid or not.

◆ sf_crypto_cipher_aes_encrypt_final()

ssp_err_t sf_crypto_cipher_aes_encrypt_final	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Subroutine to finalize the cipher encrypt operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in,out]	p_data_in	Pointer to the input data structure - has the pointer to input data and the data length
[in,out]	p_data_out	Pointer to the output data structure - has the pointer to output data and the data length.

Return values

SSP_SUCCESS	Cipher operation was finalized successfully.
SSP_ERR_INVALID_ARGUMENT	Input data is invalid.
SSP_ERR_INVALID_SIZE	The out buffer is inadequate to hold the output data.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

Validate the input parameters

Process the input data

Handle padding for ECB, CBC modes

Add padding and encrypt the last block.

If there is a remaining partial block process it. For GCM zero padding is automatic

Now that the possible AAD update and plain text encryption is done, get the GCM tag

◆ sf_crypto_cipher_aes_final()

ssp_err_t sf_crypto_cipher_aes_final	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Sub-routine for Crypto Cipher Framework to call the appropriate routine for final encryption based on the algorithm for the cipherFinal operation. This function is called by SF_CRYPTO_CIPHER_CipherFinal().

Parameters

[in,out]	p_ctrl	Pointer to the Cipher framework module instance control block.
[in]	p_data_in	Pointer to the input data buffer and the length of the input data.
[in,out]	p_data_out	Pointer to the output data buffer and the buffer length on input. If data is output, the length of the data will be updated.

Return values

SSP_SUCCESS	The cipher update operation was successful.
SSP_ERR_UNSUPPORTED	The module does not support the algorithm bbased on the key type specified by the user.

Returns: See Common Error Codes for other possible return codes.

Validate that there is some input data provided / processed before the finalizing operation Applies to both encrypt and decrypt operations. AES GCM is the only exception.

◆ sf_crypto_cipher_aes_init()

ssp_err_t sf_crypto_cipher_aes_init	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_cipher_op_mode_t	cipher_operation_mode,
		sf_crypto_key_t const *const	p_key,
		sf_crypto_cipher_algorithm_init_params_t *	p_algorithm_specific_params
	)

Subroutine to initialize the AES cipher operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in]	cipher_operation_mode	The cipher operation mode - encrypt / decrypt.
[in]	p_key	Pointer to the key to be used for the cipher operations.
[in]	p_algorithm_specific_params	Pointer to the algorithm specific parameters.

Return values

SSP_SUCCESS	All of the input parameters are validated successfully.
SSP_ERR_INVALID_ARGUMENT	An input for the required cipher operation is invalid.

All buffers within the context buffer are allocated at Open. Now just zeroise their contents.

Copy the init parameters to the context buffer

◆ sf_crypto_cipher_aes_interface_get()

void sf_crypto_cipher_aes_interface_get ( sf_crypto_cipher_instance_ctrl_t *const p_ctrl )

Subroutine to get a pointer to the AES HAL API instance.

Parameters

[in,out] p_ctrl Pointer to a Cipher framework control block, whose p_hal_api is filled with HAL AES interface. This will be NULL, for MCUs /feature/ configuration parameters not supported

Get a Crypto common control block and the HAL instance.

Check the AES key type and size and get an appropriate API instance.

Get the HAL API instance for a selected algorithm type.

◆ sf_crypto_cipher_aes_update()

ssp_err_t sf_crypto_cipher_aes_update	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Subroutine to update the cipher AES operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in,out]	p_data_in	Pointer to the input data structure - has the pointer to input data and the data length
[in,out]	p_data_out	Pointer to the output data structure - has the pointer to output data and the data length.

Return values

SSP_SUCCESS	Cipher operation was updated successfully.
SSP_ERR_INVALID_SIZE	The out buffer is inadequate to hold the output data.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

If GCM check if there is any partial AAD remaining. This is to be processed only if the cipher is in initialized state. Once the update is done AAD calculations should not be done. if so call to update AAD

Set the data out length before starting cipher operation.

Update the number of bytes remaining in the input buffer to be processed.

If data is block length, process it. That is encrypt / decrypt it.

Check if the remaining input data is a multiple of block size

Update the number of bytes written to the output buffer.

Update the number of bytes remaining in the input buffer to be processed.

If any bytes remain that is less than the block size, copy to the partial buffer

Update the size of the data in the partial block

◆ sf_crypto_cipher_aes_validate_aad_update_params_context()

ssp_err_t sf_crypto_cipher_aes_validate_aad_update_params_context ( sf_crypto_cipher_instance_ctrl_t *const p_ctrl )

Subroutine to validate the context buffer parameters for the cipherAadUpdate operation.

Parameters

[in,out] p_ctrl Pointer to the cipher framework module control block used in the open() call.

Return values

SSP_SUCCESS	Parameters were validated successfully.
SSP_ERR_ASSERTION	At least one of the buffer is set to NULL.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

◆ SF_CRYPTO_CIPHER_CipherAadUpdate()

ssp_err_t SF_CRYPTO_CIPHER_CipherAadUpdate	(	sf_crypto_cipher_ctrl_t *const	p_api_ctrl,
		sf_crypto_data_handle_t const *const	p_aad
	)

Updates Additional Authenticated Data. This is applicable only to AES GCM. Can be called multiple times for chunks of data.

Return values

SSP_SUCCESS	The function updated the AAD successfully.
SSP_ERR_ASSERTION	NULL is passed through an argument.
SSP_ERR_NOT_OPEN	The module has yet been opened. Call Open API first.
SSP_ERR_UNSUPPORTED	Key types / algorithms are not supported for the MCU part.
SSP_ERR_INVALID_CALL	Function call was made if the module state had not yet transitioned to SF_CRYPTO_CIPHER_STATE_INITIALIZED.

Returns: See Common Error Codes for other possible return codes.

Note: 1. This is a blocking call.; 2. This function has to be called before any call to cipherUpdate / cipherFinal is made.; 3. The data buffer must be WORD aligned.

do nothing - similar to the cipherUpdate API

Get a Crypto Framework common control block and the interface.

Check if the Crypto Cipher Framework is in the correct state to execute this operation. If module is not opened or initialized, return an error.

Acquire the lock from the common module to access the Crypto HAL driver.

AAD is optional so no need to track if it is updated.

Unlock the module.

if update processing has succeeded return the error from unlock.

◆ SF_CRYPTO_CIPHER_CipherFinal()

ssp_err_t SF_CRYPTO_CIPHER_CipherFinal	(	sf_crypto_cipher_ctrl_t *const	p_api_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

SSP Crypto Cipher Framework - Generates encrypted / decrypted output from all/last input data. This function processes any remaining input data buffered by one or more calls to the cipherUpdate()API as well as input data supplied in the input parameter. This function must be invoked to complete a cipher operation.

Return values

SSP_SUCCESS	The module updated a message Digest successfully.
SSP_ERR_ASSERTION	NULL is passed through an argument.
SSP_ERR_NOT_OPEN	The module has yet been opened. Call Open API first.
SSP_ERR_UNSUPPORTED	Key types / algorithms are not supported for the MCU part.
SSP_ERR_INVALID_CALL	Function call was made if the module state had not yet transitioned to SF_CRYPTO_CIPHER_STATE_INITIALIZED or SF_CRYPTO_CIPHER_STATE_UPDATED.

Returns: See Common Error Codes for other possible return codes.

Note: 1. This is a blocking call.; 2. On encryption and decryption operations, block alignment considerations may require that the number of bytes written into output buffer be larger or smaller than input data length or even 0.; 3. The output data area must not partially overlap the input data area such that the input data is modified before it is used else incorrect output may result.; 4. Except for GCM, if the length of input data is 0 and no input was provided through update, an error is returned.; 5. On decryption operations the padding bytes are not written to p_data_out.p_data.; 6. The input and output buffers must be WORD aligned.

Get a Crypto Framework common control block and the interface.

Check if the Crypto Cipher Framework is in the correct state to execute this operation. If module is not opened or initialized, return an error.

Acquire the lock from the common module to access to Crypto HAL driver.

Mark the module status as 'Finalized'.

Unlock the module.

if final processing has succeeded return the error from unlock.

◆ SF_CRYPTO_CIPHER_CipherInit()

ssp_err_t SF_CRYPTO_CIPHER_CipherInit	(	sf_crypto_cipher_ctrl_t *const	p_api_ctrl,
		sf_crypto_cipher_op_mode_t	cipher_operation_mode,
		sf_crypto_key_t const *const	p_key,
		sf_crypto_cipher_algorithm_init_params_t *const	p_algorithm_specific_params
	)

SSP Crypto Framework Cipher Init operation. The input parameters initialize the cipher operation. Some of the parameters are algorithm specific. The input parameters are validated and then copied into the context buffer. Refer to sf_crypto_cipher_aes_init_params_t or sf_crypto_cipher_rsa_init_params_t.

Return values

SSP_SUCCESS	The module is initialized for cipher operation successfully.
SSP_ERR_ASSERTION	NULL is passed through an argument.
SSP_ERR_NOT_OPEN	The module has yet been opened. Call Open API first.
SSP_ERR_INVALID_ARGUMENT	One of the input parameters is invalid.
SSP_ERR_UNSUPPORTED	The module does not support the key type specified by user.

Returns: See Common Error Codes for other possible return codes.

Validate cipher operation mode

Check if the module can transition to the initialized state.

Note: sf_crypto.lock() is not called because the HAL driver does not access HW during init. If HW will be accessed through the HAL driver, lock should be acquired.

Do algorithm specific init

Mark the module status as 'Initialized'.

◆ SF_CRYPTO_CIPHER_CipherUpdate()

ssp_err_t SF_CRYPTO_CIPHER_CipherUpdate	(	sf_crypto_cipher_ctrl_t *const	p_api_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

SSP Crypto Cipher Framework - Encrypts / Decrypts the input data and writes the cipher-text or plain-text to the output buffer. Can be called multiple times for chunks of data.

Return values

SSP_SUCCESS	The function updated a cipher operation successfully.
SSP_ERR_ASSERTION	NULL is passed through an argument.
SSP_ERR_NOT_OPEN	The module has yet been opened. Call Open API first.
SSP_ERR_UNSUPPORTED	Key types / algorithms are not supported for the MCU part.
SSP_ERR_INVALID_CALL	Function call was made if the module state had not yet transitioned to SF_CRYPTO_CIPHER_STATE_INITIALIZED.

Returns: See Common Error Codes for other possible return codes.

Note: 1. This is a blocking call.; 2. The input and output buffers have to be WORD aligned.; 3. On encryption and decryption operations, block alignment considerations may require that the number of bytes written into output buffer be larger or smaller than input data length or even 0.; 4. The output data area must not partially overlap the input data area such that the input data is modified before it is used else incorrect output may result.; 5. If the length of input data is 0 this method does nothing.; 6. For all Cipher operations cipherFinal() must be called to finalize the operation.; 7. For RSA Operations, no data is output unless cipherFinal() is called.

If input data length is 0 - do nothing return success.

The status will be set to 'updated' only when data is processed.

Get a Crypto Framework common control block and the interface.

Check if the Crypto Cipher Framework is in the correct state to transition to do the update operation. If module is not opened or initialized, return an error.

Acquire the lock from the common module to access the Crypto HAL driver.

If update processing has succeeded return the error from unlock.

◆ SF_CRYPTO_CIPHER_Close()

ssp_err_t SF_CRYPTO_CIPHER_Close ( sf_crypto_cipher_ctrl_t *const p_api_ctrl )

SSP Crypto Cipher Framework Close operation.

Return values

SSP_SUCCESS	The module was successfully closed.
SSP_ERR_ASSERTION	One or more input parameters maybe NULL.
SSP_ERR_NOT_OPEN	The module has yet been opened. Call Open API first.

Returns: See Common Error Codes for other possible return codes.

Get a Crypto common control block and the interface.

Check if the Crypto Framework Cipher module has been opened. If not yet opened, return an error.

Note: sf_crypto.lock() is not called because the HAL driver does not access HW during close. If HW will be accessed through the HAL driver, lock should be acquired.

Free the memory allocated for this instance and close the HAL driver.

◆ sf_crypto_cipher_deinitialize_aes_instance()

ssp_err_t sf_crypto_cipher_deinitialize_aes_instance ( sf_crypto_cipher_instance_ctrl_t * p_ctrl )

closes the underlying HAL instance and releases the memory for the instance.

Parameters

[in,out] p_ctrl Pointer to Crypto Cipher Framework instance control block structure.

Return values

SSP_SUCCESS	The module instantiated successfully.
SSP_ERR_TIMEOUT	Was unable to allocate the memory within the specified time to wait.
SP_ERR_OUT_OF_MEMORY	Requested size is zero or larger than the pool.
SSP_ERR_INTERNAL	RTOS service returned a unexpected error.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes. This function calls: sf_crypto_cipher_instance_memory_allocate sf_crypto_cipher_hal_open

◆ sf_crypto_cipher_deinitialize_rsa_instance()

ssp_err_t sf_crypto_cipher_deinitialize_rsa_instance ( sf_crypto_cipher_instance_ctrl_t * p_ctrl )

closes the underlying HAL instance and releases the memory for the instance.

Parameters

[in,out] p_ctrl Pointer to Crypto Cipher Framework instance control block structure.

Return values

SSP_SUCCESS	The module instantiated successfully.
SSP_ERR_TIMEOUT	Was unable to allocate the memory within the specified time to wait.
SP_ERR_OUT_OF_MEMORY	Requested size is zero or larger than the pool.
SSP_ERR_INTERNAL	RTOS service returned a unexpected error.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes. This function calls: sf_crypto_cipher_instance_memory_allocate sf_crypto_cipher_hal_open

First close the Framework TRNG instance.

Then close the HAL RSA instance.

◆ sf_crypto_cipher_initialize_aes_instance()

ssp_err_t sf_crypto_cipher_initialize_aes_instance	(	sf_crypto_cipher_instance_ctrl_t *	p_ctrl,
		sf_crypto_cipher_cfg_t const *const	p_cfg
	)

Allocates memory for the instance and opens the underlying HAL instance.

Parameters

[in,out]	p_ctrl	Pointer to Crypto Cipher Framework instance control block structure.
[in]	p_cfg	Pointer to the configuration structure for Cipher module .

Return values

SSP_SUCCESS	The module instantiated successfully.
SSP_ERR_TIMEOUT	Was unable to allocate the memory within the specified time to wait.
SP_ERR_OUT_OF_MEMORY	Requested size is zero or larger than the pool.
SSP_ERR_INTERNAL	RTOS service returned a unexpected error.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes. This function calls: sf_crypto_cipher_instance_memory_allocate sf_crypto_cipher_hal_open

◆ sf_crypto_cipher_initialize_rsa_instance()

ssp_err_t sf_crypto_cipher_initialize_rsa_instance	(	sf_crypto_cipher_instance_ctrl_t *	p_ctrl,
		sf_crypto_cipher_cfg_t const *const	p_cfg
	)

Allocates memory for the instance and opens the underlying HAL instance.

Parameters

[in,out]	p_ctrl	Pointer to Crypto Cipher Framework instance control block structure.
[in]	p_cfg	Pointer to the configuration structure for Cipher module .

Return values

SSP_SUCCESS	The module instantiated successfully.
SSP_ERR_TIMEOUT	Was unable to allocate the memory within the specified time to wait.
SP_ERR_OUT_OF_MEMORY	Requested size is zero or larger than the pool.
SSP_ERR_INTERNAL	RTOS service returned a unexpected error.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes. This function calls: sf_crypto_cipher_instance_memory_allocate sf_crypto_cipher_hal_open

◆ sf_crypto_cipher_is_key_type_aes()

bool sf_crypto_cipher_is_key_type_aes ( sf_crypto_key_type_t key_type )

Subroutine to check if the key type enum provided is a valid AES key type for cipher operation.

Parameters

[in] key_type The key type to be tested.

Return values

true	The key is a valid AES key type.
false	The key is NOT a valid AES key type.

Check the key type and and determine the algorithm.

◆ sf_crypto_cipher_is_key_type_rsa()

bool sf_crypto_cipher_is_key_type_rsa ( sf_crypto_key_type_t key_type )

Subroutine to check if key type is RSA.

Parameters

[in] key_type Key type enum.

Return values

true	Key type is RSA plain text (standard or CRT)/ wrapped.
false	Key type is not RSA.

Check the key type is valid for RSA operations.

◆ SF_CRYPTO_CIPHER_Open()

ssp_err_t SF_CRYPTO_CIPHER_Open	(	sf_crypto_cipher_ctrl_t *const	p_api_ctrl,
		sf_crypto_cipher_cfg_t const *const	p_cfg
	)

SSP Crypto Cipher Framework Open operation.

The SF_CRYTO_CIPHER_Open function: Allocates memory required for the cipher operations based on the configuration parameters. Acquires lock for the shared crypto resources. Gets the interface to the HAL driver based on the config parameters. Calls the .open function of the HAL API. On successful open, the module status is updated as such. The shared resources are unlocked before exit.

Return values

SSP_SUCCESS	The module was successfully opened.
SSP_ERR_ASSERTION	One or more input parameters maybe NULL.
SSP_ERR_INVALID_ARGUMENT	An invalid argument is used.
SSP_ERR_CRYPTO_COMMON_NOT_OPENED	Crypto Framework Common Module has yet been opened.
SSP_ERR_ALREADY_OPEN	The module has been already opened.
SSP_ERR_UNSUPPORTED	The module does not support the key type specified by user.
SSP_ERR_INTERNAL	An internal ThreadX error has occurred. This is typically a failure to create/use a mutex or to create an internal thread.

Returns: See Common Error Codes for other possible return codes.

Get a Crypto common control block and the interface.

Get the pointers to TRNG control and API structures from the instance pointed to by the config structure.

Check if the Crypto Framework has been opened. If not yet opened, return an error.

Check if the Cipher module has been already opened. If opened, return an error.

Validate the cfg parameters

Fill the control block with the validated cfg parameters

Determine and fill the algorithm type in the control block.

Note: sf_crypto.lock() is not called because the HAL driver does not access HW during open. The HAL interfaceGet API is also called which does not access HW either. If HW will be accessed through the HAL driver, lock should be acquired.

Allocate memory resources used by this framework instance and open HAL driver

◆ SF_CRYPTO_CIPHER_RSA_EB_SIZE_BYTES()

__STATIC_INLINE uint32_t SF_CRYPTO_CIPHER_RSA_EB_SIZE_BYTES ( uint32_t key_size_bits )

Routine to calculate and return the Encryption block size based on the key size.

Private Functions.

Parameters

[in] key_size_bits key size in bits.

◆ sf_crypto_cipher_rsa_final()

ssp_err_t sf_crypto_cipher_rsa_final	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Routine to process the final encryption / decryption operation for RSA. This function is called by SF_CRYPTO_CIPHER_CipherFinal().

Return values

SSP_SUCCESS	The cipher update operation was successful.
SSP_ERR_UNSUPPORTED	The module does not support the algorithm bbased on the key type specified by the user.

Returns: See Common Error Codes for other possible return codes.

Clean up the data in the context buffer before exiting.

◆ sf_crypto_cipher_rsa_init()

ssp_err_t sf_crypto_cipher_rsa_init	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_cipher_op_mode_t	cipher_operation_mode,
		sf_crypto_key_t const *const	p_key,
		sf_crypto_cipher_algorithm_init_params_t *	p_algorithm_specific_params
	)

Routine to handle the cipherInit RSA operation.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in]	cipher_operation_mode	The cipher operation mode - encrypt / decrypt.
[in]	p_key	Pointer to the key to be used for the cipher operations.
[in]	p_algorithm_specific_params	Pointer to the algorithm specific parameters.

Return values

SSP_SUCCESS	Cipher operation was updated successfully.
SSP_ERR_INVALID_SIZE	The out buffer is inadequate to hold the output data.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

All buffers within the context buffer are allocated at Open. Now just zeroise their contents.

Copy data into the control block / context buffer.

◆ sf_crypto_cipher_rsa_interface_get()

void sf_crypto_cipher_rsa_interface_get ( sf_crypto_cipher_instance_ctrl_t *const p_ctrl )

Subroutine to get a RSA HAL API instance. This function is called by sf_crypto_cipher_open_rsa().

Parameters

[in,out] p_ctrl Pointer to a Key framework control block, whose p_hal_api filled with HAL RSA interface. This indicates NULL, for not supported MCUs

Get a Crypto common control block and the HAL instance.

Check the RSA key type.

Get the HAL API instance for a selected algorithm type.

◆ SF_CRYPTO_CIPHER_RSA_PKCS_1_5_EB_DATA_SIZE_BYTES()

__STATIC_INLINE uint32_t SF_CRYPTO_CIPHER_RSA_PKCS_1_5_EB_DATA_SIZE_BYTES ( uint32_t key_size_bits )

Routine to calculate and return the Encryption block size based on the key size.

Parameters

[in] key_size_bits key size in bits.

◆ sf_crypto_cipher_rsa_update()

ssp_err_t sf_crypto_cipher_rsa_update	(	sf_crypto_cipher_instance_ctrl_t *const	p_ctrl,
		sf_crypto_data_handle_t const *const	p_data_in,
		sf_crypto_data_handle_t *const	p_data_out
	)

Subroutine to update the cipher RSA operation. This algorithm is only suitable for messages of limited length. The total number of input bytes processed during encryption may not be more than k-11, where k is the RSA key's modulus size in bytes. The encryption block(EB) during encryption with a Public key is built as follows: EB = 00 || 02 || PS || 00 || M :: M (input bytes) is the plaintext message :: PS is an octet string of length k-3-||M|| of pseudo random nonzero octets. The length of PS must be at least 8 octets. :: k is the RSA modulus size.

Parameters

[in,out]	p_ctrl	Pointer to the cipher framework module control block used in the open() call.
[in]	p_data_in	Pointer to the input data structure - has the pointer to input data and the data length
[in,out]	p_data_out	Pointer to the output data structure - has the pointer to output data and the buffer length on input. If data is filled the length is updated on output.

Return values

SSP_SUCCESS	Cipher operation was updated successfully.
SSP_ERR_UNSUPPORTED	Unknown cipher operation mode was passed in.
SSP_ERR_INVALID_SIZE	The out buffer is inadequate to hold the output data.

Returns: See Common Error Codes or HAL driver for other possible return codes or causes.

input parameters validation - done at the entry nothing to do here no output on update - so no checks for output buffer / length collect input up to the block size for encryption when no padding is selected. collect data up to block size -11 for encryption when padding is selected collect input up to the block size for decryption if it exceeds the above return error

Copy the data into the partial block

◆ SF_CRYPTO_CIPHER_VersionGet()

ssp_err_t SF_CRYPTO_CIPHER_VersionGet ( ssp_version_t *const p_version )

Gets driver version based on compile time macros.

Return values

SSP_SUCCESS	The version is returned successfully.
SSP_ERR_ASSERTION	The parameter p_version is NULL.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SF_CRYPTO_CIPHER_AES_128_XTS_KEY_SIZE

◆ SF_CRYPTO_CIPHER_API_VERSION_MAJOR

◆ SF_CRYPTO_CIPHER_CODE_VERSION_MAJOR

◆ SF_CRYPTO_CIPHER_RSA_1024_MODULUS_BITS

◆ SF_CRYPTO_PKCS_1_5_EB_OVERHEAD

Enumeration Type Documentation

◆ sf_crypto_cipher_state_t

Function Documentation

◆ sf_crypto_cipher_aes_aad_update()

◆ sf_crypto_cipher_aes_decrypt_final()

◆ sf_crypto_cipher_aes_encrypt_final()

◆ sf_crypto_cipher_aes_final()

◆ sf_crypto_cipher_aes_init()

◆ sf_crypto_cipher_aes_interface_get()

◆ sf_crypto_cipher_aes_update()

◆ sf_crypto_cipher_aes_validate_aad_update_params_context()

◆ SF_CRYPTO_CIPHER_CipherAadUpdate()

◆ SF_CRYPTO_CIPHER_CipherFinal()

◆ SF_CRYPTO_CIPHER_CipherInit()

◆ SF_CRYPTO_CIPHER_CipherUpdate()

◆ SF_CRYPTO_CIPHER_Close()

◆ sf_crypto_cipher_deinitialize_aes_instance()

◆ sf_crypto_cipher_deinitialize_rsa_instance()

◆ sf_crypto_cipher_initialize_aes_instance()

◆ sf_crypto_cipher_initialize_rsa_instance()

◆ sf_crypto_cipher_is_key_type_aes()

◆ sf_crypto_cipher_is_key_type_rsa()

◆ SF_CRYPTO_CIPHER_Open()

◆ SF_CRYPTO_CIPHER_RSA_EB_SIZE_BYTES()

◆ sf_crypto_cipher_rsa_final()

◆ sf_crypto_cipher_rsa_init()

◆ sf_crypto_cipher_rsa_interface_get()

◆ SF_CRYPTO_CIPHER_RSA_PKCS_1_5_EB_DATA_SIZE_BYTES()

◆ sf_crypto_cipher_rsa_update()

◆ SF_CRYPTO_CIPHER_VersionGet()