SA3UL

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)

  • 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

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.

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

sa3ul_sha Example

Include the below file to access the SA3UL AES CBC APIs

sa3ul_aes_cbc Example

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

examples/security

Contains all Security examples

API

  • SECURITY_SA3UL_MODULE