24. SECURITY

24.1 Introduction

SP7021 supports AES / RSA / HASH algorithms in security block. The Security IP is used to speed up AES / RSA / HASH related operations and reduce CPU overhead. The Security IP features are useful in applications that require AES / RSA / HASH operation.

Encryption techniques are usually divided into "symmetric", "asymmetric" and a special "Hash" algorithm.
Symmetric encryption algorithm: Symmetric encryption uses the same key for encryption and decryption. Both parties to the information need to know the key and the encryption and decryption algorithm in advance and their keys are the same, and then the data is encrypted and decrypted. Symmetric encryption algorithms are used to encrypt information such as sensitive data.
Asymmetric encryption algorithm: Asymmetric encryption is not the same key used for encryption and decryption. There are usually two keys, called "public key" and "private key". They must be paired, otherwise they cannot be opened. Encrypt the file. Both sides A and B send a stack of keys in advance, then A sends its own public key to B, and B sends its own public key to A. If A wants to send a message to B, it needs to use B first. The public key encrypts the message and sends it to the B end. At this time, the B end decrypts the message with its own private key. The same is true when B sends a message to A.
Hash algorithm: Hash algorithm, also known as hash function, is a one-way encryption algorithm. In information security technology, it is often necessary to verify the integrity of a message. A hash function provides this service, which produces fixed-length output for input messages of different lengths. This fixed length output is called the "hash" or "message digest" of the original input message. The hash algorithm does not count as an encryption algorithm because the result is irreversible. Since it is irreversible, it is of course not used for encryption, but for signature.

The Security IP include below features.

AES (Advanced Encryption Standard):

Support encryption and decryption.
Support key length: 128bit, 192bit and 256bit.
Support mode: ECB, CBC and CTR.

RSA: Issued by RSA company.

Support modular exponentiation.
Support data length: 256/512/1024/2048 bit.

HASH:

Support MD5.
Support GHASH.
Support SHA3-224, SHA3-256, SHA3-384 and SHA3-512 modes.

The Security block control registers locate at RGST Table Group 84 and 85 which memory map in 0x9C002A00~0x9C002AFF.

24.2 Function Diagram

The function diagram of Security block is shown in Figure 24-1.

Figure 24-1 Security Functional Blocks

REG_CTL: CPU can configure registers in this module through Register Bus to configure function in Security IP and deal with interrupt related issue.
AES_ENDEC: AES encryption and decryption, including DMA, Descriptor, block algorithm and core algorithm.
RSA_ENDEC: RSA includes DMA, RSA Complementation processing, modular exponentiation and modular multiplication algorithm.
HASH: HASH module includes DMA, Descriptor, GHASH algorithm, MD5 algorithm and SHA3 algorithm.
DMA: DMA Module is used to get or write back data for encryption/decryption according to the configuration info in register file.
Auto DMA: Auto DMA Module is used to get or write back TRB (Transfer Request Block) data or according to the configuration info in register file. One TRB contain the configuration info in a DMA operation.

24.3 Data Structure

Defined two rings for each type of transfer: One command ring for SW to put schedule for controller, which is read only for controller. One event ring for HW to report the status of the transfers SW scheduled, SW should not modify this ring after it started.

Command Ring

Figure 24-2 Command Ring Data Structure

CRCR: Command Ring Control Register, include the pointer of the command ring and some control/status.

TRB: Transfer Request Block: Each TRB for one DMA transfer. SW can create multiple TRB segments in one ring, the last TRB of a segment must be link TRB (describes later).

Event Ring

Figure 24-3 Event Ring Data Structure

ERBAR: Event Ring Base Address Register: include the pointer for the address of the event ring.

ERDPR: Event Ring De-queue pointer Register: indicates the SW is process this TRB, HW will not write over this address.

TRB: Transfer Request Block.

TRB Structure

Figure 24-4 TRB Structure

Parameter for AES

Figure 24-5 AES Structure

Parameter for HASH

Figure 24-6 HASH Structure

Structure Parameters:

Name	Bits	Description
C/C'	1	Cycle bits. indicates the current cycle of the ring
TC	1	Toggle Cycle bit. Used in link TRB only. Indicates the cycle bits will be toggle in next segment.
IOC	1	Interrupt On Complete. when this bit is set, controller will set an interrupt after this TRB is transmitted.
CC	1	Completion Code. 0 Invalid Indicates this field has not been updated1 Success indicates the transfer is successfully completed
TYPE	4	TRB type:0x1: Normal. Normal TRB used in command ring.0x2: Link. Link TRB to link to command ring segments0x3: Event. Reserved
SIZE	16	Plain text size in bytes. indicates the read/write data bytes of this TRB. 0 means 0 length data.
SPTR	32	Source data pointer(depend on ENDC) or For link TRB indicates the next segment address.
DPTR	32	Destination data pointer (depend on ENDC).
IPTR	32	Initial Vector/Counter (IV/ICB) pointer
KPTR	32	AES only. indicates the key pointer.
HPTR	32	GHASH only. indicates the subkey pointer
NK	8	AES only. Key Length(Nk) , only support 4(128bit) ,6(192bit),8(256bit)
M	8	Only for CTR to indicate the increase way(inc(2**M)), when m=5 means inc32 which for GCTR of GCM.
D	2	GHASH only. Output hash length(d)
ENDC	1	AES only. 0: encrypt 1: decrypt
MODE	7	AES: 0x0 : ECB 0x1:CBC 0x2 : GCTRHASH: 0x0 : MD5 0x1 SHA3 0x2 : GHASH

24.4 Ring Operation

Ring Empty

For command ring, the HW will implement an internal Current Cycle State(CCS). The ring is empty when CCS != TRB.C. The initial value of CCS is RCS in CRCR register. When ever a link TRB with TC bit set is read in, the CCS toggles. For event ring, this bit is always 0.

Ring Full

The event ring will be full if HW has and TRB to write and the next TRB address reaches the de-queue pointer. For command ring, the SW can read the CRCR register for the current TRB address which HW is process.

Command Ring Size

SW can change the command ring size to any value even when the ring is running. To do this just link the new TRB or TRB segment to the ring. The cycle bits of each TRB should be set to the ring value.

24.5 Security Block Interrupts

The security block interrupt events are connected to the same interrupt vector, please refer to figure 24-7. These events generate an interrupt if the corresponding "Enable Control Bit" is set.

Figure 24-7 Security Interrupt Tree

AES_CRD interrupt is issued when AES Command Ring Empty and AES_CRD_IE is set to 1.
HASH_CRD interrupt is issued when HASH Command Ring Empty and HASH_CRD_IE is set to 1.
AES_TRB interrupt is issued when AES TRB done , AES_TRB_IE is set to 1 and IOC is set to 1.
HASH_TRB interrupt is issued when HASH TRB done ,HASH_TRB_IE is set to 1 and IOC is set to 1.
AES_ERF interrupt is issued when AES Event Ring Full and AES_ERF_IE is set to 1 .
HASH_ERF interrupt is issued when HASH Event Ring Full and HASH_ERF_IE is set to 1.
AES_DMA interrupt is issued when AES DMA finish and AES_DMA_IE is set to 1.
HASH_DMA interrupt is issued when HASH DMA finish and HASH_DMA_IE is set to 1.
RSA_DMA interrupt is issued when RSA DMA finish and RSA_DMA_IE is set to 1.

24.6 Registers Map

24.6.1 Registers Memory Map

Address	Group&No.	Register Name	Register Description
0x9C002A00	G84.0	AESDMACS	AES DMA Control Status register
0x9C002A04	G84.1	AESSPTR	AES Source Data pointer
0x9C002A08	G84.2	AESDPTR	AES Destination Data pointer
0x9C002A0C	G84.3	AESPAR0	AES Dma Parameter 0
0x9C002A10	G84.4	AESPAR1	AES Dma Parameter 1
0x9C002A14	G84.5	AESPAR2	AES Dma Parameter 2
0x9C002A18	G84.6	HASHDMACS	HASH DMA Control Status register
0x9C002A1C	G84.7	HASHSPTR	HASH Source Data pointer
0x9C002A20	G84.8	HASHDPTR	HASH Destination Data pointer
0x9C002A24	G84.9	HASHPAR0	HASH Dma Parameter 0
0x9C002A28	G84.10	HASHPAR1	HASH Dma Parameter 1
0x9C002A2C	G84.11	HASHPAR2	HASH Dma Parameter 2
0x9C002A30	G84.12	RSADMACS	RSA DMA Control Status register
0x9C002A34	G84.13	RSASPTR	RSA Source Data pointer
0x9C002A38	G84.14	RSADPTR	RSA Destination Data pointer
0x9C002A3C	G84.15	RSAPAR0	RSA Dma Parameter 0
0x9C002A40	G84.16	RSAPAR1	RSA Dma Parameter 1
0x9C002A44	G84.17	RSAPAR2	RSA Dma Parameter 2
0x9C002A48	G84.18	RSAPAR3	RSA Dma Parameter 3
0x9C002A4C	G84.19	RSAPAR4	RSA Dma Parameter 4
0x9C002A50	G84.20	RSAPAR5	RSA Dma Parameter 5
0x9C002A54	G84.21	AESDMA_CRCR	AES DMA Command Ring Control Register
0x9C002A58	G84.22	AESDMA_ERBAR	AES DMA Event Ring Base Address Register
0x9C002A5C	G84.23	AESDMA_ERDPR	AES DMA Event Ring De-queue Pointer Register
0x9C002A60	G84.24	AESDMA_RCSR	AES DMA Ring Control and Status Register
0x9C002A64	G84.25	AESDMA_RTR	AES DMA Ring Trig Register
0x9C002A68	G84.26	HASHDMA_CRCR	HASH DMA Command Ring Control Register
0x9C002A6C	G84.27	HASHDMA_ERBAR	HASH DMA Event Ring Base Address Register
0x9C002A70	G84.28	HASHDMA_ERDPR	HASH DMA Event Ring De-queue Pointer Register
0x9C002A74	G84.29	HASHDMA_RCSR	HASH DMA Ring Control and Status Register
0x9C002A78	G84.30	HASHDMA_RTR	HASH DMA Ring Trig Register

Address	Group&No.	Register Name	Register Description
0x9C002A80	G85.0	VERSION	SEC IP Version
0x9C002A84	G85.1	SECIE	Interrupt Enable
0x9C002A88	G85.2	SECIF	Interrupt Flag

24.6.2 Registers Description

RGST Table Group 84 Security DMA Control Registers

84.0 AES DMA Control Status register (AESDMACS)

Address: 0x9C002A
Reset: 0x0

Field Name	Bit	Access	Description
SIZE	31:16	RW	DMA Transfer Length
Reserved	15:1	RO	RESERVED
EN	0	RU	DMA Enable It will be auto-clear to 0 when DMA finished

84.1 AES Source Data pointer (AESSPTR)
Address: 0x9C002A04
Reset: 0x0

Field Name	Bit	Access	Description
SPTR	31:0	RW	Source Pointer must be 32B aligned

84.2 AES Destination Data pointer (AESDPTR)
Address: 0x9C002A08
Reset: 0x0

Field Name	Bit	Access	Description
DPTR	31:0	RW	Destination Pointer must be 32B aligned

84.3 AES Dma Parameter 0 (AESPAR0)
Address: 0x9C002A0C
Reset: 0x0

Field Name	Bit	Access	Description
CNT M	31:24	RW	Counter Increment Part For instance , GCTR use m=32(inc32)
NK	23:16	RW	Key Length Only support 4,6,8
Reserved	15:8	RO	RESERVED
ENDEC	7	RW	En/Decrypt 0: encrypt 1: decrypt
MODE	6:0	RW	MODE 0x0: AES 0x1: ECB 0x2: CBC Others: Reserved

84.4 AES Dma Parameter 1 (AESPAR1)
Address: 0x9C002A10
Reset: 0x0

Field Name	Bit	Access	Description
IPTR	31:0	RW	IV/ICB Pointer

84.5 AES Dma Parameter 2 (AESPAR2)
Address: 0x9C002A14
Reset: 0x0

Field Name	Bit	Access	Description
KPTR	31:0	RW	Key Pointer

84.6 HASH DMA Control Status register (HASHDMACS)
Address: 0x9C002A18
Reset: 0x0

Field Name	Bit	Access	Description
SIZE	31:16	RW	DMA Transfer Length
Reserved	15:1	RO	RESERVED
EN	0	RU	DMA Enable It will be auto-clear to 0 when DMA finished

84.7 HASH Source Data pointer (HASHSPTR)
Address: 0x9C002A1C
Reset: 0x0

Field Name	Bit	Access	Description
SPTR	31:0	RW	Source Address must be 32B aligned

84.8 HASH Destination Data pointer (HASHDPTR)
Address: 0x9C002A20
Reset: 0x0

Field Name	Bit	Access	Description
DPTR	31:0	RW	Destination Address must be 32B aligned

84.9 HASH Dma Parameter 0 (HASHPAR0)
Address: 0x9C002A24
Reset: 0x0

Field Name	Bit	Access	Description
Reserved	31:18	RO	RESERVED
D	17:16	RW	Output Hash Length SHA3 Only 0x0: 224 0x1: 256 0x2: 384 0x3: 512
Reserved	15:7	RO	RESERVED
MODE	6:0	RW	MODE 0x0: MD5 0x1: SHA3 0x2: GHASH Others:reserved

84.10 HASH Dma Parameter 1 (HASHPAR1)
Address: 0x9C002A28
Reset: 0x0

Field Name	Bit	Access	Description
IPTR	31:0	RW	IV pointer

84.11 HASH Dma Parameter 2 (HASHPAR2)
Address: 0x9C002A2C
Reset: 0x0

Field Name	Bit	Access	Description
HPTR	31:0	RW	Subkey Pointer GHASH only

84.12 RSA DMA Control Status register (RSADMACS)
Address: 0x9C002A30
Reset: 0x0

Field Name	Bit	Access	Description
SIZE	31:16	RW	DMA Transfer Length
Reserved	15:1	RO	RESERVED
EN	0	RU	DMA Enable It will be auto-clear to 0 when DMA finished

84.13 RSA Source Data pointer (RSASPTR)
Address: 0x9C002A34
Reset: 0x0

Field Name	Bit	Access	Description
SPTR	31:0	RW	Source(X) Address Z=X**Y (mod N),must be 32B aligned

84.14 RSA Destination Data pointer (RSADPTR)
Address: 0x9C002A38
Reset: 0x0

Field Name	Bit	Access	Description
DPTR	31:0	RW	Destination(Z) Address Z=X**Y (mod N),must be 32B aligned

84.15 RSA Dma Parameter 0 (RSAPAR0)
Address: 0x9C002A3C
Reset: 0x0

Field Name	Bit	Access	Description
D	31:16	RW	N Length Only support 64*n(1¡=n¡=32)
Reserved	15:8	RO	RESERVED
PRECALC	7	RW	Precalculate P2 0: Precalculate and write back to pointer from P2PTR 1: Fetch from P2PTR
Reserved	6:0	RO	RESERVED

84.16 RSA Dma Parameter 1 (RSAPAR1)
Address: 0x9C002A40
Reset: 0x0

Field Name	Bit	Access	Description
YPTR	31:0	RW	Y Pointer Z=X**Y (mod N)

84.17 RSA Dma Parameter 2 (RSAPAR2)
Address: 0x9C002A44
Reset: 0x0

Field Name	Bit	Access	Description
NPTR	31:0	RW	N Pointer Z=X**Y (mod N)

84.18 RSA Dma Parameter 3 (RSAPAR3)
Address: 0x9C002A48
Reset: 0x0

Field Name	Bit	Access	Description
P2PTR	31:0	RW	P2 Pointer P2 = P**2(mod N)

84.19 RSA Dma Parameter 4 (RSAPAR4)
Address: 0x9C002A4C
Reset: 0x0

Field Name	Bit	Access	Description
WPTR	31:0	RW	W Low Dword W = -N**-1(mod N)

84.20 RSA Dma Parameter 5 (RSAPAR5)
Address: 0x9C002A50
Reset: 0x0

Field Name	Bit	Access	Description
WPTR	31:0	RW	W High Dword W = -N**-1(mod N)

84.21 AES DMA Command Ring Control Register (AESDMA CRCR)
Address: 0x9C002A54
Reset: 0x0

Field Name	Bit	Access	Description
CRPTR	31:5	RW	Command Ring Pointer The command ring should be 32bytes aligned
CP	4	RW	Cycle bit Position 0: Word 0[0] 1: Word7[31]
CRR	3	RO	Command Ring Running Indicates the command ring is running, SW can only change the pointer when this bit is cleared
Reserved	2	RO	RESERVED
CS	1	RW	Command Ring Stop Write 1 to stop the command ring
RCS	0	RW	Ring Cycle State Indicates the initial state of ring cycle bit

84.22 AES DMA Event Ring Base Address Register (AESDMA ERBAR)
Address: 0x9C002A58
Reset: 0x0

Field Name	Bit	Access	Description
ERBA	31:0	RW	Event Ring Base Address The first TRB of the status will be write to this address

84.23 AES DMA Event Ring De-queue Pointer Register (AESDMA ERDPR)
Address: 0x9C002A5C
Reset: 0x0

Field Name	Bit	Access	Description
ERDP	31:0	RW	Event Ring De-queue Pointer Indicates the TRB address of which the CPU is processing now

84.24 AES DMA Ring Control and Status Register (AESDMA RCSR)

Address: 0x9C002A60
Reset: 0x0

Field Name	Bit	Access	Description
EN	31	RW	Auto DMA Enable To enable the auto DMA feature
ERF	30	W1C	Event Ring Full Indicates the Event Ring has been writing full
Reserved	29:16	RO	RESERVED
Size	15:0	RW	Event Ring Size HW will write to ERBA if the size reaches this value and ERDP != ERBA

84.25 AES DMA Ring Trig Register (AESDMA RTR)
Address: 0x9C002A64
Reset: 0x0

Field Name	Bit	Access	Description
Reserved	31:1	RO	Reserved
CRT	0	WO	Command Ring Trig After SW write a '1' to this bit, HW will start transfer TRBs until the ring is empty or stopped

84.26 HASH DMA Command Ring Control Register (HASHDMA CRCR)
Address: 0x9C002A68
Reset: 0x0

Field Name	Bit	Access	Description
CRPTR	31:5	RW	Command Ring Pointer The command ring should be 32bytes aligned
CP	4	RW	Cycle bit Position 0: Word 0[0] 1: Word7[31]
CRR	3	RO	Command Ring Running Indicates the command ring is running, SW can only change the pointer when this bit is cleared
Reserved	2	RO	RESERVED
CS	1	RW	Command Ring Stop Write 1 to stop the command ring
RCS	0	RW	Ring Cycle State Indicates the initial state of ring cycle bit

84.27 HASH DMA Event Ring Base Address Register (HASHDMA ERBAR)
Address: 0x9C002A6C
Reset: 0x0

Field Name	Bit	Access	Description
ERBA	31:0	RW	Event Ring Base Address The first TRB of the status will be write to this address

84.28 HASH DMA Event Ring De-queue Pointer Register (HASHDMA ERDPR)
Address: 0x9C002A70
Reset: 0x0

Field Name	Bit	Access	Description
ERDP	31:0	RW	Event Ring De-queue Pointer Indicates the TRB address of which the CPU is processing now

84.29 HASH DMA Ring Control and Status Register (HASHDMA RCSR)

Address: 0x9C002A74
Reset: 0x0

Field Name	Bit	Access	Description
EN	31	RW	Auto DMA Enable To enable the auto DMA feature
ERF	30	W1C	Event Ring Full Indicates the Event Ring has been writing full
Reserved	29:16	RO	RESERVED
Size	15:0	RW	Event Ring Size HW will write to ERBA if the size reaches this value and ERDP != ERBA

84.30 HASH DMA Ring Trig Register (HASHDMA RTR)
Address: 0x9C002A78
Reset: 0x0

Field Name	Bit	Access	Description
Reserved	31:1	RO	RESERVED
CRT	0	WO	Command Ring Trig After SW write a '1' to this bit, HW will start transfer TRBs until the ring is empty or stopped

RGST Table Group 85 Security Global Control Registers

85.0 SEC IP Version (VERSION)
Address: 0x9C002A80
Reset: 0x20180503

Field Name	Bit	Access	Description
VERSION	31:0	RO	The Date of Version

85.1Interrupt Enable (SECIE)

Address: 0x9C002A84
Reset: 0x0

Field Name	Bit	Access	Description
Reserve	31:9	RO	RESERVED
AES CRD IE	8	RW	AES Command Ring Empty interrupt enable
HASH CRD IE	7	RW	HASH Command Ring Empty interrupt enable
AES TRB IE	6	RW	AES TRB done interrupt enable
HASH TRB IE	5	RW	HASH TRB done interrupt enable
AES ERF IE	4	RW	AES Event Ring Full interrupt enable
HASH ERF IE	3	RW	HASH Event Ring Full interrupt enable
AES DMA IE	2	RW	AES DMA finish interrupt enable
HASH DMA IE	1	RW	HASH DMA finish interrupt enable
RSA DMA IE	0	RW	RSA DMA finish interrupt enable

85.2 Interrupt Flag (SECIF)

Address: 0x9C002A88
Reset: 0x0

Field Name	Bit	Access	Description
Reserve	31:9	RO	RESERVED
AES CRD IF	8	W1C	AES Command Ring Empty interrupt flag pull up all trb done
HASH CRD IF	7	W1C	HASH Command Ring Empty interrupt flag pull up all trb done
AES TRB IF	6	W1C	AES TRB done interrupt flag pull up each trb done
HASH TRB IF	5	W1C	HASH TRB done interrupt flag pull up each trb done
AES ERF IF	4	RU	AES Event Ring Full interrupt flag
HASH ERF IF	3	RU	HASH Event Ring Full interrupt flag
AES DMA IF	2	W1C	AES DMA finish interrupt flag for normal dma
HASH DMA IF	1	W1C	HASH DMA finish interrupt flag for normal dma
RSA DMA IF	0	W1C	RSA DMA finish interrupt flag