SA3UL

Table of Contents

• Features Supported In Hardware
• Features Supported In Driver
• Block diagram
  • PSI-L
  • Context Cache
  • Encryption Engine
  • Authentication Engine
  • ECC Aggregator
  • CBASS
  • Context RAM
  • Packet RAM
  • TRNG
  • PKA
• DMA Flow
• SysConfig Features
• Features NOT Supported
• Usage Overview
  • Dependencies
• SA3UL API's Supported
  • API Sequence for CBC abd ECB Algorithms
  • API Sequence for SHA Algorithms
  • API Sequence for HMAC-SHA Algorithms
  • API Sequence for AES-CMAC Algorithms
  • API Sequence for RNG (Random number generation)
  • Opening the SA3UL Driver
  • Ultra lite Security Accelerator
  • AES (Advanced Encryption Standard)
  • SHA (Secure Hash Algorithm)
  • HMAC-SHA (Keyed-Hash Message Authentication Code Secure Hash Algorithm)
  • AES-CMAC (Cipher-based Message Authentication Code)
  • RNG (Random number generation)
  • Closing the SA3UL Driver
• Example Usage
• Directory Structure
• API

The SA3_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 Sa3ul functional specification.

Sa3ul 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 master 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 sa3ul 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

• Sa3ul 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.

sa3ul dma flow

SysConfig Features

• Select Crypto instance, it automatically create sa3ul 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

• SA3UL_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.

SA3UL API's Supported

• SA3UL_init() : Initialize the SA3UL module.
• SA3UL_Params_init() : Initialize a SA3UL_Params structure with default values. Then change the parameters from non-default values as needed.
• SA3UL_open() : Open an instance of the SA3UL module, enable Sa3ul hw engines and initialize dma.
• SA3UL_contextAlloc() : Function to configure secure context.
• SA3UL_contextFree() : Function to free secure context configuration.
• SA3UL_contextProcess() : Function to transfer and receive data buffer.
• SA3UL_rngSetup() : setup the SA3UL RNG module.
• SA3UL_rngRead() : Read random numbers into the output buffer.
• SA3UL_close() : De-initialize the SA3UL instance, disable Sa3ul hw engines and de-initialize dma.
• SA3UL_deinit() : De-Initialize the SA3UL 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 SA3UL module, enable Sa3ul hw engines and initialize dma.
• SA3UL_contextAlloc() : Function to configure secure context.
• SA3UL_contextProcess() : Function to transfer and receive data buffer.
• SA3UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the SA3UL instance, disable Sa3ul 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 SA3UL module, enable Sa3ul hw engines and initialize dma.
• SA3UL_contextAlloc() : Function to configure secure context.
• SA3UL_contextProcess() : Function to transfer and receive data buffer.
• SA3UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the SA3UL instance, disable Sa3ul 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 SA3UL module, enable Sa3ul hw engines and initialize dma.
• Crypto_hmacSha() : This function updates oPad & iPad for HMAC calculation.
• SA3UL_contextAlloc() : Function to configure secure context.
• SA3UL_contextProcess() : Function to transfer and receive data buffer.
• SA3UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the SA3UL instance, disable Sa3ul 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 SA3UL module, enable Sa3ul hw engines and initialize dma.
• Crypto_cmacGenSubKeys() : This function Generate Sub keys for CMAC calculation.
• SA3UL_contextAlloc() : Function to configure secure context.
• SA3UL_contextProcess() : Function to transfer and receive data buffer.
• SA3UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the SA3UL instance, disable Sa3ul hw engines and de-initialize dma and clears context.

API Sequence for RNG (Random number generation)

This sequence to get RNG (Random number generation).

• Crypto_open() : Initializes a Crypto context and Open an instance of the SA3UL module, enable Sa3ul hw engines and initialize dma.
• SA3UL_rngSetup() : setup the SA3UL RNG module.
• SA3UL_rngRead() : Read random numbers into the output buffer.
• Crypto_close() : De-initialize the SA3UL instance, disable Sa3ul hw engines and de-initialize dma and clears context.

Opening the SA3UL Driver

• The application can open a SA3UL instance by calling Crypto_open(). Please note that opening SA3UL driver is taken care by the SysConfig generated code. This function takes an index into the gSa3ulConfig[] array, and the SA3UL parameters data structure. The SA3UL instance is specified by the index of the SA3UL in gSa3ulConfig[]. 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 SA3UL_ContextParams structure, all necessary parameters set to SA3UL_ContextParams variables and allocate sa3ul context by calling SA3UL_contextAlloc(), to get expected result by calling SA3UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa3ul context by calling SA3UL_contextFree().

AES (Advanced Encryption Standard)

• For enabling Sa3ul Aes engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA3UL_ContextParams structure, all necessary parameters set to SA3UL_ContextParams variables and allocate sa3ul context by calling SA3UL_contextAlloc(), to get expected result by calling SA3UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa3ul context by calling SA3UL_contextFree(). For closing sa3ul Aes engine use Crypto_close().

SHA (Secure Hash Algorithm)

• For enabling Sa3ul Sha engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA3UL_ContextParams structure, all necessary parameters set to SA3UL_ContextParams variables and allocate sa3ul context by calling SA3UL_contextAlloc(), to get expected result by calling SA3UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in gSa3ulCtxObj(computedHash) buffer. Close sa3ul context by calling SA3UL_contextFree(). For closing sa3ul Sha engine use Crypto_close().

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

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

AES-CMAC (Cipher-based Message Authentication Code)

• For enabling Sa3ul Aes engine use Crypto_open() and it also do initialize Crypto context, set the ctx parameters using SA3UL_ContextParams structure, all necessary parameters set to SA3UL_ContextParams variables and allocate sa3ul context by calling SA3UL_contextAlloc(), for key1 and key2 call Crypto_cmacGenSubKeys(), to get expected result by calling SA3UL_contextProcess() with input buffer and output buffer as parameters, final output will stored in output buffer. Close sa3ul context by calling SA3UL_contextFree(). For closing sa3ul Sha engine use Crypto_close().

RNG (Random number generation)

• For enabling SA3UL RNG use Crypto_open(), Setup rng module by calling SA3UL_rngSetup(), to get 128 bit random number by calling SA3UL_rngRead() with output buffer as parameters, final 128 bit random number will stored in output buffer. For disabling SA3UL RNG use Crypto_close().

Closing the SA3UL Driver

• The application can Close a SA3UL instance by calling Crypto_close(), it close the sa3ul instance passed by the user.

Example Usage

Include the below file to access the SA3UL SHA APIs

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

sa3ul_sha Example

 
    int32_t             status;
    uint8_t             sha512sum[64];
    Crypto_Handle       shaHandle;
    SA3UL_ContextParams ctxParams;
 
    /* Init SA */
    SA3UL_init();
 
    /* Open SHA instance */
    shaHandle = Crypto_open(&gCryptoSha512Context);
 
    /* Configure secure context */
    ctxParams.opType    = SA3UL_OP_AUTH;
    ctxParams.hashAlg   = SA3UL_HASH_ALG_SHA2_512;
    ctxParams.inputLen  = sizeof(gCryptoSha512TestBuf);
    gCtxObj.totalLengthInBytes = sizeof(gCryptoSha512TestBuf);
    status = SA3UL_contextAlloc(gCryptoSha512Context.drvHandle,&gCtxObj,&ctxParams);
 
    /* Perform SHA operation */
    status = SA3UL_contextProcess(&gCtxObj,&gCryptoSha512TestBuf[0], sizeof(gCryptoSha512TestBuf), sha512sum);
 
    /* Free the secure context configuration */
    SA3UL_contextFree(&gCtxObj);
 
    /* Close SHA instance */
    status = Crypto_close(shaHandle);
 
    /*deinit SA */
    SA3UL_deinit();
 
    /* Kill warning of variable set but not used */
    (void) status;
 

Include the below file to access the SA3UL AES CBC APIs

 
#include<stdio.h>
#include <security/crypto.h>
#include <security/crypto/sa3ul/sa3ul.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 (SA3UL_CACHELINE_ALIGNMENT)));
 
/* Context Object */
SA3UL_ContextObject  gSa3ulCtxObj __attribute__ ((aligned (SA3UL_CACHELINE_ALIGNMENT)));
 

sa3ul_aes_cbc Example

    int32_t             status;
    Crypto_Handle       aesHandle;
    SA3UL_ContextParams ctxParams;
 
    aesHandle = Crypto_open(&gCryptoAesCbcContext);
 
    /* Configure secure context */
    ctxParams.opType       = SA3UL_OP_ENC;
    ctxParams.encAlg       = SA3UL_ENC_ALG_AES;
    ctxParams.encMode      = SA3UL_ENC_MODE_CBC;
    ctxParams.encKeySize   = SA3UL_ENC_KEYSIZE_256;
    ctxParams.encDirection = SA3UL_ENC_DIR_ENCRYPT;
    memcpy( &ctxParams.key[0], &gCryptoAesCbc256Key[0], SA3UL_MAX_KEY_SIZE_BYTES);
    memcpy( &ctxParams.iv[0], &gCryptoAesCbc256Iv[0], SA3UL_MAX_IV_SIZE_BYTES);
    ctxParams.inputLen = sizeof(gCryptoAesCbc256InputBuf);
    gSa3ulCtxObj.totalLengthInBytes = sizeof(gCryptoAesCbc256InputBuf);
 
    SA3UL_Config     *config  = NULL;
    config = &gSa3ulConfig[0];
    config->attrs->secure = 1;
    config->attrs->priv   = 1;
 
    /* Function to configure secure context */
    status = SA3UL_contextAlloc(gCryptoAesCbcContext.drvHandle, &gSa3ulCtxObj, &ctxParams);
 
    /* Encryption */
    /* Function to transfer and receive data buffer */
    status = SA3UL_contextProcess(&gSa3ulCtxObj,&gCryptoAesCbc256InputBuf[0], sizeof(gCryptoAesCbc256InputBuf), gCryptoAesCbc256EncResultBuf);
 
    /* Function to free secure context configuration*/
    status = SA3UL_contextFree(&gSa3ulCtxObj);
 
    /* 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/sa3ul	Contains Sa3ul driver files
source/security/crypto/pka	Contains Pka driver files
examples/security	Contains all Security examples

API

• APIs for SA3UL