Description

Cryptography accelerator peripheral API.

For cryptographic support, users should consider the crypto APIs of the mbedTLS library provided by Silicon Labs instead of the interface provided in em_crypto.h. The mbedTLS library provides a much richer crypto API, including hardware acceleration of several functions.

The main purpose of em_crypto.h is to implement a thin software interface for the CRYPTO hardware functions especially for the accelerated APIs of the mbedTLS library. Additionally, em_crypto.h implement the AES API of the em_aes.h (supported by classic EFM32) for backward compatibility. The following list summarizes the em_crypto.h interface:

• AES (Advanced Encryption Standard) AES
• SHA (Secure Hash Algorithm) SHA
• Big Integer multiplier CRYPTO_Mul
• Functions for loading data and executing instruction sequences Load and Execute Instruction Sequences

AES

The AES APIs include support for AES-128 and AES-256 with block cipher modes:

• CBC - Cipher Block Chaining mode
• CFB - Cipher Feedback mode
• CTR - Counter mode
• ECB - Electronic Code Book mode
• OFB - Output Feedback mode

For the AES APIs, input/output data (plaintext, ciphertext, key, and so on) are treated as byte arrays, starting with most significant byte. In other words, 32 bytes of plaintext (B0...B31) is located in memory in the same order, with B0 at the lower address and B31 at the higher address.

Byte arrays must always be a multiple of AES block size, i.e., a multiple of 16. Padding, if required, is done at the end of the byte array.

Byte arrays should be word (32 bit)-aligned for performance considerations, since the array is accessed with 32 bit access type. The core MCUs supports unaligned accesses but with a performance penalty.

You can specify the same output buffer as input buffer as long as they point to the same address. In that case, the provided input buffer is replaced with the encrypted/decrypted output. Notice that the buffers must be exactly overlapping. If partly overlapping, the behavior is undefined.

It is up to the user to use a cipher mode according to its requirements to avoid breaking security. See the specific cipher mode theory for details.

References:

• Wikipedia - Cipher modes, en.wikipedia.org/wiki/Cipher_modes

• Recommendation for Block Cipher Modes of Operation, NIST Special Publication 800-38A, 2001 Edition, csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf

• Recommendation for Block Cipher Modes of Operation, csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

SHA

The SHA APIs include support for

• SHA-1 CRYPTO_SHA_1
• SHA-256 CRYPTO_SHA_256

The SHA-1 implementation is FIPS-180-1 compliant, ref:

• Wikipedia - SHA-1, en.wikipedia.org/wiki/SHA-1
• SHA-1 spec - www.itl.nist.gov/fipspubs/fip180-1.htm

The SHA-256 implementation is FIPS-180-2 compliant, ref:

• Wikipedia - SHA-2, en.wikipedia.org/wiki/SHA-2
• SHA-2 spec - csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf

CRYPTO_Mul

CRYPTO_Mul is a function for multiplying big integers that are bigger than the operand size of the MUL instruction, which is 128 bits. CRYPTO_Mul multiplies all partial operands of the input operands using MUL to form a resulting number which may be twice the size of the operands.

CRPYTO_Mul is typically used by RSA implementations, which perform a huge amount of multiplication and square operations to implement modular exponentiation. Some RSA implementations use a number representation including arrays of 32-bit words of variable size. Compile with -D USE_VARIABLE_SIZED_DATA_LOADS to load these numbers directly into CRYPTO without converting the number representation.

Load and Execute Instruction Sequences

The functions for loading data and executing instruction sequences can be used to implement complex algorithms, such as elliptic curve cryptography (ECC)) and authenticated encryption algorithms. There are two typical modes of operation, as follows:

• Multi-sequence operation
• Single static instruction sequence operation

In multi-sequence mode, the software starts by loading input data, an instruction sequence, execute, and finally read the result. This process is repeated until the full crypto operation is complete.

When using a single static instruction sequence, only one instruction sequence is loaded initially. The sequence can be set up to run multiple times. Data can be loaded during the execution of the sequence by using DMA, BUFC and/or programmed I/O directly from the MCU core. For details about how to program the instruction sequences, see the reference manual of the particular Silicon Labs device.

To load input data to the CRYPTO module, use any of the following functions:

• CRYPTO_DataWrite - Write 128 bits to a DATA register.
• CRYPTO_DDataWrite - Write 256 bits to a DDATA register.
• CRYPTO_QDataWrite - Write 512 bits to a QDATA register.

To read output data from the CRYPTO module use any of the following functions:

• CRYPTO_DataRead - Read 128 bits from a DATA register.
• CRYPTO_DDataRead - Read 256 bits from a DDATA register.
• CRYPTO_QDataRead - Read 512 bits from a QDATA register.

To load an instruction sequence to the CRYPTO module, use CRYPTO_InstructionSequenceLoad.

To execute the current instruction sequence in the CRYPTO module, use CRYPTO_InstructionSequenceExecute.

To check whether an instruction sequence has completed, use CRYPTO_InstructionSequenceDone.

To wait for an instruction sequence to complete, use CRYPTO_InstructionSequenceWait.

To optimally load (with regards to speed) and execute an instruction sequence, use any of the CRYPTO_EXECUTE_X macros (where X is in the range 1-20) defined in em_crypto.h. E.g. CRYPTO_EXECUTE_19.

Functions
void	CRYPTO_BurstToCrypto (volatile uint32_t *reg, const uint32_t *val)
	Write a 128 bit value into a crypto register.
void	CRYPTO_BurstFromCrypto (volatile uint32_t *reg, uint32_t *val)
	Read a 128 bit value from a crypto register.
void	CRYPTO_DataWrite (CRYPTO_DataReg_TypeDef dataReg, const CRYPTO_Data_TypeDef val)
	Write 128 bits of data to a DATAX register in the CRYPTO module.
void	CRYPTO_DataWriteUnaligned (volatile uint32_t *reg, const uint8_t *val)
	Write 128 bits of unaligned data to a DATAX register in the CRYPTO module.
void	CRYPTO_DataRead (CRYPTO_DataReg_TypeDef dataReg, CRYPTO_Data_TypeDef val)
	Read 128 bits of data from a DATAX register in the CRYPTO module.
void	CRYPTO_DataReadUnaligned (volatile uint32_t *reg, uint8_t *val)
	Read 128 bits of data from a DATAX register in the CRYPTO module to an unaligned pointer.
void	CRYPTO_DDataWrite (CRYPTO_DDataReg_TypeDef ddataReg, const CRYPTO_DData_TypeDef val)
	Write 256 bits of data to a DDATAX register in the CRYPTO module.
void	CRYPTO_DDataRead (CRYPTO_DDataReg_TypeDef ddataReg, CRYPTO_DData_TypeDef val)
	Read 256 bits of data from a DDATAX register in the CRYPTO module.
void	CRYPTO_QDataRead (CRYPTO_QDataReg_TypeDef qdataReg, CRYPTO_QData_TypeDef val)
	Read 512 bits of data from a QDATAX register in the CRYPTO module.
void	CRYPTO_QDataWrite (CRYPTO_QDataReg_TypeDef qdataReg, const CRYPTO_QData_TypeDef val)
	Write 512 bits of data to a QDATAX register in the CRYPTO module.
void	CRYPTO_KeyBufWrite (CRYPTO_TypeDef *crypto, CRYPTO_KeyBuf_TypeDef val, CRYPTO_KeyWidth_TypeDef keyWidth)
	Set the key value to be used by the CRYPTO module.
void	CRYPTO_KeyBufWriteUnaligned (CRYPTO_TypeDef *crypto, const uint8_t *val, CRYPTO_KeyWidth_TypeDef keyWidth)
	Set the key value to be used by the CRYPTO module.
void	CRYPTO_KeyBuf128Write (CRYPTO_TypeDef *crypto, const uint32_t *val)
	Quick write 128 bit key to the CRYPTO module.
void	CRYPTO_ModulusSet (CRYPTO_TypeDef *crypto, CRYPTO_ModulusId_TypeDef modulusId)
	Set the modulus type used for wide arithmetic operations.
void	CRYPTO_KeyRead (CRYPTO_TypeDef *crypto, CRYPTO_KeyBuf_TypeDef val, CRYPTO_KeyWidth_TypeDef keyWidth)
	Read the key value currently used by the CRYPTO module.
void	CRYPTO_KeyReadUnaligned (CRYPTO_TypeDef *crypto, uint8_t *val, CRYPTO_KeyWidth_TypeDef keyWidth)
	Read the key value currently used by the CRYPTO module.
void	CRYPTO_SHA_1 (CRYPTO_TypeDef *crypto, const uint8_t *msg, uint64_t msgLen, CRYPTO_SHA1_Digest_TypeDef msgDigest)
	Perform a SHA-1 hash operation on a message.
void	CRYPTO_SHA_256 (CRYPTO_TypeDef *crypto, const uint8_t *msg, uint64_t msgLen, CRYPTO_SHA256_Digest_TypeDef msgDigest)
	Perform a SHA-256 hash operation on a message.
void	cryptoBigintZeroize (uint32_t *words32bits, unsigned num32bitWords)
	Set the 32 bit word array to zero.
void	cryptoBigintIncrement (uint32_t *words32bits, unsigned num32bitWords)
	Increment value of 32bit word array by one.
void	CRYPTO_Mul (CRYPTO_TypeDef *crypto, uint32_t *A, int aSize, uint32_t *B, int bSize, uint32_t *R, int rSize)
	Multiply two big integers.
void	CRYPTO_AES_CBC128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Cipher-block chaining (CBC) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_CBC256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Cipher-block chaining (CBC) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_PCBC128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Propagating Cipher-block chaining (PCBC) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_PCBC256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Propagating Cipher-block chaining (PCBC) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_CFB128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Cipher feedback (CFB) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_CFB256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv, bool encrypt)
	AES Cipher feedback (CFB) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_CTR128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, uint8_t *ctr, CRYPTO_AES_CtrFuncPtr_TypeDef ctrFunc)
	AES Counter (CTR) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_CTR256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, uint8_t *ctr, CRYPTO_AES_CtrFuncPtr_TypeDef ctrFunc)
	AES Counter (CTR) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_CTRUpdate32Bit (uint8_t *ctr)
	Update the last 32 bits of 128 bit counter by incrementing with 1.
void	CRYPTO_AES_DecryptKey128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in)
	Generate 128 bit AES decryption key from 128 bit encryption key.
void	CRYPTO_AES_DecryptKey256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in)
	Generate 256 bit AES decryption key from 256 bit encryption key.
void	CRYPTO_AES_ECB128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, bool encrypt)
	AES Electronic Codebook (ECB) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_ECB256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, bool encrypt)
	AES Electronic Codebook (ECB) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_OFB128 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv)
	AES Output feedback (OFB) cipher mode encryption/decryption, 128 bit key.
void	CRYPTO_AES_OFB256 (CRYPTO_TypeDef *crypto, uint8_t *out, const uint8_t *in, unsigned int len, const uint8_t *key, const uint8_t *iv)
	AES Output feedback (OFB) cipher mode encryption/decryption, 256 bit key.
void	CRYPTO_AES_ProcessLoop (CRYPTO_TypeDef *crypto, unsigned int len, CRYPTO_DataReg_TypeDef inReg, const uint8_t *in, CRYPTO_DataReg_TypeDef outReg, uint8_t *out)
	Perform generic AES loop.
void	CRYPTO_MulOperandWidthSet (CRYPTO_TypeDef *crypto, CRYPTO_MulOperandWidth_TypeDef mulOperandWidth)
	Set the number of bits in the operands of the MUL instruction.
void	CRYPTO_ResultWidthSet (CRYPTO_TypeDef *crypto, CRYPTO_ResultWidth_TypeDef resultWidth)
	Set the width of the results of the non-modulus instructions.
void	CRYPTO_IncWidthSet (CRYPTO_TypeDef *crypto, CRYPTO_IncWidth_TypeDef incWidth)
	Set the width of the DATA1 increment instruction DATA1INC.
bool	CRYPTO_CarryIsSet (CRYPTO_TypeDef *crypto)
	Quick read access of the carry bit from arithmetic operations.
uint8_t	CRYPTO_DData0_4LSBitsRead (CRYPTO_TypeDef *crypto)
	Quick read access of the 4 LSbits of the DDATA0 register.
void	CRYPTO_DData0Read260 (CRYPTO_TypeDef *crypto, CRYPTO_Data260_TypeDef val)
	Read 260 bits from the DDATA0 register.
void	CRYPTO_DData0Write260 (CRYPTO_TypeDef *crypto, const CRYPTO_Data260_TypeDef val)
	Write 260 bits to the DDATA0 register.
bool	CRYPTO_DData1_MSBitRead (CRYPTO_TypeDef *crypto)
	Quick read the MSbit of the DDATA1 register.
CRYPTO_WARNINGS_NO_CAST_ALIGN void	CRYPTO_InstructionSequenceLoad (CRYPTO_TypeDef *crypto, const CRYPTO_InstructionSequence_TypeDef instructionSequence)
	Load a sequence of instructions to be executed on the current values in the data registers.
CRYPTO_WARNINGS_RESET void	CRYPTO_InstructionSequenceExecute (CRYPTO_TypeDef *crypto)
	Execute the current programmed instruction sequence.
bool	CRYPTO_InstructionSequenceDone (CRYPTO_TypeDef *crypto)
	Check whether the execution of an instruction sequence has completed.
void	CRYPTO_InstructionSequenceWait (CRYPTO_TypeDef *crypto)
	Wait for completion of the current sequence of instructions.
void	CRYPTO_InstructionWait (CRYPTO_TypeDef *crypto)
	Wait for completion of the current command.
void	CRYPTO_IntClear (CRYPTO_TypeDef *crypto, uint32_t flags)
	Clear one or more pending CRYPTO interrupts.
void	CRYPTO_IntDisable (CRYPTO_TypeDef *crypto, uint32_t flags)
	Disable one or more CRYPTO interrupts.
void	CRYPTO_IntEnable (CRYPTO_TypeDef *crypto, uint32_t flags)
	Enable one or more CRYPTO interrupts.
uint32_t	CRYPTO_IntGet (CRYPTO_TypeDef *crypto)
	Get pending CRYPTO interrupt flags.
uint32_t	CRYPTO_IntGetEnabled (CRYPTO_TypeDef *crypto)
	Get enabled and pending CRYPTO interrupt flags.
void	CRYPTO_IntSet (CRYPTO_TypeDef *crypto, uint32_t flags)
	Set one or more pending CRYPTO interrupts from software.

Macros
#define	CRYPTO_MAX_SEQUENCE_INSTRUCTIONS   (20)
	The maximum number of crypto instructions in an instruction sequence.
#define	CRYPTO_INSTRUCTIONSEQUENSE_DEFAULT
	Default instruction sequence consisting of all ENDs.

Typedefs
typedef uint32_t	CRYPTO_Data_TypeDef[CRYPTO_DATA_SIZE_IN_32BIT_WORDS]
	CRYPTO data types used for data load functions.
typedef uint32_t	CRYPTO_DData_TypeDef[CRYPTO_DDATA_SIZE_IN_32BIT_WORDS]
	CRYPTO data type used for data load functions.
typedef uint32_t	CRYPTO_QData_TypeDef[CRYPTO_QDATA_SIZE_IN_32BIT_WORDS]
	CRYPTO data type used for data load functions.
typedef uint32_t	CRYPTO_Data260_TypeDef[CRYPTO_DATA260_SIZE_IN_32BIT_WORDS]
	CRYPTO data type used for data load functions.
typedef uint32_t	CRYPTO_KeyBuf_TypeDef[CRYPTO_KEYBUF_SIZE_IN_32BIT_WORDS]
	CRYPTO data type used for data load functions.
typedef volatile uint32_t *	CRYPTO_DataReg_TypeDef
	CRYPTO 128 bit Data register pointer type.
typedef volatile uint32_t *	CRYPTO_DDataReg_TypeDef
	CRYPTO 256 bit DData (Double Data) register pointer type.
typedef volatile uint32_t *	CRYPTO_QDataReg_TypeDef
	CRYPTO 512 bit QData (Quad data) register pointer type.
typedef uint8_t	CRYPTO_InstructionSequence_TypeDef[CRYPTO_MAX_SEQUENCE_INSTRUCTIONS]
	Instruction sequence type.
typedef uint8_t	CRYPTO_SHA1_Digest_TypeDef[CRYPTO_SHA1_DIGEST_SIZE_IN_BYTES]
	SHA-1 Digest type.
typedef uint8_t	CRYPTO_SHA256_Digest_TypeDef[CRYPTO_SHA256_DIGEST_SIZE_IN_BYTES]
	SHA-256 Digest type.
typedef void(*	CRYPTO_AES_CtrFuncPtr_TypeDef) (uint8_t *ctr)
	AES counter modification function pointer.

Enumerations
enum	CRYPTO_ModulusId_TypeDef {   cryptoModulusBin256 = CRYPTO_WAC_MODULUS_BIN256,   cryptoModulusBin128 = CRYPTO_WAC_MODULUS_BIN128,   cryptoModulusGcmBin128 = CRYPTO_WAC_MODULUS_GCMBIN128,   cryptoModulusEccB233 = CRYPTO_WAC_MODULUS_ECCBIN233P,   cryptoModulusEccB163 = CRYPTO_WAC_MODULUS_ECCBIN163P,   cryptoModulusEccP256 = CRYPTO_WAC_MODULUS_ECCPRIME256P,   cryptoModulusEccP224 = CRYPTO_WAC_MODULUS_ECCPRIME224P,   cryptoModulusEccP192 = CRYPTO_WAC_MODULUS_ECCPRIME192P,   cryptoModulusEccB233Order = CRYPTO_WAC_MODULUS_ECCBIN233N,   cryptoModulusEccB233KOrder = CRYPTO_WAC_MODULUS_ECCBIN233KN,   cryptoModulusEccB163Order = CRYPTO_WAC_MODULUS_ECCBIN163N,   cryptoModulusEccB163KOrder = CRYPTO_WAC_MODULUS_ECCBIN163KN,   cryptoModulusEccP256Order = CRYPTO_WAC_MODULUS_ECCPRIME256N,   cryptoModulusEccP224Order = CRYPTO_WAC_MODULUS_ECCPRIME224N,   cryptoModulusEccP192Order = CRYPTO_WAC_MODULUS_ECCPRIME192N }
	CRYPTO modulus identifiers.
enum	CRYPTO_MulOperandWidth_TypeDef {   cryptoMulOperand256Bits = CRYPTO_WAC_MULWIDTH_MUL256,   cryptoMulOperand128Bits = CRYPTO_WAC_MULWIDTH_MUL128,   cryptoMulOperandModulusBits = CRYPTO_WAC_MULWIDTH_MULMOD }
	CRYPTO multiplication widths for wide arithmetic operations.
enum	CRYPTO_ResultWidth_TypeDef {   cryptoResult128Bits = CRYPTO_WAC_RESULTWIDTH_128BIT,   cryptoResult256Bits = CRYPTO_WAC_RESULTWIDTH_256BIT,   cryptoResult260Bits = CRYPTO_WAC_RESULTWIDTH_260BIT }
	CRYPTO result widths for MUL operations.
enum	CRYPTO_IncWidth_TypeDef {   cryptoInc1byte = CRYPTO_CTRL_INCWIDTH_INCWIDTH1,   cryptoInc2byte = CRYPTO_CTRL_INCWIDTH_INCWIDTH2,   cryptoInc3byte = CRYPTO_CTRL_INCWIDTH_INCWIDTH3,   cryptoInc4byte = CRYPTO_CTRL_INCWIDTH_INCWIDTH4 }
	CRYPTO result widths for MUL operations.
enum	CRYPTO_KeyWidth_TypeDef {   cryptoKey128Bits = 8,   cryptoKey256Bits = 16 }
	CRYPTO key width.

Function Documentation

◆ CRYPTO_BurstToCrypto()

◆ CRYPTO_BurstFromCrypto()

◆ CRYPTO_DataWrite()

◆ CRYPTO_DataWriteUnaligned()

◆ CRYPTO_DataRead()

◆ CRYPTO_DataReadUnaligned()

◆ CRYPTO_DDataWrite()

◆ CRYPTO_DDataRead()

◆ CRYPTO_QDataRead()