Crypto Framework

Table of Contents

• Crypto Framework Introduction
  • Crypto Framework Module Features
• Crypto Framework Module APIs Overview
• Crypto Framework Module Operational Overview
  • SF CRYPTO Framework Module Overview Description
  • SF CRYPTO TRNG Framework Module Overview Description
  • SF CRYPTO HASH Framework Module Overview Description
  • SF CRYPTO KEY Framework Module Overview Description
  • SF Crypto Signature Framework Module Overview Description
  • SF Crypto Cipher Framework Module Overview Description
  • SF Crypto Key Installation Framework Module Overview Description
• Including the Crypto Framework Module in an Application
• Configuring the Crypto Framework Module
• Using the Crypto Framework Module in an Application

Crypto Framework Introduction

The Crypto Framework layer is composed of multiple Crypto modules providing varied cryptographic services. It includes:

SF_CRYPTO for resource synchronization between the crypto modules.

SF_CRYPTO_TRNG for true random number generation.

SF_CRYPTO_HASH for message digest generation. Provides support for MD5, SHA1, SHA 224, SHA 256 algorithms.

SF_CRYPTO_KEY for Key Generation services. Provides support for AES, ECC and RSA keys.

SF_CRYPTO_CIPHER for encryption and decryption services. Provides support for AES and RSA algorithms.

SF_CRYPTO_SIGNATURE for RSA signature generation and verification services.

SF_CRYPTO_KEY_INSTALLATION for key installation services. Provides support for AES, ECC and RSA keys.

Crypto Framework Module Features

The terms "key wrapping" and "key installation" in the context of SSP are defined as follows:

Key Wrapping: The APIs to generate symmetric keys or asymmetric key pairs on the Synergy platform where the private / secret key is a wrapped key (encrypted key).

Key Installation: User generated private /secret keys on a PC (system outside of the Synergy platform) will be installed (no storage) on the Synergy platform and the wrapped private /secret key returned to the user.

Wrapped keys provide the following advantages:

• The wrapped key can only be used on the Synergy platform (MCU) on which it was generated.
• It cannot be moved to another Synergy platform (MCU).
• Original Key cannot be recovered from the wrapped key.

Crypto Framework Module Block Diagram

Crypto Framework Module APIs Overview

The Crypto Framework Module defines APIs for a variety of cryptographic services. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Crypto Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto0.p_api->open(g_sf_crypto0.p_ctrl, g_sf_crypto0.p_cfg); This function is used to open the crypto framework module and the r_sce HAL module.
close	g_sf_crypto0.p_api->close(g_sf_crypto0.p_ctrl); This function is used to close the crypto framework module and the r_sce HAL module.
lock	g_sf_crypto0.p_api->lock(g_sf_crypto0.p_ctrl); This function locks shared resources for cryptography operations.
unlock	g_sf_crypto0.p_api->unlock(g_sf_crypto0.p_ctrl); Unlock shared resources for cryptography operations.
getStatus	g_sf_crypto0.p_api->statusGet(g_sf_crypto0.p_ctrl, &p_status); This function gets the status of the Crypto Framework common module.
versionGet	g_sf_crypto0.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto HASH Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_hash0.p_api->open(g_sf_crypto_hash0.p_ctrl, g_sf_crypto_hash0.p_cfg); This function is used to open the crypto hash framework module.
close	g_sf_crypto_hash0.p_api->close(g_sf_crypto_hash0.p_ctrl); This function is used to close the crypto hash framework module.
hashInit	g_sf_crypto_hash0.p_api->hashInit(g_sf_crypto_hash0.p_ctrl); This function initializes the calculation of the hash function. It has to be invoked first and only once, at the beginning of each new calculation.
hashUpdate	g_sf_crypto_hash0.p_api->hashUpdate(g_sf_crypto_hash0.p_ctrl, &p_data_in); This function calculates the hash on the data pointed to by the p_data_in pointer.
hashFinal	g_sf_crypto_hash0.p_api->hashFinal(g_sf_crypto_hash0.p_ctrl, &p_data_in, &p_size); This function finalizes the hash operation on the data pointed to by the p_data_in pointer and stores the output size in the 32-bit word defined by the p_size pointer.
versionGet	g_sf_crypto_hash0.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto TRNG Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_trng0.p_api->open( g_sf_crypto_trng0.p_ctrl, g_sf_crypto_trng0.p_cfg); This function is used to open the Crypto TRNG framework module.
close	g_sf_crypto_trng0.p_api->close( g_sf_crypto_trng0.p_ctrl); This function is used to close the Crypto TRNG framework module.
randomNumberGenerate	g_sf_crypto_trng0.p_api-> randomNumberGenerate (&p_buffer); This function generates the random number and stores it in memory starting at the address defined by the p_buffer pointer.
versionGet	g_sf_crypto_trng0.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto Key Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_key0.p_api->open( g_sf_crypto_key0.p_ctrl, g_sf_crypto_key0.p_cfg); This function is used to open the crypto key framework module.
keyGenerate	g_sf_crypto_key0.p_api->keyGenerate( g_sf_crypto_key0.p_ctrl, &p_secret_key, &p_public_key); This function is used to generate a key or key pair and store it at the p_secret_key and p_public_key pointers.
EcdhSharedSecretCompute	g_sf_crypto_key0.p_api->EcdhSharedSecretCompute( g_sf_crypto_key0.p_ctrl, &p_local_secret_key, &p_remote_public_key, &p_shared_secret); This function is used to perform ECC scalar multiplication
close	g_sf_crypto_key0.p_api->close( g_sf_crypto_key0.p_ctrl); This function is used to close the crypto key framework module and the r_sce HAL module.
versionGet	g_sf_crypto_key0.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto Key Installation Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_key_installation.p_api->open( g_sf_crypto_key_installation.p_ctrl, g_sf_crypto_key_installation.p_cfg); This function is used to open the crypto key initialization framework module.
keyInstall	g_sf_crypto_key_installation.p_api->keyInstall( g_sf_crypto_key_installation.p_ctrl, p_user_key_input, p_install_key_input, p_key_data_out ); This function is used to install a key using the p_user_key_input, p_install_key_input and p_key_data_out pointers.
close	g_sf_crypto_key_installation.p_api->close( g_sf_crypto_key_installation.p_ctrl); This function is used to close the crypto key installation framework module.
versionGet	g_sf_crypto_key_installation.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto Cipher Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_cipher.p_api->open( g_sf_crypto_cipher.p_ctrl, g_sf_crypto_cipher.p_cfg); This function is used to open the crypto cipher framework module.
cipherInit	g_sf_crypto_cipher.p_api->cipherInit( g_sf_crypto_cipher.p_ctrl, mode, p_key, p_params); This function is used to initialize the crypto cipher framework module.
signUpdate	g_sf_crypto_cipher.p_api->cipherUpdate( g_sf_crypto_cipher.p_ctrl, p_datain, p_dataout); This function performs the cipher encrypt or decrypt operation. It can be called multiple times on additional blocks of data. Result is placed in p_dataout.
cipherFinal	g_sf_crypto_cipher.p_api->cipherFinal( g_sf_crypto_signature.p_ctrl, p_datain, p_dataout); This function performs the final encrypt or decrypt operation. Result is placed in p_dataout.
cipherAadUpdate	g_sf_crypto_cipher.p_api->cipherAadUpdate( g_sf_crypto_cipher.p_ctrl, p_aad); This function updates AAD (Additional Authenticated Data) for AES GCM operation using the p_aad pointer to the AAD data and length. It can be called multiple times on additional blocks of data.
close	g_sf_crypto_cipher.p_api->close( g_sf_crypto_cipher.p_ctrl); This function is used to close the crypto signature framework module.
versionGet	g_sf_crypto_cipher.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Crypto Signature Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_crypto_signature.p_api->open( g_sf_crypto_signature.p_ctrl, g_sf_crypto_signature.p_cfg); This function is used to open the crypto signature framework module.
contextInit	g_sf_crypto_signature.p_api->contextInit( g_sf_crypto_signature.p_ctrl, mode, p_params, p_key); This function is used to initialize the crypto signature framework module.
signUpdate	g_sf_crypto_signature.p_api->signUpdate( g_sf_crypto_signature.p_ctrl, p_message); This function performs the signature update operation. It can be called multiple times to accumulate the message to be signed.
verifyUpdate	g_sf_crypto_signature.p_api->verifyUpdate( g_sf_crypto_signature.p_ctrl, p_message); This function performs the signature verification update operation. It can be called multiple times to accumulate the message whose signature is to be verified.
signFinal	g_sf_crypto_signature.p_api->signFinal( g_sf_crypto_signature.p_ctrl, p_message, p_dest); This function generates the signature and writes it to the destination.
verifyFinal	g_sf_crypto_signature.p_api->verifyFinal( g_sf_crypto_signature.p_ctrl, p_signature, p_message); This function performs the signature verify operation.
close	g_sf_crypto_signature.p_api->close( g_sf_crypto_signature.p_ctrl); This function is used to close the crypto signature framework module.
versionGet	g_sf_crypto_signature.p_api->versionGet(&version); This function retrieves the API version using the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

 The Framework APIs return common SSP error codes and in addition may return error codes from low level modules. Crypto Framework specific error codes can be found in the API Reference section for the specific function.

Crypto Framework Module Operational Overview

The following notes apply to SF_CRYPTO, SF_CRYPTO_TRNG, SF_CRYPTO_HASH, SF_CRYPTO_KEY, SF_CRYPTO_KEY_INSTALLATION, SF_CRYPTO_CIPHER and SF_CRYPTO_SIGNATURE modules.

Endianness configuration parameter

• In the Synergy Configurator (if only the Crypto HAL drivers are selected without the Crypto Framework modules), endianness is a configurable parameter and set to big endian by default. This is the mode that was supported in previous releases.
• In the Synergy Configurator, if Crypto Framework modules are selected (the respective HAL component is included automatically), the endianness flag is locked to the little endian mode where only the byte array format is supported.
• The Crypto Framework Layer APIs support only byte arrays for input and output data.
• The Crypto HAL APIs support WORD / 32-bit (uint32_t) arrays for input and output data.
• Users with data in byte array format should use the Crypto Framework modules.
• For any existing projects using the Crypto HAL API without the respective Framework API, Big Endian data may have been used and in that case, it needs to be converted to little Endian to use framework API or continue to use the existing HAL API directly.
• If using the HAL APIs directly, the user needs to make sure that the data cast as (uint32_t) matches the endianness of the HAL module used.

Alignment for data buffers

• All data buffers allocated to be passed in as input buffers must be aligned on WORD boundary.

Blocking calls

• All Crypto Framework APIs are blocking calls.

SF CRYPTO Framework Services

• The SF CRYPTO Framework modules include:
  • SF_CRYPTO for HW initialization and resource synchronization between the crypto modules.
  • SF_CRYPTO_TRNG for true random number generation.
  • SF_CRYPTO_HASH for message digest generation. Provides the ability to process data in chunks before finalizing the hash operation.
  • SF_CRYPTO_KEY for RSA, AES, ECC. Provides the option to generate wrapped keys in addition to plain text keys.
  • SF_CRYPTO_KEY_INSTALLATION provides key installation services for RSA, AES and ECC keys.
  • SF_CRYPTO_CIPHER provides encryption and decryption services for AES and RSA keys.
  • SF_CRYPTO_SIGNATURE provides RSA signature generation and verification services.

VersionGet API

This API can be called at any time, that is, even before a module is opened.

SF CRYPTO Framework Module Overview Description

The SF CRYPTO Framework provides a high-level API and is implemented on sf_crypto.  The SF CRYPTO Framework provides a foundation for the Framework Crypto services through the Secure Cryptographic Engine (SCE) HAL module. 

SF CRYPTO Framework Module Features

• The SF CRYPTO Framework opens/ initializes the underlying HW Secure Crypto Engine.
• Provides services for access to shared resources for other Crypto Framework modules SF_CRYPTO_TRNG, SF_CRYPTO_HASH, SF_CRYPTO_KEY, SF_CRYPTO_CIPHER, SF_CRYPTO_SIGNATURE and SF_CRYPTO_KEY_INSTALLATION.

SF CRYPTO Framework Module Operational Notes

• sf_crypto_api_t::open API is called during initialization because the "Auto Initialization" configuration option is enabled by default.
• sf_crypto_api_t::lock API and sf_crypto_api_t::unlock API are for the SF_CRYPTO_XXX modules to to be used.

However, if the application is making a direct call to HAL APIs, use sf_crypto_api_t::lock API just before making the call to HAL module.

• Use sf_crypto_api_t::unlock API just after returning from the call to HAL module.
• sf_crypto_api_t::statusGet API requires the control block / p_ctrl as input parameter. Hence it should be called only after the open API of SF_CRYPTO module is called.

Configuration Settings for the SF CRYPTO Framework Module

Configuration parameter	Description
uint32_t                     wait_option	Wait option for RTOS service calls Defines how the service behaves if there is not enough memory available. The wait options are defined as follows: TX_NO_WAIT (0x00000000) T X_WAIT_FOREVER (0xFFFFFFFF) timeout value (0x00000001 through 0xFFFFFFFE) Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from initialization. Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until enough memory is available. Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for the memory. Default set through ISDE isTX_WAIT_FOREVER.
crypto_instance_t     * p_lower_lvl_crypto	Pointer to a low-level Crypto engine HAL driver instance. Configured by Synergy Configurator.
void const                  * p_extend	Extension parameter for hardware specific settings. Configured by Synergy Configurator.
void const                  * p_context	Placeholder for user data. For future expansion.
void                            * p_memory_pool	Byte pool address. Configured by Synergy Configurator.
uint32_t                      memory_pool_size	Byte pool size. Default set by ISDE is 128 bytes. Caller to allocate pool based on the number of SF_CRYPTO_XXX module instances created. Recommended sizes: In addition to the default byte pool: Note An additional 12 bytes per instance is needed for RTOS housekeeping. 24 + 12 bytes per instance of SF_CRYPTO_KEY module if RSA Key is required. 264 +12bytes per instance of SF_CRYPTO_KEY module if AES Key is required. SF_CRYPTO_KEY module if AES Key is required. 112 +12 bytes per instance of SF_CRYPTO_HASH module. 1200 bytes per instance of SF_CRYPTO_CIPHER module for RSA algorithm is required. 600 bytes per instance of SF_CRYPTO_CIPHER module for AES algorithm is required. 1450 bytes per instance of SF_CRYPTO_SIGNATURE module.
sf_crypto_close_option_t    close_option	Close option Selects how the SCE module can be closed. SF_CRYPTO_CLOSE_OPTION_DEFAULT -  Close the module only if none of the other SF_CRYPTO_XXX modules are opened. Note This is the default setting. SF_CRYPTO_CLOSE_OPTION_FORCE_CLOSE   - Close the module regardless of SF_CRYPTO_XXX modules status. With either option, It is the responsibility of the caller to ensure that the SF CRYPTO module is not closed when any of the other Crypto Framework modules are open.

SF CRYPTO Framework Module Limitations

It is the responsibility of the caller to ensure that the SF CRYPTO module is not closed when any of the other Crypto Framework modules are open.

Using the SF CRYPTO Framework Module in an Application

The typical steps in using the SF CRYPTO Framework module in an application are:

To use the SF CRYPTO module.

• Ensure that the configuration parameters (given in the previous table) are set as per the needs of the application.
• Use the sf_crypto_api_t::open API to Initialize the SF_CRYPTO and the SCE HAL module (R_SCE) through the SCE common driver. This is done by Synergy Configurator when the Auto Initialize setting is at default.
• The little endian mode is set by default.  It is locked and not configurable.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_api_t::close API to close the Crypto Framework services and the HW SCE.

SF CRYPTO TRNG Framework Module Overview Description

The SF CRYPTO TRNG Framework provides a high-level API and is implemented on sf_crypto_trng.  The SF CRYPTO TRNG Framework provides True Random Number Generation services through the Secure Cryptographic Engine (SCE) HAL module. 

SF CRYPTO TRNG Framework Module Features

• The SF CRYPTO TRNG Framework module uses the TRNG HAL interfaces to the underlying Secure Crypto Engine.
• Access to shared resources through SF CRYPTO Framework module.

Configuration Settings for the SF TRNG CRYPTO Framework Module

Configuration Parameter	Description
sf_crypto_instance_t     * p_lower_lvl_common;	Pointer to a low-level Crypto engine HAL driver instance. Configured by Synergy Configurator.
trng_instance_t              * p_lower_lvl_instance;	Pointer to a TRNG HAL driver instance. Configured by Synergy Configurator.
void                                   * p_extend;	Extension parameter for hardware specific settings. For future use.

The configuration is set through the ISDE for the TRNG HAL driver:

Configuration Parameter for the TRNG HAL Module on r_sce_trng

Configuration parameter	Description
uint32_t                             num_attempts	Number of attempts within which a true random number is to be generated. Set to 2 by default.

SF CRYPTO TRNG Framework Module Limitations

None.

SF CRYPTO HASH Framework Module Overview Description

The SF CRYPTO HASH Framework provides a high-level API and is implemented on sf_crypto_hash.  The SF CRYPTO HASH Framework provides hash/message digest services through the Secure Cryptographic Engine (SCE) HAL module. 

The hash functions supported are MD5, SHA-1, SHA-224 and SHA-256.

From FIPS Secure Hash Standard:

All of the algorithms are iterative, one-way hash functions that can process a message to produce a condensed representation called a message digest. These algorithms enable the determination of a message's integrity: any change to the message will, with a very high probability, result in a different message digest. This property is useful in the generation and verification of digital signatures and message authentication codes, and in the generation of random numbers or bits.

For the supported hash functions, the message size should be < 2⁶⁴ bits.

The message digest sizes are as follows:

MD5       :  16 bytes

SHA-1    :  20 bytes

SHA-224:  28 bytes

SHA-256:  32 bytes

SF CRYPTO HASH Framework Module Features

• The SF CRYPTO HASH Framework utilizes the underlying Secure Crypto Engine to provide HASH services.
• This module provides enhancements over the HAL Driver such as:
  • Initializing the HASH value. 
  • Processing chunks of data through sf_crypto_hash_api_t::hashUpdate API before finalizing the hash operation.
  • Formatting the final block for the final HASH operation.

Configuration Settings for the SF CRYPTO HASH Framework Module

Configuration Parameter	Description
sf_crypto_hash_type_t       hash_type;	HASH algorithm type. Select MD5, SHA1, SHA 224 or SHA256. See the header file for the definitions.
crypto_instance_t               * p_lower_lvl_crypto	Pointer to a low-level Crypto engine HAL driver instance. Configured by Synergy Configurator.
hash_instance_t                  * p_lower_lvl_instance;	pointer to HASH lower-level module instance. Configured by ISDE.
void                                        * p_extend	Extension parameter for hardware specific settings. Optional. Configured by Synergy Configurator.

SF CRYPTO HASH Framework Module Limitations

None

SF CRYPTO KEY Framework Module Overview Description

The SF CRYPTO KEY Framework provides a high-level API and is implemented on sf_crypto_key.  The SF CRYPTO KEY Framework provides cryptographic key generation services through the Secure Cryptographic Engine (SCE) HAL module. 

The wrapped keys are often referred to by different names, for example encrypted key, key handle, wrapped key. Key wrapping on Synergy platform is considered secure as those keys cannot be used outside of the platform.

SF CRYPTO KEY Framework Module Features

The following key types can be generated using the services of the SF CRYPTO KEY module:

• RSA 2048-bit, 1024-bit plain text / raw keys.
• RSA 2048-bit, 1024-bit standard format wrapped private keys (public keys in plain ).
• AES 128-bit, 192-bit and 256-bit wrapped keys for ECB, CBC, CTR and GCM chaining modes.
• AES 128-bit and 256-bit wrapped keys for XTS chaining mode.
• ECC 192-bit, 224-bit, 256-bit, 384-bit plain-text and wrapped keys.

SF CRYPTO KEY Framework Module Operational Notes

AES Keys

AES wrapped key sizes are as follows:

/* Return Wrapped AES secret key size in bytes for a 128-bit AES Key */
#define AES128_WRAPPPED_SECRET_KEY_SIZE_BYTES  (36U)
/* Return Wrapped AES secret key size in bytes for a 192-bit AES Key */
#define AES192_WRAPPPED_SECRET_KEY_SIZE_BYTES  (52U)
/* Return Wrapped AES secret key size in bytes for a 256-bit AES Key */
#define AES256_WRAPPPED_SECRET_KEY_SIZE_BYTES  (52U)
/* Return Wrapped AES-XTS secret key size in bytes for a 128-bit AES XTS Mode Key */
#define AES_XTS_128_WRAPPPED_SECRET_KEY_SIZE_BYTES  (52U)
/* Return AES-XTS secret key size in bytes for a 256-bit AES XTS Mode Key */
#define AES_XTS_256_WRAPPPED_SECRET_KEY_SIZE_BYTES  (84U)

RSA Keys

The format of RSA plain text keys generated by the keyGenerate API is as follows:

RSA Public key

Byte 0 to Byte 3: Public key exponent

Byte 4                : Start of RSA modulus

                               (128 bytes for RSA 1024-bit and 256 bytes for RSA 2048-bit keys)

RSA Private key in standard format

Byte 0: Private key exponent (128 bytes for RSA 1024-bit and 256 bytes for RSA 2048-bit keys)

Followed by RSA modulus. (128 bytes for RSA 1024-bit and 256 bytes for RSA 2048-bit keys)

RSA Private key in CRT format

The components are ordered in the following order with exponent2 at byte 0:

exponent2            // the second factor's CRT exponent, a positive integer

prime2                 // the second factor, a positive integer

exponent1           // the first factor's CRT exponent, a positive integer

prime1                // the first factor, a positive integer

coefficient          //  the (first) CRT coefficient, a positive integer

The format of RSA wrapped keys generated by the keyGenerate API is as follows:

RSA Public key is always in plain text.

Byte 0 to Byte 3: Public key exponent

Byte 4               : Start of RSA modulus

                               (128 bytes for RSA 1024-bit and 256 bytes for RSA 2048-bit keys)

RSA Private key in standard format

Byte 0: Private key exponent is wrapped. (Length is 148 bytes for RSA 1024-bit and 276 bytes for RSA 2048-bit keys)

Followed by RSA modulus in plain text. (Length is 128 bytes for RSA 1024-bit and 256 bytes for RSA 2048-bit keys)

Configuration Settings for the SF CRYPTO KEY Framework Module

Configuration parameter	Description
sf_crypto_key_type_t            key_type	Key type to be generated. Plain text or Wrapped keys. See the header file for the definitions.
sf_crypto_key_size_t            key_size	Key size to be generated. See the header file for the definitions.
sf_crypto_data_handle_t       domain_params;	Pointer to domain parameters for the requested key type. Structure contains, pointer to the data (contains the domain data) and data length. Structure contains the domain data in the order a||b||p||n for ECC as defined in FIPS186-3 and data length. To be filled appropriately for ECC and set to NULL for RSA and AES Key types, since this parameter only applies to the ECC function.
sf_crypto_data_handle_t     generator_point	Pointer to the generator base point of curve in the order Gx||Gy for ECC (where Gx and Gy are x and y coordinates respectively) and data length. To be set to NULL for RSA and AES key types.
sf_crypto_instance_t            * p_lower_lvl_crypto_common	Pointer to a Crypto Framework common instance. Configured by Synergy Configurator.
void const                               * p_extend	Extension parameter for hardware specific settings (Reserved for future use). Configured by Synergy Configurator.

SF Crypto Signature Framework Module Overview Description

The SF CRYPTO Signature Framework provides a high-level API and is implemented on sf_crypto_signature. This module is in the SSP framework layer that interfaces with Synergy HAL drivers for the hardware level cryptography operations. The module functions specified herein are used to sign / verify messagethat is provided as input.

SF Crypto Signature Module Features

• This module currently supports signature generation and signature-verification for RSA algorithm. There is support for both 1024-bits and 2048-bits key lengths for standard format plain-text, standard format wrapped private key and CRT plain-text keys.
• RSASSA-PKCS1 v1.5 is the supported signature scheme. The input message can be passed as raw message to be signed/verified or can be PKCS1 v1.5 encoded and padded before sign/verify.
• SHA1, SHA224, SHA256 are the supported hashing algorithms for PKCS1 v1.5 encoding /padding schemes.
• This module allows signature generation / verification on data which is smaller than a block size.
• If all of the data is not available at once, update APIs can be used to accumulate the incoming chunks of data and finally sign/verify the message only when all the message is gathered. 
• Module allows to switching between sign and verify operations with less expensive API calls which are not involved in allocating and deallocating memory.

SF Crypto Signature Framework Module Operational Notes

1. Operation modes for Signature Framework Module:
   1. SF_CRYPTO_SIGNATURE_MODE_SIGN
   2. SF_CRYPTO_SIGNATURE_MODE_VERIFY
2. Input Message Format to the Signature Framework APIs to perform sign or verify operation:
   1. SF_CRYPTO_SIGNATURE_MESSAGE_OPERATION_NONE
   2. SF_CRYPTO_SIGNATURE_MESSAGE_OPERATION_RSA_SHA1_PKCS1_1_5
   3. SF_CRYPTO_SIGNATURE_MESSAGE_OPERATION_RSA_SHA224_PKCS1_1_5
   4. SF_CRYPTO_SIGNATURE_MESSAGE_OPERATION_RSA_SHA256_PKCS1_1_5

Configuration Settings for SF CRYPTO Signature Framework Module

Configuration parameter	Description
sf_crypto_key_type_t              key_type;	Type of Key RSA plain text or wrapped. See the header file for the definitions.
sf_crypto_key_size_t                key_size	Size of Key RSA 1024-bit /2048-bit key. See the header file for the definitions.
sf_crypto_hash_instance_t  * p_lower_lvl_sf_crypto_hash	Pointer to the Crypto Hash framework module instance structure. Configured by Synergy Configurator.
sf_crypto_instance_t            * p_lower_lvl_crypto_common	Pointer to Crypto Common module instance. Configured by Synergy Configurator.
void    const                           * p_extend	Extension parameter for hardware specific settings. Optional. Configured by Synergy Configurator.
void const                               * p_extend	Extension parameter for hardware specific settings (Reserved for future use). Configured by Synergy Configurator.

SF CRYPTO Signature Framework Module Limitations

None

SF Crypto Cipher Framework Module Overview Description

The SF CRYPTO Cipher Framework provides a high-level API and is implemented on sf_crypto_cipher. This module is in the SSP framework layer and provides encryption and decryption services through the Secure Cryptographic Engine (SCE) HAL module. 

SF Crypto Cipher Module Features

• This module currently supports encryption and decryption for AES and RSA algorithms.
• This module allows encryption/ decryption of data when available in chunks through the sf_crypto_cipher_api_t::cipherUpdate API and final() when the last chunk /all the data is gathered. 
• Once the module is opened for a specific key type and key size, the encrypt and decrypt modes can be switched by calling the sf_crypto_cipher_api_t::cipherInit API.

AES algorithm support:

• AES 128-bit, 192-bit and 256-bit plain text and wrapped keys for the following chaining modes:
  • ECB (Electronic Code Book)
  • CBC (Cipher Block Chaining)
  • CTR (Counter Mode)
  • GCM (Galois Counter Mode)
• AES 128-bit and 256-bit plain text and wrapped keys for XTS (XEX-based tweaked code-book mode with ciphertext stealing) are supported.
• IV provided for AES GCM operations can be either 96-bits or a 96-bit IV formatted to 128-bits.
  • Example:
    • 96-bit IV: 94c1935afc061cbf254b936f
    • 96-bit IV formatted to 128-bits: 94c1935afc061cbf254b936f00000001
• PKCS#7 padding scheme is supported for ECB and CBC modes. This scheme can be used when the data is of any block size from 1 to 255 bytes.
• No padding option is supported for all modes where the data is exactly a multiple of the AES block size.
  • For GCM, no padding option is to be selected even when the data is not a multiple of the block size.

RSA algorithm support:

• RSA 1024-bit and 2048-bit plain-text standard format, plain-text CRT format and standard format wrapped keys are supported.
• RSA encrypt operation requires RSA public key and RSA decrypt operation requires RSA private key.
• RSAES-PKCS1-v1_5 (RSA Encryption Scheme)
  • RSA-PKCS1 v1.5 encoding /padding scheme is supported.
  • The input raw message is encoded and formatted to be encrypted. It requires that the message be less than k-11 where k is the length of the modulus of the selected key.
• No padding option should be selected when an encoded and formatted block (exactly the size as the modulus of the selected key) needs to be encrypted / decrypted.

SF Crypto Cipher Framework Module Operational Notes

Configuration Settings for the SF Crypto Cipher Framework Module

Configuration Parameter	Description
sf_crypto_key_type_t   key_type	Key type for cipher operation: AES or RSA plain text or wrapped. Please refer to the header file for the definitions.
sf_crypto_key_size_t   key_size	Key size for cipher operation: AES 128-bit / 192-bit/256-bit key or RSA 1024-bit /2048-bit key. Please refer to the header file for the definitions.
sf_crypto_cipher_mode_t   cipher_chaining_mode	Applicable only to AES algorithm: ECB, CBC, CTR, XTS or GCM chaining modes Set to ECB for RSA. Please refer to the header file for the definitions.
sf_crypto_instance_t                 * p_lower_lvl_crypto_common	Pointer to Crypto Framework Common module instance. Configured by Synergy Configurator.
sf_crypto_trng_instance_t          * p_lower_lvl_crypto_trng	Pointer to Crypto Framework TRNG module instance. Configured by Synergy Configurator.
void    const                                * p_extend	Extension parameter for hardware specific settings.Optional. Configured by Synergy Configurator.

SF CRYPTO Cipher Framework Module Limitations

• AES XTS mode only supports lengths which are a multiple of 32-bits / 4 bytes.

SF Crypto Key Installation Framework Module Overview Description

The SF Crypto Key Installation Framework provides a high-level API and is implemented on sf_crypto_key_installation.  The SF Crypto Key Installation Framework Key Installation services through the Secure Cryptographic Engine (SCE) HAL module. 

Note

1. The API returns the wrapped key (please refer to the SF CRYPTO KEY Module section for the wrapped key format and size details) to the user and does not store the key for future use. It is the responsibility of the application to store the wrapped key in non-volatile memory for future use.
2. This Framework module provides the same level of service as the Crypto HAL module without any enhancements. It is provided for thread safe operation and for completeness of Crypto support in the Framework layer.

SF Crypto Key Installation Framework Module Features

• The SF Crypto Key Installation Framework module uses the KEY INSTALLATION HAL interfaces to the underlying Secure Crypto Engine.
• Access to shared resources through SF CRYPTO Framework module.
• This module supports key installation for the following keys:
  • RSA:
    • 1024-bit and 2048-bit plain text standard format keys.

    • Note

      CRT keys are not supported.

  • AES:
    • 128-bit, 192-bit and 256-bit plain text keys for ECB, CBC, CTR and GCM chaining modes.
    • 128-bit and 256-bit plain text keys for XTS chaining mode.
  • ECC:
    • 192-bit and 256-bit plain text keys.
• The session key, iv and shared index must be provided to the key installation API in the specified format.
• Upon installation the key installation service returns a wrapped key to the caller for any future usage of installed key on that device.
• ECC 224-bit and 384-bit keys are supported by the HAL module and not by the framework.

Configuration Settings for the SF Crypto Key Installation Framework Module

Configuration parameter	Description
sf_crypto_key_type_t key_type;	Type of key to be installed. The prepared key will be of the encrypted type. Please refer to the header file for the definitions.
sf_crypto_key_size_t key_size;	Size of key to be installed. Please refer to the header file for the definitions.
sf_crypto_instance_t         * p_lower_lvl_common;	Pointer to a Crypto Framework common instance. Configured by Synergy Configurator.
key_installation_instance_t  * p_lower_lvl_instance;	Pointer to Crypto Key Install HAL instance Configured by Synergy Configurator.
void const     * p_extend;	Extension parameter for hardware specific settings. For future use.

Including the Crypto Framework Module in an Application

This section describes how to include the Crypto Framework module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Crypto Framework module to an application, simply add it to a HAL /Common thread using the stacks selection sequence given in the following table. (The default name for the Crypto Framework module is g_sf_crypto0. This name can be changed in the associated Properties window.)

Crypto Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_crypt0 Crypto Framework on sf_crypto	Threads	New Stack> Framework> Crypto> Crypto Framework on sf_crypto
g_sf_crypt_key0 Crypto Key Framework on sf_crypto_key	Threads	New Stack> Framework> Crypto> Crypto Key Framework on sf_crypto_key
g_sf_crypt0 Crypto TRNG Framework on sf_crypto_trng	Threads	New Stack> Framework> Crypto> Crypto TRNG Framework
g_sf_crypt0 Crypto HASH Framework on sf_crypto_hash	Threads	New Stack> Framework> Crypto> Crypto HASH Framework
g_sf_crypt_key0 Crypto Key Installation Framework on sf_crypto_key_installation	Threads	New Stack> Framework> Crypto> Crypto Key Installation Framework on sf_crypto_key_installation
g_sf_crypt0 Crypto cipher Framework on sf_crypto_cipher	Threads	New Stack> Framework> Crypto> Crypto cipher Framework
g_sf_crypt0 Crypto signature Framework on sf_crypto_signature	Threads	New Stack> Framework> Crypto> Crypto signature Framework

When the Crypto Framework module on sf_crypto is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

Crypto Framework Module Stack

Configuring the Crypto Framework Module

The Crypto Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are not available for changes, and are identified with a lock icon for the 'locked' property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous 'manual' approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP configurator, and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings; this will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with the SSP.

Configuration Settings for the Crypto Framework on sf_crypto

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto0	Module name.
Wait time	TX_WAIT_FOREVER	Value must be a non-negative integer.
Byte Pool Size	128	Specify the size of the byte pool in bytes.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto will be initialized during startup.
Force Closure Support	Default, Force Close Default: Default	Select Force Close to close the crypto module regardless of the status of submodules.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto HASH Framework on sf_crypto_hash

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Instance Name	g_sf_crypto_hash0	Module name.
Name of generated initialization function	sf_crypto_hash_init0	Select the name of the generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_hash will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto TRNG Framework on sf_crypto_trng

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto_trng0	Module name.
Name of generated initialization function	sf_crypt_trng_init0	Select the name of the generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_trng will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto Cipher Framework on sf_crypto_cipher

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto_cipher0	Module name.
Key type	RSA Plain text, RSA CRT Plain text, RSA Wrapped, AES Wrapped, ECC Plain text, ECC Wrapped Default: RSA Plain text	Select the key type.
Key size	RSA 1024-bits, RSA 2048-bits, AES 128-bits, AES XTS 128-bits, AES 192-bits, AES 256-bits, AES XTS 256-bits, ECC 192-bits, ECC 256-bits Default: RSA 2048-bits	Select the key size.
Cipher chaining mode	ECB, CBC, CTR, GCM, XTS Default: ECB	Select the cipher chaining mode.
Name of generated initialization function	sf_crypto_cipher_init0	Select the name of the generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_cipher will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto Key Framework on sf_crypto_key

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto_key0	Module name.
Key type	RSA Plain text, RSA CRT Plain text, RSA Wrapped, AES Wrapped, ECC Plain text, ECC Wrapped Default: RSA Plain text	Select the key type. For AES, the byte pool size defined in sf_crypto must be >= 280 bytes.
Key size	RSA 1024-bits, RSA 2048-bits, AES 128-bits, AES XTS 128-bits, AES 192-bits, AES 256-bits, AES XTS 256-bits, ECC 192-bits, ECC 224-bits, ECC 256-bits, ECC 384-bits Default: RSA 2048-bits	Select the key size.
Name of generated initialization function	sf_crypto_key_init0	Select the name of the generated initialization function.
Name of Domain Parameter (Applicable only for ECC)	sf_crypto_key_domain_params0	Specify the name of the ECC domain partner.
Name of Generator Point (Applicable only for ECC)	sf_crypto_key_generator_point0	Specify the name of the ECC generator point.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_key_will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto Key Installation Framework on sf_crypto_key_installation

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto_key_installation0	Module name.
Key type	Encrypted RSA Key, Encrypted AES Key, Encrypted ECC Key Default: Encrypted RSA Key	Select the key type.
Key size	RSA 1024-bits, RSA 2048-bits, AES 128-bits, AES XTS 128-bits, AES 192-bits, AES 256-bits, AES XTS 256-bits, ECC 192-bits, ECC 256-bits Default: RSA 2048-bits	Select the key size.
Name of generated initialization function	sf_crypto_key_installation_init0	Select the name of the generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_key_installation will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Crypto Signature Framework on sf_crypto_signature

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Select if code for parameter checking is to be included in the build.
Name	g_sf_crypto_signature0	Module name.
Key type	RSA Plain text, RSA CRT Plain text, RSA Wrapped Default: RSA Plain text	Select the key type. Byte Pool size in sf_crypto must be > = 1450 bytes.
Key size	RSA 1024-bits, RSA 2048-bits Default: RSA 2048-bits	Select the key size.
Name of generated initialization function	sf_crypto_signature_init0	Select the name of the generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Select if sf_crypto_signature will be initialized during startup.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Using the Crypto Framework Module in an Application

The typical steps in using the SF CRYPTO Framework module in an application are:

To use the SF CRYPTO module.

• Ensure that the configuration parameters (given in the previous table) are set as per the needs of the application.
• Use the sf_crypto_api_t::open API to Initialize the SF_CRYPTO and the SCE HAL module (R_SCE) through the SCE common driver. This is done by Synergy Configurator when the Auto Initialize setting is at default.
• The little endian mode is set by default.  It is locked and not configurable.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_api_t::close API to close the Crypto Framework services and the HW SCE.

Using the SF CRYPTO HASH Framework Module in an Application

The typical steps in using the SF CRYPTO HASH Framework module in an application are:

Calling the APIs in this order: sf_crypto_hash_api_t::open -> sf_crypto_hash_api_t::hashInit -> sf_crypto_hash_api_t::hashUpdate -> sf_crypto_hash_api_t::hashFinal -> sf_crypto_hash_api_t::close.

Details:

• Add SF_CRYPTO HASH Framework module in the Synergy Configurator. The HASH algorithm for this instance is set to SHA 256 by default.
• The little endian mode is set by default.  It is locked and not configurable. (Please refer to note on endianness and data format in the Module Operational Notes.)
• The SF CRYPTO Module has to be first opened. (The Synergy Configurator will do this provided the Auto start option set by default is retained.)
• Set the chosen HASH algorithm (specified in Table 4) as the configuration parameter for the module open API.
• Use the sf_crypto_hash_api_t::open API to initialize the SF CRYPTO HASH Framework module and the SCE HASH HAL module (R_SCE_HASH) through the SCE HASH driver. (The Synergy Configurator will do this provided the Auto init option set by default is retained.)
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_hash_api_t::hashInit API to initialize the HASH operation for the chosen HASH algorithm.
  • The sf_crypto_hash_api_t::hashInit can be called after the sf_crypto_hash_api_t::open API, sf_crypto_hash_api_t::hashUpdate API or sf_crypto_hash_api_t::hashFinal API to initialize a new operation with the configured HASH algorithm.
• Use the sf_crypto_hash_api_t::hashUpdate API to hash input data. It can be called multiple times until all the data is completely used up.
• Use the sf_crypto_hash_api_t::hashFinal API to get the message digest for all the data hashed with the sf_crypto_hash_api_t::hashUpdate API.
  • Once the sf_crypto_hash_api_t::hashFinal API is called, either the sf_crypto_hash_api_t::hashInit can be called to initialize operation for the next set of data using the same HASH algorithm or the sf_crypto_hash_api_t::close API can be called to close the module. It can then be re-opened for a different HASH algorithm.
• Use the sf_crypto_hash_api_t::close API to close the Crypto HASH Framework services.

Note

In a particular thread, a single instance of the SF CRYPTO HASH module can be re-used for different HASH algorithms without having to create multiple instances.

Using the SF CRYPTO TRNG Framework Module in an Application

The typical steps in using the SF CRYPTO TRNG Framework module in an application are:

• Use the sf_crypto_trng_api_t::open API to initialize the SF_CRYPTO_TRNG and the SCE TRNG HAL module (R_SCE_TRNG). This is done by the ISDE when the auto initialization setting is set to default.
• The little endian mode is set by default.  It is locked and not configurable. (Please refer to the note on endianness and data format in the module Operational Notes.)
• The open function cannot be called again until the module is closed.
• Use sf_crypto_trng_api_t::randomNumberGenerate API to generate random numbers. The minimum length of random number bytes that can be requested is 1.
• Use sf_crypto_trng_api_t::close API to close the Crypto Framework services and the SCE when the TRNG services are no longer required.

Note

In the rare event that the sf_crypto_trng_api_t::randomNumberGenerate API returns an error, all the CRYPTO Framework modules have to closed and SF CRYPTO module re-opened.

There will be only one instance of the TRNG HAL module, so the configuration parameters set for each instance of the Crypto TRNG Framework will be overwrite any previously configured instances. The last value configured is applicable to all instances.

Using the SF CRYPTO Cipher Framework Module in an Application

The typical steps in using the SF CRYPTO Cipher Framework module in an application are:

Calling the APIs in this order: sf_crypto_cipher_api_t::open -> sf_crypto_cipher_api_t::cipherInit -> sf_crypto_cipher_api_t::cipherUpdate -> sf_crypto_cipher_api_t::cipherFinal -> sf_crypto_cipher_api_t::close.

Details:

• Please refer to the note on endianness and data format in the module Operational Notes.
• The Crypto Framework module has to be opened first; the ISDE will do this provided the auto initialization option set by default is retained. Refer to the section regarding using the Crypto Framework module in an Application.
• Set the configuration parameters for the module sf_crypto_cipher_api_t::open API per the needs of the application.
• Use the sf_crypto_cipher_api_t::open API to open the Crypto Cipher Framework module (This is done by the ISDE when the auto start option is set to the default setting) and the SCE HAL modules through the SCE drivers.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_cipher_api_t::cipherInit API to initialize the context by assigning appropriate operation mode, key and padding scheme option and algorithm specific parameters.
• If the data for encrypt / decrypt operation is not available all at once but is available in chunks, use the sf_crypto_cipher_api_t::cipherUpdate API. The sf_crypto_cipher_api_t::cipherUpdate API can be called multiple times.

Note

For RSA operations, no data is outputted from the sf_crypto_cipher_api_t::cipherUpdate API. The message will only be accumulated until the sf_crypto_cipher_api_t::cipherFinal API is called.

• In order to complete the encrypt or decrypt operation call the sf_crypto_cipher_api_t::cipherFinal API. This API accepts last chunk of incoming data. In case all the data has been passed through the sf_crypto_cipher_api_t::cipherUpdate APIs the length for last message chunk can be set to 0.
• In case all the data to be encrypted/decrypted is available at once, sf_crypto_cipher_api_t::cipherFinal API can be called directly without using the sf_crypto_cipher_api_t::cipherUpdate API.
• Use sf_crypto_cipher_api_t::close API to close the Crypto Cipher Framework Module services.

AES GCM operation specifics:

• For AES GCM encrypt / decrypt operations, AAD (Additional Authenticated Data) is optional. If it is to be used, it has to be provided for the cipher operation through the sf_crypto_cipher_api_t::cipherAadUpdate API after the sf_crypto_cipher_api_t::cipherInit is called and prior to calling the sf_crypto_cipher_api_t::cipherUpdate or sf_crypto_cipher_api_t::cipherFinal APIs.
• For AES GCM encrypt operation, the tag (Authentication Tag) will be generated when cipherFinal API is executed. The caller has to supply the buffer to hold the tag through the cipherInit API.
• For AES GCM decrypt operation, the tag has to be provided prior to providing any ciphertext data through the cipherUpdate / cipherFinal APIs. Hence the caller is required to provide the tag through the cipherInit API.
• The AES GCM decrypt operation may output plain text data through the cipherUpdate / cipherFinal APIs but it should not be consumed if the decrypt operation returns an error code. This is to ensure that the tag is verified before the data is used.

Note

In a particular thread, a single instance of the Crypto Cipher Framework module can be re-used for alternately performing encrypt or decrypt operations by appropriately setting/re-setting the operation mode and other related parameters. Two instances of the Crypto Cipher Framework module can also be used simultaneously.

Using the SF CRYPTO KEY Framework Module in an Application

The typical steps in using the SF CRYPTO KEY Framework module in an application are:

Calling the APIs in this order: sf_crypto_key_api_t::open ->  sf_crypto_key_api_t::keyGenerate -> sf_crypto_key_api_t::EcdhSharedSecretCompute -> sf_crypto_key_api_t::close.

Details:

• Please refer to note on endianness and data format in the module Operational Notes.
• The Crypto Key Framework has to be opened first; the ISDE will do this provided the auto initialization option is set to the default setting. Refer to the Using the Crypto Framework Module in an Application section.
• Set the configuration parameters as per the needs of the application required for the module sf_crypto_key_api_t::open API.
• Use the sf_crypto_key_api_t::open API to initialize the Crypto Key Framework module; this is done by the ISDE when the auto start option is set to the default setting) and the SCE HAL modules through the SCE drivers.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_key_api_t::keyGenerate API to generate the cryptographic keys of the type and size set by the configuration parameters at the open call.
• Use sf_crypto_key_api_t::EcdhSharedSecretCompute API to perform scalar multiplication for ECC algorithms only.
• Use sf_crypto_key_api_t::close API to close the Crypto Key Framework Module services.

Note

In a particular thread, a single instance of Crypto Key Framework module can be re-used for generating different key types without having to create multiple instances.

Using the SF Crypto Key Installation Framework Module in an Application

The typical steps in using the SF Crypto Key Installation Framework module in an application are:

Calling the APIs in this order: sf_crypto_key_installation_api_t::open -> sf_crypto_key_installation_api_t::keyInstall -> sf_crypto_key_installation_api_t::close.

Details:

• Please refer to note on endianness and data format in the module Operational Notes.
• The Crypto Framework Module has to be opened first; the ISDE will do this provided the auto initialization option is set to the default setting. Refer to the Using the Crypto Framework Module in an Application section.
• Set the configuration parameters for the module sf_crypto_key_installation_api_t::open API per the needs of the application.
• Use the sf_crypto_key_installation_api_t::open API to open the Crypto Key Installation Framework module (This is done by the ISDE when the auto start option is set to the default setting) and the SCE HAL modules through the SCE drivers.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_key_installation_api_t::keyInstall API to install the user's key.
• Use sf_crypto_key_installation_api_t::close API to close the Crypto Key Installation Framework Module services.

Using the SF CRYPTO Signature Framework Module in an Application

The typical steps in using the SF CRYPTO Signature Framework module in an application are:

Calling the APIs in this order: sf_crypto_signature_api_t::open -> sf_crypto_signature_api_t::contextInit -> sf_crypto_signature_api_t::signUpdate -> sf_crypto_signature_api_t::signFinal -> sf_crypto_signature_api_t::close.

Calling the APIs in this order: sf_crypto_signature_api_t::open -> sf_crypto_signature_api_t::contextInit -> sf_crypto_signature_api_t::verifyUpdate -> sf_crypto_signature_api_t::verifyFinal -> sf_crypto_signature_api_t::close.

Details:

• Please refer to note on endianness and data format in the module Operational Notes.
• The Crypto Framework module has to be opened first; the ISDE will do this provided the auto initialization option is set to the default setting. Refer to the Using the Crypto Framework Module in an Application section.
• Set the configuration parameters per the needs of the application required for the module sf_crypto_signature_api_t::open API.
• Use the sf_crypto_signature_api_t::open API to open the Crypto Signature Framework module (This is done by ISDE when the auto start option is set to the default setting) and the SCE HAL modules through the SCE drivers.
• The open function cannot be called again until the module is closed.
• Use the sf_crypto_signature_api_t::contextInit API to initialize the context by assigning appropriate operation mode, key (public key for verify operation mode and private key for sign operation mode), message formatting option.
• If the data is coming in as smaller chunks for sign operation mode, use the sf_crypto_signature_api_t::signUpdate API to accumulate the data for future signing operation or for verify operation mode use the sf_crypto_signature_api_t::verifyFinal API to accumulate the data for future signature verification.
• In order to complete the sign or verify operation call the sf_crypto_signature_api_t::signFinal or sf_crypto_signature_api_t::verifyFinal APIs, respectively. These APIs support accepting the last chunk of incoming data. In case all the data has been passed through, one of the update API parameters for last message chunk can be set to NULL.
• In case all the data to be signed or verified is available at once, sf_crypto_signature_api_t::signFinal or sf_crypto_signature_api_t::verifyFinal can be called directly without using either of the update APIs.
• Use sf_crypto_signature_api_t::close API to close the Crypto Signature Framework module services.

Note

In a particular thread, a single instance of the Crypto Signature Framework module can be re-used for alternately performing sign or verify operations by appropriately setting/re-setting the operation mode and other related parameters. In order to perform sign or verify operations simultaneously, two instances of the SF Crypto Signature Framework module need to be used.