SCE HAL Module Introduction
- SCE HAL Module Features
- SCE Hardware Support Details
SCE HAL Module APIs Overview
SCE HAL Module Operational Overview
- SCE HAL Module Important Operational Notes and Limitations
  - SCE HAL Module Operational Notes
  - SCE HAL Module Limitations
Including the SCE HAL Module in an Application
Configuring the SCE HAL Module
Using the SCE HAL Module in an Application

SCE HAL Module Introduction

The Secure Cryptographic Engine (SCE) HAL module provides high-level API functions for random number generation, digest computation (hash), data encryption and decryption, digital signing and verification, key generation (using RSA, AES and ECC algorithms), ECC scalar multiplication and key installation (for RSA, AES and ECC keys). The SCE is a dedicated hardware block and the functionality provided by the SCE varies across the supported MCUs.

SCE HAL Module Features

The SCE HAL module configures the cryptographic module, which allows user to build cryptographic protocols for security with the following cryptographic primitives:

Random-number generation
Data encryption and decryption using AES or Triple DES (3DES) or ARC4 algorithms
Signature generation and verification using the ECC, RSA or DSA algorithms
Scalar multiplication support for ECDH key agreement operations.
Message-digest computation using HASH algorithms MD5, SHA1, SHA224, or SHA256
Key generation - AES wrapped keys, RSA plain text and wrapped keys, ECC plain text and wrapped keys
Installing the encrypted user key on to the Synergy platform.

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).
The original key cannot be recovered from the wrapped key.

SCE HAL Module Block Diagram

*KI is an abbreviation for Key Installation

SCE Hardware Support Details

Note: The prior figure shows all nine available crypto modules. The SCE COMMON module is repeated for each one since it is included when the module is added to a thread stack. Common modules can be referenced by multiple other module instances across multiple Synergy stacks.

Support of MCU Groups: SCE Driver

Function	S7G2, S5D9, S5D5, S5D3	S3A1, S3A3, S3A7, S3A6	S1JA, S124, S128	Notes
TRNG	Generate and read random number	Generate and read random number	Generate and read random number	Generate and read random number
AES	Encryption, decryption, key generation - wrapped keys	Encryption, decryption, key generation - wrapped keys	Encryption, decryption	Symmetric key encryption based on AES standard
AES Key Size	128-bit, 192-bit, 256-bit	128-bit, 256-bit	128-bit, 256-bit
AES Key Type	Plain text/raw key, wrapped key	Plain text/raw key, wrapped key	Plain text/raw key
AES Chaining Modes	ECB, CBC, CTR, GCM, XTS††	ECB, CBC, CTR, GCM, XTS	ECB, CBC, CTR
ARC4	Encryption, decryption	NA	NA
TDES	Encryption, decryption	NA	NA
TDES Key Size	192-bit	NA	NA
TDES Chaining Modes	ECB, CBC, CTR	NA	NA
RSA	Signature Generation, Signature Verification, Public-key Encryption, Private-key Decryption, Key Generation - plain text and wrapped keys	NA	NA	Supports CRT keys and standard keys for private key operations for both plain-text and wrapped key types

Function	S7G2, S5D9, S5D5, S5D3	S3A1, S3A3, S3A7, S3A6	S1JA, S124, S128	Notes
RSA Key Size	1024-bit, 2048-bit	NA	NA
RSA Key Type	Plain text/raw standard format and CRT keys, wrapped standard format and wrapped CRT keys	NA	NA
Key Installation	AES, ECC, RSA keys	AES keys	NA
ECC	Key Generation – plain text and wrapped keys, Scalar Multiplication, ECDSA – Signature Generation, ECDSA – Signature Verification	NA	NA
ECC Key Size (in bits)	192, 224, 256, and 384	NA	NA
ECC Key Type	Plain text/ raw keys and wrapped keys	NA	NA
DSA	Signature Generation, Signature Verification	NA	NA
DSA Key Size	(1024, 160)-bit, (2048, 224)-bit, (2048, 256)-bit	NA	NA
HASH	MD5, SHA1, SHA224, SHA256	NA	NA	Message digest algorithms

†† XTS is supported for 128-bit and 256-bit keys only.

SCE HAL Module APIs Overview

The SCE interface provides a common API for SCE HAL modules. The SCE interface supports multiple operations depending on the chosen module (AES, ARC4, RSA, DSA, HASH, TDES or TRNG).

The AES interface defines APIs for opening, closing, generating wrapped keys, encrypting and decrypting data using the AES algorithm. It uses a 128-bit, 192-bit or 256-bit key and ECB, CBC, CTR, GCM or XTS chaining-mode options. A complete list of the available APIs, an example API call, and a short description of each can be found in the following table. For return status values, refer to the SCE API reference section of the SSP User's Manual.

SCE Common Instance API Summary

Function Name	Example API Call and Description
open	`g_sce.p_api->open(g_sce.p_ctrl, g_sce.p_cfg);` SCE Common module open function. Must be called before performing any other crypto operations.
close	`g_sce.p_api->close(g_sce.p_ctrl);` Close the SCE Common module.
interfaceGet	`g_sce.p_api->interfaceGet(g_sce_aes.p_ctrl, p_interface_info, p_interface);` Get the interface structure for the interface info provided.
statusGet	`g_sce.p_api->statusGet (g_sce.p_ctrl, p_status);` Get status of SCE initialization.
versionGet	`g_sce.p_api->versionGet(&version);` Gets the module code and API version and stores it in provided 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.

AES HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_aes.p_api->open(g_sce_aes.p_ctrl, g_sce_aes.p_cfg);` AES module open function. Must be called before performing any encrypt/decrypt operations.
createKey	`g_sce_aes.p_api->createKey(g_sce_aes.p_ctrl, num_words, p_key);` Generate an AES key for encrypt/decrypt operations.
encrypt	`g_sce_aes.p_api->encrypt(g_sce_aes.p_ctrl, p_key, p_vi, num_words, p_source, p_dest);` AES encryption using the chaining mode and padding mode specified in the open() function call.
addAdditionalAuthenticationData	`g_sce_aes.p_api->addAdditionalAuthenticationData (g_sce_aes.p_ctrl, p_key, p_vi, num_words, p_source);` Add additional authentication data (called before starting an encryption or decryption operation).
encryptFinal	`g_sce_aes.p_api->encryptFinal(g_sce_aes.p_ctrl, p_key, p_iv, input_num_words, p_source, output_num_words, p_dest);` AES final encryption using the chaining mode and padding mode specified in the open() function call.
decrypt	`g_sce_aes.p_api->decrypt(g_sce_aes.p_ctrl, p_key, p_iv, num_words, p_source, p_dest);` AES decryption.
setGcmTag	`g_sce_aes.p_api-> setGcmTag(g_sce_aes.p_ctrl,num_words, p_source);` Set authentication tag data.
getGcmTag	`g_sce_aes.p_api->` `getGcmTag(g_sce_aes.p_ctrl,num_words, p_dest);` Get authentication tag data.
zeroPaddingEncrypt	`g_sce_aes.p_api->` `zeroPaddingEncrypt(g_sce_aes.p_ctrl, p_key, p_iv, num_bytes, p_source, p_dest)` AES zero padding encryption using the chaining mode and padding mode specified. Implementation for GCM mode only API usage - 1. To provide any Add Authentication Data (AAD): set p_dest = NULL 2. Encryption: set p_source to input data and p_dest will return encrypted data 3. Get/Compute Tag: set p_source = NULL
zeroPaddingDecrypt	`g_sce_aes.p_api->` `zeroPaddingDecrypt(g_sce_aes.p_ctrl, p_key, p_iv, num_words, p_source, p_dest);` AES zero padding decryption< using the chaining mode and padding mode specified. Implementation for GCM mode only API usage - 1. Set expected tag value using the setGcmTag() function 2. To provide any Add Authentication Data (AAD), invoke this API using p_dest = NULL 3. Decryption: set p_source to input encrypted data, decrypted data will be returned in p_dest 4. To verify the tag, invoke this API using p_source = NULL and p_dest = NULL, the return value indicates authentication tag verification status.
versionGet	`g_sce_aes.p_api->versionGet(&version);` Gets the module code and API version and stores it in provided version pointer.
close	`g_sce_aes.p_api->close(g_sce_aes.p_ctrl);` Close the AES module.

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 ARC4 interface defines APIs for opening, closing, setting a key and processing data. A complete list of the available APIs, an example API call and a short description of each can be found in the following table:

ARC4 HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_arc4.p_api->open(g_sce_arc4.p_ctrl, g_sce_trng.p_cfg);` Open the ARC4 module.
keySet	`g_sce_arc4.p_api->keySet(g_sce_arc4.p_ctrl, &rngbuf, nbytes);` Set the key to be used by the ARC4 module.
arc4Process	`g_sce_arc4.p_api-> arc4Process(g_sce_arc4.p_ctrl, nbytes, &source, &destination);` Encrypt or decrypt data using the ARC4 module.
close	`g_sce_arc4.p_api->close(g_sce_arc4.p_ctrl);` Close the ARC4 module.
versionGet	`g_sce_arc4.p_api->versionGet (&version);` Retrieve the version using the provided 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 DSA interface defines APIs for opening, closing, digital-signing and verification. Available options include a 1024-bit public key and a 160-bit private key, a 2048-bit public key and a 224-bit private key or a 2048-bit public key and a 256-bit private key. A complete list of the available APIs, an example API call and a short description of each can be found in the following table:

DSA HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_dsa.p_api->open(g_sce_dsa.p_ctrl, g_sce_dsa.p_cfg);` DSA module open function. Must be called before performing any sign/verify operations.
verify	`g_sce_dsa.p_api->verify(p_key, p_domain, num_words, p_signature, p_paddedHash);` DSA signature verification using given DSA public key. This function is deprecated. The function hashVerify should be used instead.
hashVerify	`g_sce_dsa.p_api->hashVerify(g_sce_dsa.p_ctrl, p_key, p_domain, num_words, p_signature, p_paddedHash);` DSA signature verification using given DSA public key.
sign	`g_sce_dsa.p_api->sign(p_key, p_domain, num_words, p_padded_hash, p_dest);` DSA Signature generation using DSA private key. This function is deprecated. The function hashSign should be used instead.
hashSign	`g_sce_dsa.p_api->hashSign(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_padded_hash, p_dest);` DSA Signature generation using DSA private key.
close	`g_sce_dsa.p_api->close(g_sce_dsa.p_ctrl);` Close the DSA module.
versionGet	`g_sce_dsa.p_api->versionGet(p_version);` Gets version and stores it in provided pointer p_version.

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.

ECC HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_ecc.p_api->open(g_sce_ecc.p_ctrl, g_sce_ecc.p_cfg);` Open the ECC driver. This API must be called before performing any ECC operations.
close	`g_sce_ecc.p_api->close(g_sce_ecc.p_ctrl);` Close the ECC module.
scalarMultiplication	`g_sce_ecc.p_api-> scalarMultiplication(g_sce_ecc.p_ctrl, p_domain, p_k, p_p, p_r);` This API calculates R=kP.
keyCreate	`g_sce_ecc.p_api->keyCreate(g_sce_ecc.p_trl, p_domain, p_generator_point, p_key_private, p_key_public);` This API generates key pair for ECC.
sign	`g_sce_ecc.p_api->sign(g_sce_ecc.p_ctrl, p_domain, p_generator_point, p_key_private, msg_digest, signature_r, signature_s);` This API generates signature of ECDSA.
verify	`g_sce_ecc.p_api->verify(g_sce_ecc.p_ctrl, p_domian, p_generator_point, p_key_public, msg_digest, signature_r, signature_s);` This is a procedure for signature verification of ECDSA.
versionGet	`g_sce_ecc.p_api->versionGet(&version);` Gets version and stores it in provided 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 HASH interface defines APIs for calculating hash values for a given data-set. Available options include SHA1 and SHA256 algorithms. A complete list of the available APIs, an example API call and a short description of each can be found in the following table:

HASH HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_hash.p_api->open(g_sce_hash.p_ctrl, g_sce_hash.p_cfg);` HASH module open function. Must be called before performing any sign/verify operations.
updateHash	`g_sce_hash.p_api->updateHash(p_source, num_words, p_dest);` Update hash for the num_words words from source buffer p_source. This function is deprecated. The function hashUpdate should be used instead.
hashUpdate	`g_sce_hash.p_api->hashUpdate(g_sce_hash.p_ctrl, p_source, num_words, p_dest);` Update hash for the num_words words from source buffer p_source.
close	`g_sce_hash.p_api->close(g_sce_hash.p_ctrl);` HASH module close function.
versionGet	`g_sce_hash.p_api->versionGet(p_version);` Gets version and stores it in provided pointer p_version.

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.

Key Installation HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_key_installation.p_api-> open(g_sce_key_installation.p_ctrl, p_cfg);` Open the Crypto Key Installation framework for subsequent call/Key installation.
close	`g_sce_key_installation.p_api->close(g_sce_key_installation.p_ctrl);` Close the Crypto Key Installation framework.
keyInstall	`g_sce_key_installation.p_api-> keyInstall (g_sce_key_installation.p_ctrl, p_user_key_input, p_user_key_rsa_modulus, p_install_key_input, p_key_data_out);` Install a key version 2. This function takes the RSA modulus of the user's RSA private key as one of the input parameters to return the RSA wrapped key in a format that is compatible with other Crypto APIs. For all other key types the functionality remains the same as the earlier keyInstall API.
versionGet	`g_sce_key_installation.p_api-> versionGet(&version);` Get version of the Crypto Key Installation framework and stores it in the provided 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 RSA interface defines APIs for opening, closing, encrypting and decrypting data using an RSA algorithm as well as digitally signing and verifying the algorithm. The RSA interface employs a 1024-bit or 2048-bit key. A complete list of the available APIs, an example API call and a short description of each can be found in the following table:

RSA HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_rsa.p_api->open(g_sce_rsa.p_ctrl, g_sce_rsa.p_cfg);` RSA module open function. Must be called before performing any encrypt/decrypt or sign/verify operations.
encrypt	`g_sce_rsa.p_api->encrypt(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_source, p_dest);` Encrypt source data from p_source using an RSA public key from p_key and write the results to destination buffer p_dest.
decrypt	`g_sce_rsa.p_api->decrypt (g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_source, p_dest);` Decrypt source data from p_source using an RSA private key from p_key and write the results to destination buffer p_dest.
decryptCrt	`g_sce_rsa.p_api->decryptCrt(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_source, p_dest);` Decrypt source data from p_source using an RSA private key from p_key and write the results to destination buffer p_dest. RSA private key data is specified in CRT format.
verify	`g_sce_rsa.p_api->verify(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_signature, p_padded_hash);` Verify signature given in buffer p_signature using the RSA public key p_key for the given padded message hash from buffer p_padded_hash.
sign	`g_sce_rsa.p_api->sign(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_padded_hash, p_dest);` Generate signature for the given padded hash buffer p_padded_hash using the RSA private key p_key. Write the results to the buffer p_dest.
signCrt	`g_sce_rsa.p_api->signCrt(g_sce_rsa.p_ctrl, p_key, p_domain, num_words, p_padded_hash, p_dest);` Generate signature for the given padded hash buffer p_padded_hash using the RSA private key p_key. RSA private key p_key is assumed to be in CRT format. Write the results to the buffer p_dest.
close	`g_sce_rsa.p_api->close(g_sce_rsa.p_ctrl);` Close the RSA module.
keyCreate	`g_sce_rsa.p_api->keyCreate(g_sce_rsa.p_ctrl,` `p_private_key, p_public_key);` Generates an RSA key pair.
versionGet	`g_sce_rsa.p_api->versionGet(p_version);` Gets version and stores it in provided pointer p_version.

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 TDES interface defines APIs for encrypting and decrypting data according to the TDES standard. A complete list of the available APIs, an example API call and a short description of each can be found in the following table:

TDES HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_tdes.p_api->open(g_sce_tdes.p_ctrl, g_sce_tdes.p_cfg);` Open the TDES module.
encrypt encrypt	`g_sce_tdes.p_api->` `encrypt(g_sce_tdes.p_ctrl, &key, &iv, nwords, &source, &destination);` Encrypt the data.
decrypt	`g_sce_tdes.p_api->` `decrypt(g_sce_tdes.p_ctrl, &key, &iv, nwords, &source, &destination);` Decrypt the data.
close	`g_sce_tdes.p_api->close(g_sce_tdes.p_ctrl);` Close the TDES module.
versionGet	`g_sce_tdes.p_api->versionGet(p_version);` Gets version and stores it in provided pointer p_version.

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 TRNG interface defines APIs for computing the random-number generator. A complete list of the available APIs, an example API call and a short description of each can be found in the following table.

TRNG HAL Module API Summary

Function Name	Example API Call and Description
open	`g_sce_trng.p_api->open(g_sce_trng.p_ctrl, g_sce_trng.p_cfg);` Open the TRNG driver for reading random data from the hardware TRNG module.
read	`g_sce_trng.p_api->read(g_sce_trng.p_ctrl, p_rngbuf, nbytes);` Generate nbytes of random number bytes and store them in p_rngbuf buffer.
close	`g_sce_trng.p_api->close(g_sce_trng.p_ctrl);` Close the TRNG interface driver.
versionGet	`g_sce_trng.p_api->versionGet(&version);` Gets version and stores it in provided 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.

SCE HAL Module Operational Overview

Different cryptographic functions are available for different target MCUs; the following table shows the functionality that is available for each individual MCU-series:

Function	S7G2, S5D9, S5D5, S5D3	S3A1, S3A3, S3A7, S3A6	S124, S128, S1JA	Notes
TRNG	Generate and read random number	Generate and read random number	Generate and read random number	Generate and read random number.
AES	Encryption, decryption, Key Generation - wrapped keys	Encryption, decryption, Key Generation - wrapped keys	Encryption, decryption	Symmetric Key Encryption based on AES standard.
AES Key Size	128-bit, 192-bit, 256-bit	128-bit, 256-bit	128-bit, 256-bit
AES Key Type	Plain text/raw key, Wrapped key	Plain text/raw key, Wrapped key	Plain text/raw key
AES Chaining Modes	ECB, CBC, CTR, GCM, XTS Note: XTS is supported for 128-bit and 256-bit keys only	ECB, CBC, CTR, GCM, XTS	ECB, CBC, CTR
ARC4	Encryption, decryption	NA	NA
TDES	Encryption, decryption	NA	NA
TDES Key Size	192-bit	NA	NA
TDES Chaining Modes	ECB, CBC, CTR	NA	NA
RSA	Signature Generation, Signature Verification, Public-key Encryption, Private-key Decryption, Key Generation - plain text and wrapped keys	NA	NA	Supports CRT keys and standard keys for private key operations for both plain-text and wrapped key types.
RSA Key Size	1024-bit, 2048-bit	NA	NA
RSA Key Type	Plain text/raw standard format and CRT keys, wrapped standard format and wrapped CRT keys	NA	NA
DSA	Signature Generation, Signature Verification	NA	NA
DSA Key Size	(1024, 160)-bit, (2048, 224)-bit, (2048, 256)-bit	NA	NA
HASH	MD5, SHA1, SHA224, SHA256	NA	NA	Message digest algorithms.
ECC	Key Generation – plain text and wrapped keys, Scalar Multiplication, ECDSA- Signature Generation, ECDSA -Signature Verification,	NA	NA
ECC Key Size	192-bit, 224-bit, 256-bit and 384-bit	NA	NA
ECC Key Type	Plain Text/Raw Key, Wrapped Key
Key Installation	AES, ECC, RSA keys	AES keys	NA

Configuration Settings for the R_SCE Module

The endianness of the SCE is set to big endian by default. It can be set to little endian mode.

Please refer to the operational notes on endianness configuration parameter usage.

Configuration Settings for the TRNG Module

Random number-generation can be configured for the maximum number of attempts it makes to the underlying hardware to generate a unique 16-byte random number that differs from the previously-generated random number. On reaching the maximum number of attempts, the read API will return an error code to the caller, otherwise a success code is returned and the generated random number will be transferred to the caller-supplied data buffer.

Configuration Settings for the AES Module

The AES module can be configured for a user-specified key-length, key type (plain text or wrapped key) and chaining modes.

Configuration Settings for the RSA Module

The RSA module can be configured for a user-specified key length and key type: plain text or wrapped keys.

Configuration Settings for the DSA Module

The DSA module can be configured for a user-specified key length.

Configuration Settings for the HASH Module

The HASH module can be configured for a user specified HASH algorithm (depending on the target MCU.)

Configuration Settings for the TDES Module

The TDES module can be configured for a user-specified chaining mode.

Configuration Settings for the Key Installation Module

The Key Installation module can be configured to install the user's encrypted key.

Configuration Settings for the ECC Module

The ECC module can be configured for a user-specified key length and key type.

SCE HAL Module Important Operational Notes and Limitations

SCE HAL Module Operational Notes

Synergy S7 and S5 devices have the SCE7 and therefore support AES, TRNG, RSA, HASH, DSA, ECC and Key Installation.
Synergy S3 devices have the SCE5 and therefore support AES, TRNG, & GHASH. GHASH is supported as part of the AES GCM mode. Key Installation is supported as part of AES GCM, ECB, CTR, XTS, CBC chaining modes. Synergy S3 devices do not support MD5, SHA1/SHA256 HASH functionality.
Synergy S1 devices only support AES and TRNG.
If an unsupported module is added to the project, then a compiler warning will be generated indicating this fact.
All modules support the versionGet API which can be called even before a module is opened.
R_SCE module crypto_api_t::interfaceGet API is provided for use by the Framework layer SF CRYPTO modules.

The InterfaceGet API is used to request a crypto HAL interface. The example below shows usage of this API:

crypto_instance_t         * p_crypto;  /* R_SCE  instance */
void * p_interface = NULL;    /* Declare a pointer to hold the output interface structure object */
crypto_interface_get_param_t     param;
param.hash_type = CRYPTO_TYPE_HASH_256; /* Requesting SHA 256 interface*/
/* It is mandatory for the address of the p_interface pointer be passed to the API */
p_crypto->p_api->interfaceGet(&param, &p_interface);

All crypto APIs may return SSP_ERR_ASSERTION on null pointer input or invalid input parameters. All APIs return error codes documented in sf_crypto_err_t or ssp_err_t which are within the width of the type uint32_t.
Crypto hardware engine does not support reentrancy. When the crypto hardware engine is busy performing a task, any new request will receive a status error code SSP_ERR_CRYPTO_SCE_RESOURCE_CONFLICT.

Endianness configuration parameter usage:

The default mode is big endian where the input and output parameters (example: keys, payload and IV) are required to be in uint32_t data type.
The little endian mode allows the user to have uint8_t/byte array for input and output parameters (example: keys, payload and IV) and they should be cast to (uint32_t *).
The endianness configuration is set at the initialization of the SCE module and remains in effect until the module is closed. Hence all data should be formatted accordingly.

Example:

Select the Big endian mode when the data is in uint32_t and big endian format:

uint32_t test_data[5] = {0x84983E44, 0x1C3BD26E, 0xBAAE4AA1, 0xF95129E5, 0xE54670F1};

Select the Little endian mode when the same data is in byte array format

uint8_t test_data_byte_array[20] =

{0x84, 0x98, 0x3E, 0x44, 0x1C, 0x3B, 0xD2, 0x6E, 0xBA, 0xAE, 0x4A, 0xA1, 0xF9, 0x51, 0x29, 0xE5, 0xE5, 0x46, 0x70, 0xF1};

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)

The format of RSA keys generated by the rsa_api_t::keyCreate API is as follows:

Note: The endianness is the same as that set during SCE initialization.

RSA Key Format:

RSA Public Key Format:

WORD 0 : Public key exponent

WORD 1: Start of RSA modulus

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

RSA Private Key in Plain Text Standard Format:

WORD 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 Plain Text 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 rsa_api_t::keyCreate 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)

SCE HAL Module Limitations

The AES encrypt() and decrypt() functions do not support data padding. These functions operate on data lengths that are multiples of 16 bytes. (Data padding needs to be handled by the user application.) AES GCM mode may require support for authentication data that may not be a multiple of 16 bytes. To support this, zeroPaddingEncrypt() and zeroPaddingDecrypt() function APIs are provided only for the AES GCM mode.
- For AES GCM, when using uint32_t arrays in big endian mode, if the number of bytes of data is not a multiple of 4 (WORD length) it should be zero-padded.
AES encryption/ decryption API with XTS chaining mode supports data input lengths which are multiples of AES block size. Arbitrary input data lengths will work only when the input data is zero-padded in the user application. (Data padding needs to be handled by the user).
The TDES encrypt() and decrypt() functions do not support data padding. These functions operate on data lengths that are multiples of 8 bytes. (Data padding needs to be handled by the user application.)
Disable the unused interfaces in the r_sce module configuration in ISDE properties which will reduce the code memory. This will help in reducing code/text memory size in low memory devices like S5D3 MCUs.

HASH Module - MD5

MD5 requires byte swapping of the final message digest output. Intermediate updates (partial updates) are not required to be byte swapped.
MD5 also requires the length field within the formatted final block to be in big endian format before calling the hash_api_t::hashUpdate API.

Refer to the most recent SSP release notes for the most up-to-date limitations on this module.

Including the SCE HAL Module in an Application

This section describes how to include the SCE HAL 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 Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table.

SCE HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sce_aes_0 AES Driver on r_sce_aes	Threads	New Stack> Driver> Crypto> AES Driver on r_sce_aes
g_sce_arc4_0 ARC4 Driver on r_sce_arc4	Threads	New Stack> Driver> Crypto> ARC4 Driver on r_sce_arc4
g_sce_dsa_0 DSA Driver on r_sce_dsa	Threads	New Stack> Driver> Crypto> DSA Driver on r_sce_dsa
g_sce_ecc_0 ECC Driver on r_sce_ecc	Threads	New Stack> Driver> Crypto> ECC Driver on r_sce_ecc
g_sce_hash_0 HASH Driver on r_sce_hash	Threads	New Stack> Driver> Crypto> HASH Driver on r_sce_hash
g_sce_key_initialization_0 Key Initialization Driver on r_sce_key_initialization	Threads	New Stack> Driver> Crypto> Key Initialization Driver on r_sce_key_initialization
g_sce_rsa_0 RSA Driver on r_sce_rsa	Threads	New Stack> Driver> Crypto> RSA Driver on r_sce_rsa
g_sce_tdes TDES Driver on r_sce_tdes	Threads	New Stack> Driver> Crypto> TDES Driver on r_sce_tdes
g_sce_trng TRNG Driver on r_sce_trng	Threads	New Stack> Driver> Crypto> TRNG Driver on r_sce_trng

When a Crypto HAL module 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.

SCE HAL Module Stack

Configuring the SCE HAL Module

The SCE HAL Module must be configured by the user for the desired operation. 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. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and 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 SSP.

Configuration Settings for the AES HAL Module on r_sce_aes

ISDE Property	Value	Description
Name	g_sce_aes_0	Module name.
Key Length	128, 192, 256 Default: 128	Key length used for encryption/decryption operations by this instance of the driver.
Chaining Mode	ECB, CBC, CTR, GCM, XTS Default: CBC	Block cipher chaining mode used for encryption/decryption operations by this instance of the driver.
Key Format	Plain Text Key, Wrapped Key (Not available for S1 MCU series) Default: Plain Text Key	Key format selection.

Note: The example settings 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 ARC4 HAL Module on r_sce_arc4

ISDE Property	Value	Description
Name (for S7G2, S5D9, S5D5 devices only)	g_sce_arc40	Module name.
Key Length in number of bytes	0	Key length selection.
Key Name, this symbol must be defined as uint8_t array type data in user code	g_arc4_0_key	Key name.

Note: The example settings 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 DSA HAL Module on r_sce_dsa

ISDE Property	Value	Description
Name	g_sce_dsa_0	Module name.
Key Length	(1024, 160), (2048, 224), (2048, 256) Default: (2048, 256)	Key length used for signing/verification operations by this instance of the driver.

Note: The example settings 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 ECC HAL Module on r_sce_ecc

ISDE Property	Value	Description
Name (for S7G2, S5D9, S5D5 devices only)	g_sce_ecc0	Module name.
Key Length	192, 224, 256, 384 Default: 256	Key length used for encryption/decryption operations by this instance of the driver.
Key Format	Plain Text Key, Wrapped Key Default: Plain Text Key	Key format selection.

Note: The example settings 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 HASH Driver on r_sce_hash

ISDE Property	Value	Description
Name (for S7G2, S5D9, S5D5 devices only)	g_sce_hash_0	Module name.
Algorithm	SHA1, MD5, SHA224 SHA256 Default: SHA256	Algorithm used for computing the message digest/hash on the message data.

Note: The example settings 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 RSA HAL Module on r_sce_rsa

ISDE Property	Value	Description
Name	g_sce_rsa_0	Module name.
Key Length	1024, 2048 Default: 2048	Key length used for signing/verification/encryption/decryption operations by this instance of the driver.
Key Format	Plain Text Key, Wrapped Key Default: Plain Text Key	Key format selection.

Note: The example settings 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 TDES HAL Module on r_sce_tdes

ISDE Property	Value	Description
Name	g_sce_tdes_0	Module name.
Chaining Mode	EBC, CBC, CTR Default: CBC	Chaining mode selection.

Note: The example settings 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 TRNG HAL Module on r_sce_trng

ISDE Property	Value	Description
Name	g_sce_trng	Module name.
Max. Attempts	2	Sets the maximum number of attempts when a newly generated random number differs from the previously generated random number.

Note: The example settings 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 Key Installation on r_sce_key_installation

ISDE Property	Value	Description
Name (Not Supported for S1 Series MCUs)	g_sce_key_installation_0	Module name.

Note: The example settings 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 SCE HAL Module in an Application

The SCE Driver on r_sce HAL module makes several APIs available for various cryptographic functions. The steps to use each function are illustrated as follows, but a flow diagram is not provided due to the large number of steps.

The steps in using the SCE Driver on r_sce HAL module in a typical application are:

To use the SCE module:
- Initialize the SCE and the SCE HAL module (R_SCE) using the crypto_api_t::open API through the SCE common driver. This initializes the module as defined in the associated configuration parameters.
  - Note
    Configure the endianness (little-endian or big-endian) for the input /output data for all the HAL APIs. The big-endian mode is configured by default. See the above operational notes for details on endianness configuration.
  - All interfaces supported on the selected MCU are available at run-time by calling the crypto_api_t::interfaceGet API. This is available for use by the Crypto framework.
  - If the crypto_api_t::interfaceGet API function is used by the HAL module, disable the unused interfaces. This will exclude them from the build to save code/text space.
  - If the application is using the Crypto frameworks, disable only the interfaces which will not be used at run-time. Make sure to keep all the used interfaces enabled.
  - If the crypto_api_t::interfaceGet API is not used directly by the HAL application project and if none of the Crypto Framework modules are being used, disable all the interfaces. This will reduce the code/text space significantly.
  - Note that disabling the interfaces will only exclude them from being requested through the crypto_api_t::interfaceGet API function. These interfaces can still be used by the HAL project by including the appropriate module in ISDE.
  - Call the crypto_api_t::open API function before using the crypto_api_t::interfaceGet API.
  - Note
    The open function cannot be called again until the module is closed.
To use the AES functions:
- Initialize the selected AES module with the aes_api_t::open API. This initializes the module as defined in the associated configuration parameters.
  - Note
    AES available key sizes are 128-bit, 192-bit or 256-bit. Chaining modes supported are ECB, CBC, CTR, GCM and XTS.
  - Encrypt data with the aes_api_t::encrypt API.
- Decrypt data with the aes_api_t::decrypt API.
- Generate keys using the aes_api_t::createKey API.
  - Note
    The aes_api_t::createKey API in AES module creates AES wrapped keys. AES plain text keys can be generated with the services of the TRNG module.
- Close the interface instance using the aes_api_t::close API.
  - Note
    Subtle difference exist in GCM operations as follows.
- IV provided for AES GCM operations must be a 96-bit IV formatted to 128-bits.