The SA2_UL subsystem is designed to provide a generic cryptographic acceleration for different use cases such as secure boot, secure content, key exchange etc.

Features Supported In Hardware

Compatible with ARM Trustzone operations
Support non-secure authentication
Crypto function library for software acceleration
- AES operation
- SHA2-224, 256, 512 operation
Block data encryption supported via hardware cores
- AES with 128, 192 and 256 bits key support
Data encryption modes support
- ECB (Electronic code book)
- CBC (Cipher block chaining)
- CFB (Cipher feedback)
- OFB (Output feedback)
- F8 (3GPP confidentiality and integrity algorithms)
- CTR (Counter)
- CBC-MAC (Cipher block chaining - Message authentication code)
- CCM (Counter with CBC-MAC)
- GCM (Galois counter mode)
- GMAC (Galois Message Authentication Code)
Public Key accelerator with Elliptic Curve Cryptography (ECC)
- High performance Public Key Accelerator (PKA) for large vector math operation
Supports modulus size up to 4096-bits
- A dual LNME module for Montgomery multiplication and exponentiation
- Prime field GF(p) ECC point addition, doubling and multiplication for all NIST (FIPS 186-3) recommended prime curves
- Binary field GF(2m) ECC point addition, doubling and multiplication.
- Support public key computations such as RSA (4k).
- Single call operations for RSA up to 4k and ECC (Prime NIST curves) signing and verification
- Supports Brainpool, NIST and Curve25519 ECC curves
- Authentication supported via following hardware cores
- SHA2-224
- SHA2-256
- SHA2-512
Keyed HMAC operation via hardware core
- HMAC using SHA2-224, SHA2-256 and SHA2-512
- Support for truncated authentication tag
True Random number generator (TRNG)
- True (not pseudo) random number generator
- FIPS 140-1 compliant
- Non-deterministic noise source for generating keys, IV etc
Context cache module to auto fetch security context
- Cache limited number (up to 4) contexts for low cost
- Auto-fetch security context based on current state of engine
- Option to allow storage of security context within engine for high performance connections
Auto evict security context based on unavailability of space within context cache
Fully pipelined engines for parallel processing
DMA support for Cryptographic acceleration

Features Supported In Driver

Encryption and authentication
Crypto function library for Security acceleration
- Secure hash algorithms
  - SHA256, SHA512
- Hash-based message authentication code
  - HMAC SHA-256, HMAC SHA-512, HMAC SHA1
- Advanced encryption standard
  - AES-CBC(128/256)(Cipher Block Chaining)
  - AES-ECB(128/256)(Electronic Code Book)
  - AES-CMAC(128/256)(Cipher-based Message Authentication Code)
Supports random number generator(RNG)
- Keys and initialization values (IVs) for encryption
- Keys for keyed MAC algorithms
- Private keys for digital signature algorithms
- Values to be used in entity authentication mechanisms
- PIN and password generation
Supports public-key accelerator(PKA)
- Supports up to 4K bit key
- Supports Raw operations
- Supports PKA RSA encryption and decryption
- Supports RSA signing and verification operations
- Supports ECDSA signing and verification operations
  - P-256 and P-384 curves

Block diagram

Note: This block diagram referred from Sa2ul functional specification.

Sa2ul block diagram

PSI-L

The PSI-L(Packet Streaming Interface Link) is used to transfer words of packet data and control information between two peer entities via direct connection. There are credits used for flow control to guarantee that blocking does not occur between threads. Multiple packet transfers can be ongoing simultaneously across a PSI-L interface each on a separate logical thread but all sharing a single data path through time division multiplexing. Each packet which is transferred is accompanied by a destination thread ID which indicates the logical destination thread to which the packet is being sent.
SA2_UL accepts packets from Streaming interface (PSI-L) port with 8 ingress threads where each thread is a UDMA Tx channel. Each packet destined to SA2_UL must be prefixed with three extended packet info words (software words) that hold information about security context that is required to uniquely identify security connection and associated security parameters. The coherency is expected to be maintained by the UDMA-P.

Context Cache

Context cache fetch process involves two primary levels of security checks for the fetch to be successful. The first level of check is for SA2_UL to translate the security attributes from the incoming packets to the attributes on the VBUSP DMA host interface. The firewall IP near the external memory will then check these attributes before allowing access. The second level check is done after SA2_UL fetches and caches the context. SA2_UL compares the security attributes from the packets and the attributes stored inside the security context. If the attributes satisfy the check requirements, the context is used by the encryption and/or authentication engine, otherwise SA2_UL does not process the packet (packet will pass through) and a security exception will be generated.

Encryption Engine

It carries out the task of encrypting/decrypting payload from desired offset using hardware encryption cryptographic cores. Encryption engine has AES core, 3DES core and Galois multiplier core which is operated in conjunction with MCE (mode control engine). Mode control engine implements various encryption modes like ECB, CBC, CTR, OFB, GCM etc.

Authentication Engine

It caters the requirement of providing integrity protection. Authentication engine is equipped with SHA1 core, MD5 core, SHA2 core (up to 512 bits) to support keyed (HMAC) and non-keyed hash calculation.

ECC Aggregator

To increase functional and system reliability the memories (for example, FIFOs, queues, SRAMs and others) in many device modules and subsystems are protected by error correcting code (ECC). This is accomplished through an ECC aggregator.

CBASS

CBASS is the interconnection technique used to communicate between modules and subsystems in the device for any memory map accesses.

Context RAM

Each engine/subsystem has a Context RAM to store the control information pertaining to the logical connection. The context RAM holds the information like Keys, IV, partial data etc. for each active context. The SA2_UL subsystem provides the option to store 4 contexts on-chip. Context RAM is coupled with Context Cache module to fetch the context information from external memory to populate the active context on real-time demand basis.

Packet RAM

Packet RAM used to store Chunks of packets for processing sa2ul operations normally size of packet RAM is 2 banks (1KB or 2 chunks).

TRNG

TRNG (True Random number generator) used to create initialization vector required for certain encryption modes. The random numbers are accessible to the host in four 32-bit registers allowing 128-bit random number to be read with a single burst read.

PKA

The PKA(Public Key Accelerator) module provides a high-performance public key engine to accelerate the large vector math processing that is required for Public Key computations. It also includes hw acceleration for Elliptic Curve Cryptography such as binary field ECC point addition, inversion, multiplication and ECC prime field point addition, inversion and multiplication.

DMA Flow

Sa2ul Uses PKTDMA, the PKTDMA module supports the transmission and reception of various packet types. The PKTDMA is architected to facilitate the segmentation and reassembly of KSLC DMA data structure compliant packets to/from smaller data blocks that are natively compatible with the specific requirements of each connected peripheral.

sa2ul dma flow

SysConfig Features

Select Crypto instance, it automatically create sa2ul and Dma with PKTDMA instances.
We can not create more then one instances due to Dma limitations.

Features NOT Supported

Context fetch using the MMR is no longer supported to ensure data security.

Usage Overview

Dependencies

SA2UL_ContextParams should be populated for intended cryptographic operation. Please see this Example Usage for AES and SHA.
DMA initialization is required.
DMA Tx and Rx Channels need to be initialized. Please refer DMA Flow.

SA2UL API's Supported

SA2UL_init() : Initialize the SA2UL module.
SA2UL_Params_init() : Initialize a SA2UL_Params structure with default values. Then change the parameters from non-default values as needed.
SA2UL_open() : Open an instance of the SA2UL module, enable Sa2ul hw engines and initialize dma.
SA2UL_contextAlloc() : Function to configure secure context.
SA2UL_contextFree() : Function to free secure context configuration.
SA2UL_contextProcess() : Function to transfer and receive data buffer.
SA2UL_close() : De-initialize the SA2UL instance, disable Sa2ul hw engines and de-initialize dma.
SA2UL_deinit() : De-Initialize the SA2UL module.

API Sequence for CBC abd ECB Algorithms

This sequence performs Encryption and decryption operations for AES-CBC/ECB algorithms. Supported key lengths are 128 and 256 bit.

Crypto_open() : Initializes a Crypto context and Open an instance of the SA2UL module, enable Sa2ul hw engines and initialize dma.
SA2UL_contextAlloc() : Function to configure secure context.
SA2UL_contextProcess() : Function to transfer and receive data buffer.
SA2UL_contextFree() : Function to free secure context configuration.
Crypto_close() : De-initialize the SA2UL instance, disable Sa2ul hw engines and de-initialize dma and clears context.

API Sequence for SHA Algorithms

This sequence performs SHA-512 and SHA-256.

Crypto_open() : Initializes a Crypto context and Open an instance of the SA2UL module, enable Sa2ul hw engines and initialize dma.
SA2UL_contextAlloc() : Function to configure secure context.
SA2UL_contextProcess() : Function to transfer and receive data buffer.
SA2UL_contextFree() : Function to free secure context configuration.
Crypto_close() : De-initialize the SA2UL instance, disable Sa2ul hw engines and de-initialize dma and clears context.

API Sequence for HMAC-SHA Algorithms

This sequence performs HMAC SHA-512, SHA-256 and SHA1.

Crypto_open() : Initializes a Crypto context and Open an instance of the SA2UL module, enable Sa2ul hw engines and initialize dma.
Crypto_hmacSha() : This function updates oPad & iPad for HMAC calculation.
SA2UL_contextAlloc() : Function to configure secure context.
SA2UL_contextProcess() : Function to transfer and receive data buffer.
SA2UL_contextFree() : Function to free secure context configuration.
Crypto_close() : De-initialize the SA2UL instance, disable Sa2ul hw engines and de-initialize dma and clears context.

API Sequence for AES-CMAC Algorithms

This sequence performs AES CMAC-128 and CMAC-256.

Crypto_open() : Initializes a Crypto context and Open an instance of the SA2UL module, enable Sa2ul hw engines and initialize dma.
Crypto_cmacGenSubKeys() : This function Generate Sub keys for CMAC calculation.
SA2UL_contextAlloc() : Function to configure secure context.
SA2UL_contextProcess() : Function to transfer and receive data buffer.
SA2UL_contextFree() : Function to free secure context configuration.
Crypto_close() : De-initialize the SA2UL instance, disable Sa2ul hw engines and de-initialize dma and clears context.

Opening the SA2UL Driver

The application can open a SA2UL instance by calling Crypto_open(). Please note that opening SA2UL driver is taken care by the SysConfig generated code. This function takes an index into the gSa2ulConfig[] array, and the SA2UL parameters data structure. The SA2UL instance is specified by the index of the SA2UL in gSa2ulConfig[]. Calling Crypto_open() second time with the same index previously passed to Crypto_open() will result in an error. Re-use the index if the instance is closed via Crypto_close().

Ultra lite Security Accelerator

Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), to get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree().

AES (Advanced Encryption Standard)

For enabling Sa2ul Aes engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), to get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Aes engine use Crypto_close().

SHA (Secure Hash Algorithm)

For enabling Sa2ul Sha engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), to get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in gSa2ulCtxObj(computedHash) buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

HMAC-SHA (Keyed-Hash Message Authentication Code Secure Hash Algorithm)

For enabling Sa2ul Sha engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), for ipad and opad call Crypto_hmacSha(), to get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in computedHash buffer (present in Sa2ul Ctx Obj). Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

AES-CMAC (Cipher-based Message Authentication Code)

For enabling Sa2ul Aes engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), for key1 and key2 call Crypto_cmacGenSubKeys(), to get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

Closing the SA2UL Driver

The application can Close a SA2UL instance by calling Crypto_close(), it close the sa2ul instance passed by the user.

Example Usage

Include the below file to access the SA2UL SHA APIs

 
#include<stdio.h>
#include <security/security_common/drivers/crypto/crypto.h>
#include <security/security_common/drivers/crypto/sa2ul/sa2ul.h>
 
Crypto_Context gCryptoSha512Context;
static uint8_t gCryptoSha512TestBuf[9] = {"abcdefpra"};
SA2UL_ContextObject  gCtxObj;

sa2ul_sha Example

 
    int32_t             status;
    uint8_t             sha512sum[64];
    Crypto_Handle       shaHandle;
    SA2UL_ContextParams ctxParams;
 
    /* Init SA */
    SA2UL_init();
 
    /* Open SHA instance */
    shaHandle = Crypto_open(&gCryptoSha512Context);
 
    /* Configure secure context */
    ctxParams.opType    = SA2UL_OP_AUTH;
    ctxParams.hashAlg   = SA2UL_HASH_ALG_SHA2_512;
    ctxParams.inputLen  = sizeof(gCryptoSha512TestBuf);
    gCtxObj.totalLengthInBytes = sizeof(gCryptoSha512TestBuf);
    status = SA2UL_contextAlloc(gCryptoSha512Context.drvHandle,&gCtxObj,&ctxParams);
 
    /* Perform SHA operation */
    status = SA2UL_contextProcess(&gCtxObj,&gCryptoSha512TestBuf[0], sizeof(gCryptoSha512TestBuf), sha512sum);
 
    /* Free the secure context configuration */
    SA2UL_contextFree(&gCtxObj);
 
    /* Close SHA instance */
    status = Crypto_close(shaHandle);
 
    /*deinit SA */
    SA2UL_deinit();
 
    /* Kill warning of variable set but not used */
    (void) status;
 

Include the below file to access the SA2UL AES CBC APIs

 
#include<stdio.h>
#include <security/security_common/drivers/crypto/crypto.h>
#include <security/security_common/drivers//crypto/sa2ul/sa2ul.h>
 
/* input or output length*/
#define APP_CRYPTO_AES_CBC_256_INOUT_LENGTH           (16U)
/* Aes max key length*/
#define APP_CRYPTO_AES_CBC_256_MAX_KEY_LENGTH         (32U)
/* Aes max IV length*/
#define APP_CRYPTO_AES_CBC_256_MAX_IV_LENGTH          (16U)
/* Aes key length in bites*/
#define APP_CRYPTO_AES_CBC_256_KEY_LENGTH_IN_BITS     (256U)
/* Alignment */
#define APP_CRYPTO_AES_CBC_ALIGNMENT                  (128U)
 
/* input buffer for encryption or decryption */
static uint8_t gCryptoAesCbc256InputBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] =
{
    0x81, 0xEA, 0x5B, 0xA4, 0x69, 0x45, 0xC1, 0x70,
    0x5F, 0x6F, 0x89, 0x77, 0x88, 0x68, 0xCC, 0x67
};
 
/* The AES encryption algorithm encrypts and decrypts data in blocks of 128 bits. It can do this using 128-bit, 192-bit, or 256-bit keys */
static uint8_t gCryptoAesCbc256Key[APP_CRYPTO_AES_CBC_256_MAX_KEY_LENGTH] =
{
    0x33, 0xA3, 0x66, 0x46, 0xFE, 0x56, 0xF7, 0x0D,
    0xC0, 0xC5, 0x1A, 0x31, 0x17, 0xE6, 0x39, 0xF1,
    0x82, 0xDE, 0xF8, 0xCA, 0xB5, 0xC0, 0x66, 0x71,
    0xEE, 0xA0, 0x40, 0x7C, 0x48, 0xA9, 0xC7, 0x57
};
 
/* initialization vector (IV) is an arbitrary number that can be used along with a secret key for data encryption/decryption. */
static uint8_t gCryptoAesCbc256Iv[APP_CRYPTO_AES_CBC_256_MAX_IV_LENGTH] =
{
    0x7C, 0xE2, 0xAB, 0xAF, 0x8B, 0xEF, 0x23, 0xC4,
    0x81, 0x6D, 0xC8, 0xCE, 0x84, 0x20, 0x48, 0xA7
};
 
/* Encryption output buf */
uint8_t     gCryptoAesCbc256EncResultBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] __attribute__ ((aligned (APP_CRYPTO_AES_CBC_ALIGNMENT)));
/* Decryption output buf */
uint8_t     gCryptoAesCbc256DecResultBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] __attribute__ ((aligned (APP_CRYPTO_AES_CBC_ALIGNMENT)));
 
/* Context memory */
static Crypto_Context gCryptoAesCbcContext __attribute__ ((aligned (SA2UL_CACHELINE_ALIGNMENT)));
 
/* Context Object */
SA2UL_ContextObject  gSa2ulCtxObj __attribute__ ((aligned (SA2UL_CACHELINE_ALIGNMENT)));
 

sa2ul_aes_cbc Example

    int32_t             status;
    Crypto_Handle       aesHandle;
    SA2UL_ContextParams ctxParams;
 
    aesHandle = Crypto_open(&gCryptoAesCbcContext);
 
    /* Configure secure context */
    ctxParams.opType       = SA2UL_OP_ENC;
    ctxParams.encAlg       = SA2UL_ENC_ALG_AES;
    ctxParams.encMode      = SA2UL_ENC_MODE_CBC;
    ctxParams.encKeySize   = SA2UL_ENC_KEYSIZE_256;
    ctxParams.encDirection = SA2UL_ENC_DIR_ENCRYPT;
    memcpy( &ctxParams.key[0], &gCryptoAesCbc256Key[0], SA2UL_MAX_KEY_SIZE_BYTES);
    memcpy( &ctxParams.iv[0], &gCryptoAesCbc256Iv[0], SA2UL_MAX_IV_SIZE_BYTES);
    ctxParams.inputLen = sizeof(gCryptoAesCbc256InputBuf);
    gSa2ulCtxObj.totalLengthInBytes = sizeof(gCryptoAesCbc256InputBuf);
 
    /* Function to configure secure context */
    status = SA2UL_contextAlloc(gCryptoAesCbcContext.drvHandle, &gSa2ulCtxObj, &ctxParams);
 
    /* Encryption */
    /* Function to transfer and receive data buffer */
    status = SA2UL_contextProcess(&gSa2ulCtxObj,&gCryptoAesCbc256InputBuf[0], sizeof(gCryptoAesCbc256InputBuf), gCryptoAesCbc256EncResultBuf);
 
    /* Function to free secure context configuration*/
    status = SA2UL_contextFree(&gSa2ulCtxObj);
 
    /* Close AES instance */
    status = Crypto_close(aesHandle);
 
    /* Kill warning of variable set but not used */
    (void) status;
 
    return;

Directory Structure

Given below is a overview of the directory structure to help you navigate the Crypto structure.

Folder/Files	Description
source/security/crypto	Contains Crypto driver files
source/security/crypto/sa2ul	Contains Sa2ul driver files
source/security/crypto/pka	Contains Pka driver files
examples/security	Contains all Security examples

API

APIs for SA2UL

Table of Contents