Mbed Crypto H/W Acceleration (rm_psa_crypto)

Functions
int	mbedtls_platform_setup (mbedtls_platform_context *ctx)
void	mbedtls_platform_teardown (mbedtls_platform_context *ctx)
fsp_err_t	RM_PSA_CRYPTO_TRNG_Read (uint8_t *const p_rngbuf, uint32_t num_req_bytes, uint32_t *p_num_gen_bytes)
	Reads requested length of random data from the TRNG. Generate nbytes of random bytes and store them in p_rngbuf buffer. More...

Detailed Description

Hardware acceleration for the mbedCrypto implementation of the Arm PSA Crypto API.

Overview

Note

The PSA Crypto module does not provide any interfaces to the user. This release uses the mbedTLS version 3.4.0 which conforms to the PSA Crypto API 1.0 specification. Consult the Arm documentation at https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface for further information. FSP 3.0 onward adopts a change by Arm where mbedCrypto has been integrated back to MbedTLS and the term mbedCrypto has been deprecated. The mbedCrypto term in FSP now refers to the crypto portion of the MbedTLS module.

HW Overview

Crypto Peripheral version	Devices
SCE9	RA6M4, RA4M3, RA4M2, RA6M5
SCE7	RA6M3, RA6M2, RA6M1, RA6T1
SCE5	RA4W1, RA4M1
SCE5B	RA6T2
AES Engine	RA2A1, RA2E1, RA2E2, RA2L1
TRNG	RA4E1, RA4E2, RA4T1, RA6E1, RA6E2, RA6T3
RSIP-E51A	RA8M1, RA8D1, RA8T1

Features

The PSA_Crypto module provides hardware support for the following PSA Crypto operations

• SHA256 calculation
• SHA224 calculation
• SHA512 calculation (Available only on RSIP7)
• SHA384 calculation (Available only on RSIP7)
• MAC Operations
• AES
  • Keybits - 128, 192, 256
  • Plain-Text Key Generation
  • Wrapped Key Generation
  • Encryption and Decryption with no padding and with PKCS7 padding.
  • CBC, CTR, CCM , XTS and GCM modes
  • MAC operations
  • Export and Import of Plaintext and Wrapped keys
• ECC
  • Curves:
    • SECP256R1
    • SECP256K1
    • Brainpool256R1
    • SECP384R1
    • Brainpool384R1
  • Plain-Text Key Generation (Unavailable on SCE9 and RSIP7)
  • Wrapped Key Generation (Available only on RSIP7)
  • Signing and Verification
  • Export and Import of Plaintext keys
  • Export and Import of Wrapped keys generated by PSA.
  • ECDH Support
• RSA
  • Plain-Text Key Generation for RSA-2048. (Unavailable on SCE9 and RSIP7)
  • Wrapped Key Generation for RSA-2048. RSA-3072 on RSIP7 only.
  • Signature Generation for RSA-2048. RSA-3072 on RSIP7 only.
  • Verification for RSA-2048. RSA-3072 and 4096 on SCE9 and RSIP7 only.
  • Encryption and Decryption with PKCS1V15 and OAEP padding
  • Export and Import of Plaintext keys
  • Export and Import of Wrapped keys generated by PSA.
• Random number generation
• Persistent Key Storage

Configuration

Build Time Configurations for mbedCrypto

The following build time configurations are defined in arm/mbedtls/config.h:

Configuration	Options	Default	Description
Hardware Acceleration
Hardware Acceleration > Key Format
AES	MCU Specific Options		Select AES key formats used
ECC	MCU Specific Options		Select ECC key formats used
RSA	MCU Specific Options		Select RSA key formats used
Hardware Acceleration > Hash
SHA256/224	MCU Specific Options		Defines MBEDTLS_SHA256_ALT and MBEDTLS_SHA256_PROCESS_ALT.
SHA512/384	MCU Specific Options		Defines MBEDTLS_SHA512_ALT and MBEDTLS_SHA512_PROCESS_ALT.
Hardware Acceleration > Cipher
AES	MCU Specific Options		Defines MBEDTLS_AES_ALT, MBEDTLS_AES_SETKEY_ENC_ALT, MBEDTLS_AES_SETKEY_DEC_ALT, MBEDTLS_AES_ENCRYPT_ALT and MBEDTLS_AES_DECRYPT_ALT
Hardware Acceleration > Public Key Cryptography (PKC)
Hardware Acceleration > Public Key Cryptography (PKC) > RSA 3072
RSA 3072 > Key Generation	MCU Specific Options		Enables RSA 3072 Key Generation.
RSA 3072 > Signing	MCU Specific Options		Enables RSA 3072 Key Signing.
RSA 3072 > Verification	MCU Specific Options		Enables RSA 3072 Verify.
Hardware Acceleration > Public Key Cryptography (PKC) > RSA 4096
RSA 4096 > Verification	MCU Specific Options		Enables RSA 4096 Verify.
ECC	MCU Specific Options		Defines MBEDTLS_ECP_ALT
ECDSA	MCU Specific Options		Defines MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_VERIFY_ALT
ECDH	MCU Specific Options		Defines MBEDTLS_ECDH_ALT
RSA	MCU Specific Options		Defines MBEDTLS_RSA_ALT. RSA 2048 Key Generation, Signing and Verification are also enabled.
TRNG	Enabled	Enabled	Defines MBEDTLS_ENTROPY_HARDWARE_ALT.
Crypto Engine Initialization	Enabled	Enabled	MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT
Platform
Platform > Alternate
MBEDTLS_PLATFORM_SETBUF_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_SETBUF_ALT
MBEDTLS_PLATFORM_EXIT_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_EXIT_ALT
MBEDTLS_PLATFORM_TIME_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_TIME_ALT
MBEDTLS_PLATFORM_FPRINTF_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_FPRINTF_ALT
MBEDTLS_PLATFORM_PRINTF_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_PRINTF_ALT
MBEDTLS_PLATFORM_SNPRINTF_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_SNPRINTF_ALT
MBEDTLS_PLATFORM_VSNPRINTF_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_VSNPRINTF_ALT
MBEDTLS_PLATFORM_NV_SEED_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_NV_SEED_ALT
MBEDTLS_PLATFORM_ZEROIZE_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_ZEROIZE_ALT
MBEDTLS_PLATFORM_GMTIME_R_ALT	Define Undefine	Undefine	MBEDTLS_PLATFORM_GMTIME_R_ALT
MBEDTLS_HAVE_ASM	Define Undefine	Undefine	MBEDTLS_HAVE_ASM
MBEDTLS_NO_UDBL_DIVISION	Define Undefine	Undefine	MBEDTLS_NO_UDBL_DIVISION
MBEDTLS_NO_64BIT_MULTIPLICATION	Define Undefine	Undefine	MBEDTLS_NO_64BIT_MULTIPLICATION
MBEDTLS_HAVE_SSE2	Define Undefine	Undefine	MBEDTLS_HAVE_SSE2
MBEDTLS_HAVE_TIME	Define Undefine	Undefine	MBEDTLS_HAVE_TIME
MBEDTLS_HAVE_TIME_DATE	Define Undefine	Undefine	MBEDTLS_HAVE_TIME_DATE
MBEDTLS_PLATFORM_MEMORY	Define Undefine	Define	MBEDTLS_PLATFORM_MEMORY
MBEDTLS_PLATFORM_NO_STD_FUNCTIONS	Define Undefine	Undefine	MBEDTLS_PLATFORM_NO_STD_FUNCTIONS
MBEDTLS_TIMING_ALT	Define Undefine	Undefine	MBEDTLS_TIMING_ALT
MBEDTLS_NO_PLATFORM_ENTROPY	Define Undefine	Define	MBEDTLS_NO_PLATFORM_ENTROPY
MBEDTLS_ENTROPY_C	Define Undefine	Define	MBEDTLS_ENTROPY_C
MBEDTLS_PLATFORM_C	Define Undefine	Define	MBEDTLS_PLATFORM_C
MBEDTLS_PLATFORM_STD_CALLOC	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_CALLOC
MBEDTLS_PLATFORM_STD_CALLOC value	Manual Entry	calloc	MBEDTLS_PLATFORM_STD_CALLOC value
MBEDTLS_PLATFORM_STD_FREE	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_FREE
MBEDTLS_PLATFORM_STD_FREE value	Manual Entry	free	MBEDTLS_PLATFORM_STD_FREE value
MBEDTLS_PLATFORM_STD_SETBUF	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_SETBUF
MBEDTLS_PLATFORM_STD_SETBUF value	Manual Entry	setbuf	MBEDTLS_PLATFORM_STD_SETBUF value
MBEDTLS_PLATFORM_STD_EXIT	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_EXIT
MBEDTLS_PLATFORM_STD_EXIT value	Manual Entry	exit	MBEDTLS_PLATFORM_STD_EXIT value
MBEDTLS_PLATFORM_STD_TIME	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_TIME
MBEDTLS_PLATFORM_STD_TIME value	Manual Entry	time	MBEDTLS_PLATFORM_STD_TIME value
MBEDTLS_PLATFORM_STD_FPRINTF	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_FPRINTF
MBEDTLS_PLATFORM_STD_FPRINTF value	Manual Entry	fprintf	MBEDTLS_PLATFORM_STD_FPRINTF value
MBEDTLS_PLATFORM_STD_PRINTF	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_PRINTF
MBEDTLS_PLATFORM_STD_PRINTF value	Manual Entry	printf	MBEDTLS_PLATFORM_STD_PRINTF value
MBEDTLS_PLATFORM_STD_SNPRINTF	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_SNPRINTF
MBEDTLS_PLATFORM_STD_SNPRINTF value	Manual Entry	snprintf	MBEDTLS_PLATFORM_STD_SNPRINTF value
MBEDTLS_PLATFORM_STD_EXIT_SUCCESS	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
MBEDTLS_PLATFORM_STD_EXIT_SUCCESS value	Manual Entry	0	MBEDTLS_PLATFORM_STD_EXIT_SUCCESS value
MBEDTLS_PLATFORM_STD_EXIT_FAILURE	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_EXIT_FAILURE
MBEDTLS_PLATFORM_STD_EXIT_FAILURE value	Manual Entry	1	MBEDTLS_PLATFORM_STD_EXIT_FAILURE value
MBEDTLS_PLATFORM_STD_NV_SEED_READ	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_NV_SEED_READ
MBEDTLS_PLATFORM_STD_NV_SEED_READ value	Manual Entry	mbedtls_platform_std_nv_seed_read	MBEDTLS_PLATFORM_STD_NV_SEED_READ value
MBEDTLS_PLATFORM_STD_NV_SEED_WRITE	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_NV_SEED_WRITE
MBEDTLS_PLATFORM_STD_NV_SEED_WRITE value	Manual Entry	mbedtls_platform_std_nv_seed_write	MBEDTLS_PLATFORM_STD_NV_SEED_WRITE value
MBEDTLS_PLATFORM_STD_NV_SEED_FILE	Define Undefine	Undefine	MBEDTLS_PLATFORM_STD_NV_SEED_FILE
MBEDTLS_PLATFORM_STD_NV_SEED_FILE value	Manual Entry		MBEDTLS_PLATFORM_STD_NV_SEED_FILE value
MBEDTLS_PLATFORM_CALLOC_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_CALLOC_MACRO
MBEDTLS_PLATFORM_CALLOC_MACRO value	Manual Entry	calloc	MBEDTLS_PLATFORM_CALLOC_MACRO value
MBEDTLS_PLATFORM_FREE_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_FREE_MACRO
MBEDTLS_PLATFORM_FREE_MACRO value	Manual Entry	free	MBEDTLS_PLATFORM_FREE_MACRO value
MBEDTLS_PLATFORM_EXIT_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_EXIT_MACRO
MBEDTLS_PLATFORM_EXIT_MACRO value	Manual Entry	exit	MBEDTLS_PLATFORM_EXIT_MACRO value
MBEDTLS_PLATFORM_SETBUF_MACRO	Define Undefine	Define	MBEDTLS_PLATFORM_SETBUF_MACRO
MBEDTLS_PLATFORM_SETBUF_MACRO value	Manual Entry	dummy_setbuf	MBEDTLS_PLATFORM_SETBUF_MACRO value
MBEDTLS_PLATFORM_TIME_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_TIME_MACRO
MBEDTLS_PLATFORM_TIME_MACRO value	Manual Entry	time	MBEDTLS_PLATFORM_TIME_MACRO value
MBEDTLS_PLATFORM_TIME_TYPE_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_TIME_TYPE_MACRO
MBEDTLS_PLATFORM_TIME_TYPE_MACRO value	Manual Entry	time_t	MBEDTLS_PLATFORM_TIME_TYPE_MACRO value
MBEDTLS_PLATFORM_FPRINTF_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_FPRINTF_MACRO
MBEDTLS_PLATFORM_FPRINTF_MACRO value	Manual Entry	fprintf	MBEDTLS_PLATFORM_FPRINTF_MACRO value
MBEDTLS_PLATFORM_PRINTF_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_PRINTF_MACRO
MBEDTLS_PLATFORM_PRINTF_MACRO value	Manual Entry	printf	MBEDTLS_PLATFORM_PRINTF_MACRO value
MBEDTLS_PLATFORM_SNPRINTF_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_SNPRINTF_MACRO
MBEDTLS_PLATFORM_SNPRINTF_MACRO value	Manual Entry	snprintf	MBEDTLS_PLATFORM_SNPRINTF_MACRO value
MBEDTLS_PLATFORM_VSNPRINTF_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_VSNPRINTF_MACRO
MBEDTLS_PLATFORM_VSNPRINTF_MACRO value	Manual Entry	vsnprintf	MBEDTLS_PLATFORM_VSNPRINTF_MACRO value
MBEDTLS_PLATFORM_NV_SEED_READ_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
MBEDTLS_PLATFORM_NV_SEED_READ_MACRO value	Manual Entry	mbedtls_platform_std_nv_seed_read	MBEDTLS_PLATFORM_NV_SEED_READ_MACRO value
MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO	Define Undefine	Undefine	MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO value	Manual Entry	mbedtls_platform_std_nv_seed_write	MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO value
General
MBEDTLS_PSA_CRYPTO_DRIVERS	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_DRIVERS
MBEDTLS_DEPRECATED_WARNING	Define Undefine	Undefine	MBEDTLS_DEPRECATED_WARNING
MBEDTLS_DEPRECATED_REMOVED	Define Undefine	Define	MBEDTLS_DEPRECATED_REMOVED
MBEDTLS_CHECK_RETURN_WARNING	Define Undefine	Undefine	MBEDTLS_CHECK_RETURN_WARNING
MBEDTLS_ERROR_STRERROR_DUMMY	Define Undefine	Define	MBEDTLS_ERROR_STRERROR_DUMMY
MBEDTLS_MEMORY_DEBUG	Define Undefine	Undefine	MBEDTLS_MEMORY_DEBUG
MBEDTLS_MEMORY_BACKTRACE	Define Undefine	Undefine	MBEDTLS_MEMORY_BACKTRACE
MBEDTLS_PSA_CRYPTO_CLIENT	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_CLIENT
MBEDTLS_PSA_CRYPTO_SPM	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_SPM
MBEDTLS_SELF_TEST	Define Undefine	Undefine	MBEDTLS_SELF_TEST
MBEDTLS_THREADING_ALT	Define Undefine	Define	MBEDTLS_THREADING_ALT
MBEDTLS_THREADING_PTHREAD	Define Undefine	Undefine	MBEDTLS_THREADING_PTHREAD
MBEDTLS_USE_PSA_CRYPTO	Undefine	Undefine	MBEDTLS_USE_PSA_CRYPTO
MBEDTLS_VERSION_FEATURES	Define Undefine	Define	MBEDTLS_VERSION_FEATURES
MBEDTLS_ERROR_C	Define Undefine	Define	MBEDTLS_ERROR_C
MBEDTLS_MEMORY_BUFFER_ALLOC_C	Define Undefine	Undefine	MBEDTLS_MEMORY_BUFFER_ALLOC_C
MBEDTLS_PSA_CRYPTO_C	Define Undefine	Define	MBEDTLS_PSA_CRYPTO_C
MBEDTLS_PSA_CRYPTO_SE_C	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_SE_C
MBEDTLS_THREADING_C	Define Undefine	Define	MBEDTLS_THREADING_C
MBEDTLS_TIMING_C	Define Undefine	Undefine	MBEDTLS_TIMING_C
MBEDTLS_VERSION_C	Define Undefine	Define	MBEDTLS_VERSION_C
MBEDTLS_MEMORY_ALIGN_MULTIPLE	Define Undefine	Undefine	MBEDTLS_MEMORY_ALIGN_MULTIPLE
MBEDTLS_MEMORY_ALIGN_MULTIPLE value	Manual Entry	4	MBEDTLS_MEMORY_ALIGN_MULTIPLE value
MBEDTLS_CHECK_RETURN	Define Undefine	Define	MBEDTLS_CHECK_RETURN
MBEDTLS_IGNORE_RETURN	Define Undefine	Undefine	MBEDTLS_IGNORE_RETURN
Cipher
Cipher > Alternate
MBEDTLS_ARIA_ALT	Define Undefine	Undefine	MBEDTLS_ARIA_ALT
MBEDTLS_CAMELLIA_ALT	Define Undefine	Undefine	MBEDTLS_CAMELLIA_ALT
MBEDTLS_CCM_ALT	MCU Specific Options		MBEDTLS_CCM_ALT
MBEDTLS_CHACHA20_ALT	Define Undefine	Undefine	MBEDTLS_CHACHA20_ALT
MBEDTLS_CHACHAPOLY_ALT	Define Undefine	Undefine	MBEDTLS_CHACHAPOLY_ALT
MBEDTLS_CMAC_ALT	MCU Specific Options		MBEDTLS_CMAC_ALT
MBEDTLS_DES_ALT	Define Undefine	Undefine	MBEDTLS_DES_ALT
MBEDTLS_GCM_ALT	MCU Specific Options		MBEDTLS_GCM_ALT
MBEDTLS_NIST_KW_ALT	Define Undefine	Undefine	MBEDTLS_NIST_KW_ALT
MBEDTLS_DES_SETKEY_ALT	Define Undefine	Undefine	MBEDTLS_DES_SETKEY_ALT
MBEDTLS_DES_CRYPT_ECB_ALT	Define Undefine	Undefine	MBEDTLS_DES_CRYPT_ECB_ALT
MBEDTLS_DES3_CRYPT_ECB_ALT	Define Undefine	Undefine	MBEDTLS_DES3_CRYPT_ECB_ALT
Cipher > AES
MBEDTLS_AES_ROM_TABLES	Define Undefine	Undefine	MBEDTLS_AES_ROM_TABLES
MBEDTLS_AES_FEWER_TABLES	Define Undefine	Undefine	MBEDTLS_AES_FEWER_TABLES
MBEDTLS_CAMELLIA_SMALL_MEMORY	Define Undefine	Undefine	MBEDTLS_CAMELLIA_SMALL_MEMORY
MBEDTLS_CIPHER_MODE_CBC	Define Undefine	Define	MBEDTLS_CIPHER_MODE_CBC
MBEDTLS_CIPHER_MODE_CFB	Define Undefine	Define	MBEDTLS_CIPHER_MODE_CFB
MBEDTLS_CIPHER_MODE_CTR	Define Undefine	Define	MBEDTLS_CIPHER_MODE_CTR
MBEDTLS_CIPHER_MODE_OFB	Define Undefine	Undefine	MBEDTLS_CIPHER_MODE_OFB
MBEDTLS_CIPHER_MODE_XTS	Define Undefine	Undefine	MBEDTLS_CIPHER_MODE_XTS
MBEDTLS_CIPHER_NULL_CIPHER	Define Undefine	Undefine	MBEDTLS_CIPHER_NULL_CIPHER
MBEDTLS_CIPHER_PADDING_PKCS7	Define Undefine	Define	MBEDTLS_CIPHER_PADDING_PKCS7
MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS	Define Undefine	Define	MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS
MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN	Define Undefine	Define	MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN
MBEDTLS_CIPHER_PADDING_ZEROS	Define Undefine	Define	MBEDTLS_CIPHER_PADDING_ZEROS
MBEDTLS_AES_C	Define	Define	MBEDTLS_AES_C
MBEDTLS_CAMELLIA_C	Define Undefine	Undefine	MBEDTLS_CAMELLIA_C
MBEDTLS_ARIA_C	Define Undefine	Undefine	MBEDTLS_ARIA_C
MBEDTLS_CCM_C	Define Undefine	Define	MBEDTLS_CCM_C
MBEDTLS_CHACHA20_C	Define Undefine	Undefine	MBEDTLS_CHACHA20_C
MBEDTLS_CHACHAPOLY_C	Define Undefine	Undefine	MBEDTLS_CHACHAPOLY_C
MBEDTLS_CIPHER_C	Define Undefine	Define	MBEDTLS_CIPHER_C
MBEDTLS_DES_C	Define Undefine	Undefine	MBEDTLS_DES_C
MBEDTLS_GCM_C	Define Undefine	Define	MBEDTLS_GCM_C
MBEDTLS_NIST_KW_C	Define Undefine	Undefine	MBEDTLS_NIST_KW_C
Public Key Cryptography (PKC)
Public Key Cryptography (PKC) > DHM
Public Key Cryptography (PKC) > DHM > Alternate
MBEDTLS_DHM_ALT	Define Undefine	Undefine	MBEDTLS_DHM_ALT
MBEDTLS_DHM_C	Define Undefine	Undefine	MBEDTLS_DHM_C
Public Key Cryptography (PKC) > ECC
Public Key Cryptography (PKC) > ECC > Alternate
MBEDTLS_ECJPAKE_ALT	Define Undefine	Undefine	MBEDTLS_ECJPAKE_ALT
MBEDTLS_ECDSA_GENKEY_ALT	Define Undefine	Undefine	MBEDTLS_ECDSA_GENKEY_ALT
MBEDTLS_ECP_INTERNAL_ALT	Define Undefine	Undefine	MBEDTLS_ECP_INTERNAL_ALT
MBEDTLS_ECP_RANDOMIZE_JAC_ALT	Define Undefine	Undefine	MBEDTLS_ECP_RANDOMIZE_JAC_ALT
MBEDTLS_ECP_ADD_MIXED_ALT	Define Undefine	Undefine	MBEDTLS_ECP_ADD_MIXED_ALT
MBEDTLS_ECP_DOUBLE_JAC_ALT	Define Undefine	Undefine	MBEDTLS_ECP_DOUBLE_JAC_ALT
MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT	Define Undefine	Undefine	MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT
MBEDTLS_ECP_NORMALIZE_JAC_ALT	Define Undefine	Undefine	MBEDTLS_ECP_NORMALIZE_JAC_ALT
MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT	Define Undefine	Undefine	MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT
MBEDTLS_ECP_RANDOMIZE_MXZ_ALT	Define Undefine	Undefine	MBEDTLS_ECP_RANDOMIZE_MXZ_ALT
MBEDTLS_ECP_NORMALIZE_MXZ_ALT	Define Undefine	Undefine	MBEDTLS_ECP_NORMALIZE_MXZ_ALT
Public Key Cryptography (PKC) > ECC > Curves
MBEDTLS_ECP_DP_SECP192R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP192R1_ENABLED
MBEDTLS_ECP_DP_SECP224R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP224R1_ENABLED
MBEDTLS_ECP_DP_SECP256R1_ENABLED	Define Undefine	Define	MBEDTLS_ECP_DP_SECP256R1_ENABLED
MBEDTLS_ECP_DP_SECP384R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP384R1_ENABLED
MBEDTLS_ECP_DP_SECP521R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP521R1_ENABLED
MBEDTLS_ECP_DP_SECP192K1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP192K1_ENABLED
MBEDTLS_ECP_DP_SECP224K1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP224K1_ENABLED
MBEDTLS_ECP_DP_SECP256K1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_SECP256K1_ENABLED
MBEDTLS_ECP_DP_BP256R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_BP256R1_ENABLED
MBEDTLS_ECP_DP_BP384R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_BP384R1_ENABLED
MBEDTLS_ECP_DP_BP512R1_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_BP512R1_ENABLED
MBEDTLS_ECP_DP_CURVE25519_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_CURVE25519_ENABLED
MBEDTLS_ECP_DP_CURVE448_ENABLED	Define Undefine	Undefine	MBEDTLS_ECP_DP_CURVE448_ENABLED
MBEDTLS_ECDH_GEN_PUBLIC_ALT	Define Undefine	Undefine	MBEDTLS_ECDH_GEN_PUBLIC_ALT
MBEDTLS_ECDH_COMPUTE_SHARED_ALT	Define Undefine	Undefine	MBEDTLS_ECDH_COMPUTE_SHARED_ALT
MBEDTLS_ECP_NO_FALLBACK	Define Undefine	Undefine	MBEDTLS_ECP_NO_FALLBACK
MBEDTLS_ECP_NIST_OPTIM	Define Undefine	Undefine	MBEDTLS_ECP_NIST_OPTIM
MBEDTLS_ECP_RESTARTABLE	Define Undefine	Undefine	MBEDTLS_ECP_RESTARTABLE
MBEDTLS_ECDSA_DETERMINISTIC	Define Undefine	Undefine	MBEDTLS_ECDSA_DETERMINISTIC
MBEDTLS_PK_PARSE_EC_EXTENDED	Define Undefine	Undefine	MBEDTLS_PK_PARSE_EC_EXTENDED
MBEDTLS_ECDH_C	Define Undefine	Undefine	MBEDTLS_ECDH_C
MBEDTLS_ECDSA_C	Define Undefine	Define	MBEDTLS_ECDSA_C
MBEDTLS_ECP_C	Define Undefine	Define	MBEDTLS_ECP_C
MBEDTLS_ECJPAKE_C	Define Undefine	Undefine	MBEDTLS_ECJPAKE_C
MBEDTLS_ECP_WINDOW_SIZE	Define Undefine	Undefine	MBEDTLS_ECP_WINDOW_SIZE
MBEDTLS_ECP_WINDOW_SIZE value	Manual Entry	6	MBEDTLS_ECP_WINDOW_SIZE value
MBEDTLS_ECP_FIXED_POINT_OPTIM	Define Undefine	Undefine	MBEDTLS_ECP_FIXED_POINT_OPTIM
MBEDTLS_ECP_FIXED_POINT_OPTIM value	Manual Entry	1	MBEDTLS_ECP_FIXED_POINT_OPTIM value
MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED	Define Undefine	Undefine	MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED
Public Key Cryptography (PKC) > RSA
MBEDTLS_PK_RSA_ALT_SUPPORT	Define Undefine	Undefine	MBEDTLS_PK_RSA_ALT_SUPPORT
MBEDTLS_RSA_NO_CRT	Define Undefine	Define	MBEDTLS_RSA_NO_CRT
MBEDTLS_RSA_C	Define Undefine	Define	MBEDTLS_RSA_C
MBEDTLS_GENPRIME	Define Undefine	Define	MBEDTLS_GENPRIME
MBEDTLS_PKCS1_V15	Define Undefine	Define	MBEDTLS_PKCS1_V15
MBEDTLS_PKCS1_V21	Define Undefine	Define	MBEDTLS_PKCS1_V21
MBEDTLS_ASN1_PARSE_C	Define Undefine	Define	MBEDTLS_ASN1_PARSE_C
MBEDTLS_ASN1_WRITE_C	Define Undefine	Define	MBEDTLS_ASN1_WRITE_C
MBEDTLS_BASE64_C	Define Undefine	Define	MBEDTLS_BASE64_C
MBEDTLS_BIGNUM_C	Define Undefine	Define	MBEDTLS_BIGNUM_C
MBEDTLS_LMS_C	Define Undefine	Define	MBEDTLS_LMS_C
MBEDTLS_LMS_PRIVATE	Define Undefine	Undefine	MBEDTLS_LMS_PRIVATE
MBEDTLS_OID_C	Define Undefine	Define	MBEDTLS_OID_C
MBEDTLS_PEM_PARSE_C	Define Undefine	Define	MBEDTLS_PEM_PARSE_C
MBEDTLS_PEM_WRITE_C	Define Undefine	Define	MBEDTLS_PEM_WRITE_C
MBEDTLS_PK_C	Define Undefine	Define	MBEDTLS_PK_C
MBEDTLS_PK_PARSE_C	Define Undefine	Define	MBEDTLS_PK_PARSE_C
MBEDTLS_PK_WRITE_C	Define Undefine	Define	MBEDTLS_PK_WRITE_C
MBEDTLS_PKCS5_C	Define Undefine	Define	MBEDTLS_PKCS5_C
MBEDTLS_PKCS7_C	Define Undefine	Undefine	MBEDTLS_PKCS7_C
MBEDTLS_PKCS12_C	Define Undefine	Define	MBEDTLS_PKCS12_C
MBEDTLS_MPI_WINDOW_SIZE	Define Undefine	Undefine	MBEDTLS_MPI_WINDOW_SIZE
MBEDTLS_MPI_WINDOW_SIZE value	Manual Entry	6	MBEDTLS_MPI_WINDOW_SIZE value
MBEDTLS_MPI_MAX_SIZE	Define Undefine	Undefine	MBEDTLS_MPI_MAX_SIZE
MBEDTLS_MPI_MAX_SIZE value	Manual Entry	1024	MBEDTLS_MPI_MAX_SIZE value
Hash
Hash > Alternate
MBEDTLS_MD5_ALT	Define Undefine	Undefine	MBEDTLS_MD5_ALT
MBEDTLS_RIPEMD160_ALT	Define Undefine	Undefine	MBEDTLS_RIPEMD160_ALT
MBEDTLS_SHA1_ALT	Define Undefine	Undefine	MBEDTLS_SHA1_ALT
MBEDTLS_MD5_PROCESS_ALT	Define Undefine	Undefine	MBEDTLS_MD5_PROCESS_ALT
MBEDTLS_RIPEMD160_PROCESS_ALT	Define Undefine	Undefine	MBEDTLS_RIPEMD160_PROCESS_ALT
MBEDTLS_SHA1_PROCESS_ALT	Define Undefine	Undefine	MBEDTLS_SHA1_PROCESS_ALT
MBEDTLS_SHA256_SMALLER	Define Undefine	Undefine	MBEDTLS_SHA256_SMALLER
MBEDTLS_SHA512_SMALLER	Define Undefine	Undefine	MBEDTLS_SHA512_SMALLER
MBEDTLS_MD_C	Define Undefine	Define	MBEDTLS_MD_C
MBEDTLS_MD5_C	Define Undefine	Define	MBEDTLS_MD5_C
MBEDTLS_RIPEMD160_C	Define Undefine	Undefine	MBEDTLS_RIPEMD160_C
MBEDTLS_SHA1_C	Define Undefine	Define	MBEDTLS_SHA1_C
MBEDTLS_SHA224_C	Define Undefine	Define	MBEDTLS_SHA224_C
MBEDTLS_SHA256_C	Define Undefine	Define	MBEDTLS_SHA256_C
MBEDTLS_SHA384_C	Define Undefine	Undefine	MBEDTLS_SHA384_C
MBEDTLS_SHA512_C	Define Undefine	Undefine	MBEDTLS_SHA512_C
Message Authentication Code (MAC)
Message Authentication Code (MAC) > Alternate
MBEDTLS_POLY1305_ALT	Define Undefine	Undefine	MBEDTLS_POLY1305_ALT
MBEDTLS_CMAC_C	Define Undefine	Undefine	MBEDTLS_CMAC_C
MBEDTLS_HKDF_C	Define Undefine	Define	MBEDTLS_HKDF_C
MBEDTLS_HMAC_DRBG_C	Define Undefine	Undefine	MBEDTLS_HMAC_DRBG_C
MBEDTLS_POLY1305_C	Define Undefine	Undefine	MBEDTLS_POLY1305_C
Storage
MBEDTLS_FS_IO	Define Undefine	Undefine	MBEDTLS_FS_IO
MBEDTLS_PSA_CRYPTO_STORAGE_C	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_STORAGE_C
MBEDTLS_PSA_ITS_FILE_C	Define Undefine	Undefine	MBEDTLS_PSA_ITS_FILE_C
RNG
MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES	Define Undefine	Undefine	MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES
MBEDTLS_ENTROPY_FORCE_SHA256	Define Undefine	Undefine	MBEDTLS_ENTROPY_FORCE_SHA256
MBEDTLS_ENTROPY_NV_SEED	Define Undefine	Undefine	MBEDTLS_ENTROPY_NV_SEED
MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG
MBEDTLS_PSA_INJECT_ENTROPY	Define Undefine	Undefine	MBEDTLS_PSA_INJECT_ENTROPY
MBEDTLS_CTR_DRBG_C	Define Undefine	Define	MBEDTLS_CTR_DRBG_C
MBEDTLS_CTR_DRBG_C_ALT	Define	Define	MBEDTLS_CTR_DRBG_C_ALT
MBEDTLS_CTR_DRBG_ENTROPY_LEN	Define Undefine	Undefine	RNG|MBEDTLS_CTR_DRBG_ENTROPY_LEN
MBEDTLS_CTR_DRBG_ENTROPY_LEN value	Manual Entry	48	RNG value|MBEDTLS_CTR_DRBG_ENTROPY_LEN
MBEDTLS_CTR_DRBG_RESEED_INTERVAL	Define Undefine	Undefine	RNG|MBEDTLS_CTR_DRBG_RESEED_INTERVAL
MBEDTLS_CTR_DRBG_RESEED_INTERVAL value	Manual Entry	10000	RNG value|MBEDTLS_CTR_DRBG_RESEED_INTERVAL
MBEDTLS_CTR_DRBG_MAX_INPUT	Define Undefine	Undefine	MBEDTLS_CTR_DRBG_MAX_INPUT
MBEDTLS_CTR_DRBG_MAX_INPUT value	Manual Entry	256	MBEDTLS_CTR_DRBG_MAX_INPUT value
MBEDTLS_CTR_DRBG_MAX_REQUEST	Define Undefine	Undefine	MBEDTLS_CTR_DRBG_MAX_REQUEST
MBEDTLS_CTR_DRBG_MAX_REQUEST value	Manual Entry	1024	MBEDTLS_CTR_DRBG_MAX_REQUEST value
MBEDTLS_CTR_DRBG_MAX_SEED_INPUT	Define Undefine	Undefine	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT
MBEDTLS_CTR_DRBG_MAX_SEED_INPUT value	Manual Entry	384	MBEDTLS_CTR_DRBG_MAX_SEED_INPUT value
MBEDTLS_CTR_DRBG_USE_128_BIT_KEY	Define Undefine	Undefine	MBEDTLS_CTR_DRBG_USE_128_BIT_KEY
MBEDTLS_HMAC_DRBG_RESEED_INTERVAL	Define Undefine	Undefine	MBEDTLS_HMAC_DRBG_RESEED_INTERVAL
MBEDTLS_HMAC_DRBG_RESEED_INTERVAL value	Manual Entry	10000	MBEDTLS_HMAC_DRBG_RESEED_INTERVAL value
MBEDTLS_HMAC_DRBG_MAX_INPUT	Define Undefine	Undefine	MBEDTLS_HMAC_DRBG_MAX_INPUT
MBEDTLS_HMAC_DRBG_MAX_INPUT value	Manual Entry	256	MBEDTLS_HMAC_DRBG_MAX_INPUT value
MBEDTLS_HMAC_DRBG_MAX_REQUEST	Define Undefine	Undefine	MBEDTLS_HMAC_DRBG_MAX_REQUEST
MBEDTLS_HMAC_DRBG_MAX_REQUEST value	Manual Entry	1024	MBEDTLS_HMAC_DRBG_MAX_REQUEST value
MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT	Define Undefine	Undefine	MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT
MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT value	Manual Entry	384	MBEDTLS_HMAC_DRBG_MAX_SEED_INPUT value
MBEDTLS_ENTROPY_MAX_SOURCES	Define Undefine	Undefine	MBEDTLS_ENTROPY_MAX_SOURCES
MBEDTLS_ENTROPY_MAX_SOURCES value	Manual Entry	20	MBEDTLS_ENTROPY_MAX_SOURCES value
MBEDTLS_ENTROPY_MAX_GATHER	Define Undefine	Undefine	MBEDTLS_ENTROPY_MAX_GATHER
MBEDTLS_ENTROPY_MAX_GATHER value	Manual Entry	128	MBEDTLS_ENTROPY_MAX_GATHER value
MBEDTLS_ENTROPY_MIN_HARDWARE	Define Undefine	Undefine	MBEDTLS_ENTROPY_MIN_HARDWARE
MBEDTLS_ENTROPY_MIN_HARDWARE value	Manual Entry	32	MBEDTLS_ENTROPY_MIN_HARDWARE value
Key Configuration
MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS	Define Undefine	Undefine	MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS
PSA_CRYPTO_DRIVER_TFM_BUILTIN_KEY_LOADER	Define Undefine	Undefine	PSA_CRYPTO_DRIVER_TFM_BUILTIN_KEY_LOADER
MBEDTLS_PSA_KEY_SLOT_COUNT	Define Undefine	Undefine	MBEDTLS_PSA_KEY_SLOT_COUNT
MBEDTLS_PSA_KEY_SLOT_COUNT value	Manual Entry	32	MBEDTLS_PSA_KEY_SLOT_COUNT value
HMAC
MBEDTLS_PSA_HMAC_DRBG_MD_TYPE	Define Undefine	Define	MBEDTLS_PSA_HMAC_DRBG_MD_TYPE

SHA256 Configuration

To enable hardware acceleration for the SHA256/224 calculation, the macro MBEDTLS_SHA256_ALT and MBEDTLS_SHA256_PROCESS_ALT must be defined in the configuration file. By default SHA256 is enabled. SHA256 can be disabled, but SHA512 then needs to be enabled (software version) because the PSA implementation uses it for the entropy accumulator. This can be done using the RA Configuration editor.

AES Configuration

To enable hardware acceleration for the AES128/256 operation, the macro MBEDTLS_AES_SETKEY_ENC_ALT, MBEDTLS_AES_SETKEY_DEC_ALT, MBEDTLS_AES_ENCRYPT_ALT and MBEDTLS_AES_DECRYPT_ALT must be defined in the configuration file. By default AES is enabled. AES cannot be disabled because the PSA implementation requires it for the CTR_DRBG random number generator. This can be done using the RA Configuration editor.

Note

Only AES XTS 128 is currently supported. RA2 devices support acceleration for ECB part alone, while other devices support full AES XTS hardware acceleration.

ECC Configuration

To enable hardware acceleration for the ECC Key Generation operation, the macro MBEDTLS_ECP_ALT must be defined in the configuration file. For ECDSA, the macros MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_VERIFY_ALT must be defined. By default ECC, ECDSA and ECDHE are enabled. To disable ECC, undefine MBEDTLS_ECP_C, MBEDTLS_ECDSA_C and MBEDTLS_ECDH_C. This can be done using the RA Configuration editor.

RSA Configuration

To enable hardware acceleration for the RSA2048 operation, the macro MBEDTLS_RSA_ALT must be defined in the configuration file. By default RSA is enabled. To disable RSA, undefine MBEDTLS_RSA_C, MBEDTLS_PK_C, MBEDTLS_PK_PARSE_C, MBEDTLS_PK_WRITE_C. This can be done using the RA Configuration editor.

Wrapped Key Usage

To use the Secure Crypto Engine to generate and use wrapped keys, use PSA_KEY_TYPE_AES_WRAPPED or PSA_KEY_TYPE_ECC_KEY_PAIR_WRAPPED(curve) or PSA_KEY_TYPE_RSA_KEY_PAIR when setting the key type attribute. Setting the key's type attribute using this value will cause the SCE to use wrapped key mode for all operations related to that key. The user can use the export functionality to save the wrapped keys to user ROM and import it later for usage. This mode requires that Wrapped Key functionality for the algorithm is enabled in the project configuration.

Note

On the SCE9 devices, only the RSA public key can be exported. A file system must be used to store the internally generated private key.

Persistent Key Storage

Persistent key storage can be enabled by defining MBEDTLS_FS_IO, MBEDTLS_PSA_CRYPTO_STORAGE_C, and MBEDTLS_PSA_ITS_FILE_C. The key lifetime must also be specifed as PSA_KEY_LIFETIME_PERSISTENT. A lower level storage module must be added in the RA Configuration editor and initialized in the code before generating persistent keys. Persistent storage supports the use of plaintext and vendor keys. Refer to the lower level storage module documentation for information on how it should be initialized. To generate a persistent key the key must be assigned a unique id prior to calling generate using the psa_set_key_id api.

    if (PSA_KEY_LIFETIME_IS_PERSISTENT(lifetime))
    {
        /* Set the id to a positive integer. */
        psa_set_key_id(&attributes, (psa_key_id_t) 5);
    }

Platform Configuration

To run the mbedCrypto implementation of the PSA Crypto API on the MCU, the macro MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT must be defined in the configuration file. This enables code that will initialize the SCE. Parameter checking (General|MBEDTLS_CHECK_PARAMS) is enabled by default. To reduce code size, disable parameter checking.

Random Number Configuration

To run the mbedCrypto implementation of the PSA Crypto API on the MCU, the macro MBEDTLS_ENTROPY_HARDWARE_ALT must be defined in the configuration file. This enables using the TRNG as an entropy source. None of the other cryptographic operations (even in software only mode) will work without this feature.

Usage Notes

Hardware Initialization

mbedtls_platform_setup() must be invoked before using the PSA Crypto API to ensure that the SCE peripheral is initialized.

Memory Usage

In general, depending on the mbedCrypto features being used a heap size of 0x1000 to 0x5000 bytes is required. The total allocated heap should be the sum of the heap requirements of the individual algorithms:

Algorithm	Required Heap (bytes)
SHA256/224	None
AES	0x200
Hardware ECC	0x400
Software ECC	0x1800
RSA	0x1500

A minimum stack of 0x1000 is required where the module is used. This is either the main stack in a bare metal application or the task stack of the task used for crypto operations.

Limitations

• Only little endian mode is supported.

Stdio Buffering

The MBEDTLS_PLATFORM_SETBUF_MACRO was introduced in mbedTLS 3.2.1 to prevent stdio read/write functions from buffering stream data to reduce the likelihood of key leakage by setting the buffer argument in setbuf() to NULL. FSP uses a dummy_setbuf() function in rm_psa_crypto.c to prevent build errors; since FSP uses LittleFS by default (where the usage of a buffer is mandatory) this function does not perform any action. Setting the cache size in LittleFS to the minimum supported by the Data Flash (4) can minimize but not remove the likelihood of key data leakage. The dummy function can be replaced with a user-defined function by defining a different value for MBEDTLS_PLATFORM_SETBUF_MACRO_value in the FSP configurator.

SCE9 Usage

The SCE9 is used in Compatibility Mode for mbedCrypto acceleration. The crypto capabilities in this mode on the SCE9 are different which results in the below usage limitations with mbedCrypto:

• The module includes both wrapped and plaintext keys code irrespective of whether the application requires it.
• Plaintext key generation is not supported for RSA and ECC; only wrapped keys can be generated.
• If ECDH is used, only wrapped key will be generated on SCE9 and will not return an error even if the user context is somehow set for plain key. This may be relevant only if the psa_key_agreement() function with plaintext key on SCE9 is attempted.

Note

For a detailed description of the different SCE9 operating modes, refer to Application Note R11AN0498.

Using PSA Crypto with TrustZone

Unlike FSP drivers, PSA Crypto cannot be configured as Non-secure callable in the RA Configurator for a secure project. The reason for this is that in order to achieve the security objective of controlling access to protected keys, both the PSA Crypto code as well as the keys must be placed in the secure region. Since the PSA Crypto API requires access to the keys directly during initialization and later via a key handle, allowing non-secure code to use the API by making it Non-secure callable will require the keys to be stored in non-secure memory.

This section will provide a short explanation of how to add PSA Crypto to a secure project and have it usable by the non-secure project without exposing the keys. In this example the secure project will contain an RSA private key and the non-secure project is expected to be able to perform sign and verify operations using that key.

PSA Crypto Non-secure callable example

• Secure project
  • During secure project boot-up, psa_crypto_init() is called.
  • The RSA private key is programmed into secure flash either at the factory or by calling psa_generate_key() in persistent mode. Note that the data-flash area used by the LittleFS will have to be in the secure region if the key is generated as a persistent.
  • psa_import_key()/psa_open_key() are called with the resultant handle held in secure RAM.
  • The Non-secure callable section contains the following user-defined functions
  • verify_with_my_rsa_key(input_signature, input_hash, verification_result)
  • The implementation of this function in secure region will call psa_verify_hash() and return the result via verification_result.
  • sign_with_my_rsa_key(input_hash, output_signature)
  • The implementation of this function in secure region will call psa_sign_hash() and return the signature via output_signature.

• Non-secure project

  • Calls verify_with_my_rsa_key() to verify a signature. The implementation will use the public key that is present in the secure project.
  • Calls sign_with_my_rsa_key() to generate a signature. The implementation will use the private key that is present on the secure project.

  For more details on how to add user-code to the Non-secure callable region refer to the "Security Design with Arm TrustZone - IP Protection (R11AN0467EU0100)" Application Note.

Examples

Hash Example

This is an example on calculating the SHA256 hash using the PSA Crypto API.

const uint8_t NIST_SHA256ShortMsgLen200[] =
{
    0x2e, 0x7e, 0xa8, 0x4d, 0xa4, 0xbc, 0x4d, 0x7c, 0xfb, 0x46, 0x3e, 0x3f, 0x2c, 0x86, 0x47, 0x05,
    0x7a, 0xff, 0xf3, 0xfb, 0xec, 0xec, 0xa1, 0xd2, 00
};
const uint8_t NIST_SHA256ShortMsgLen200_expected[] =
{
    0x76, 0xe3, 0xac, 0xbc, 0x71, 0x88, 0x36, 0xf2, 0xdf, 0x8a, 0xd2, 0xd0, 0xd2, 0xd7, 0x6f, 0x0c,
    0xfa, 0x5f, 0xea, 0x09, 0x86, 0xbe, 0x91, 0x8f, 0x10, 0xbc, 0xee, 0x73, 0x0d, 0xf4, 0x41, 0xb9
};
void psa_crypto_sha256_example (void)
{
    psa_algorithm_t      alg               = PSA_ALG_SHA_256;
    psa_hash_operation_t operation         = {0};
    size_t               expected_hash_len = PSA_HASH_LENGTH(alg);
    uint8_t              actual_hash[PSA_HASH_MAX_SIZE];
    size_t               actual_hash_len;

    mbedtls_platform_context ctx = {0};

    /* Setup the platform; initialize the SCE and the TRNG */
    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))
    {
        /* Platform initialization failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_hash_setup(&operation, alg))
    {
        /* Hash setup failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_hash_update(&operation, NIST_SHA256ShortMsgLen200, sizeof(NIST_SHA256ShortMsgLen200)))
    {
        /* Hash calculation failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_hash_finish(&operation, &actual_hash[0], sizeof(actual_hash), &actual_hash_len))
    {
        /* Reading calculated hash failed */
        debugger_break();
    }
    else if (0 != memcmp(&actual_hash[0], &NIST_SHA256ShortMsgLen200_expected[0], actual_hash_len))
    {
        /* Hash compare of calculated value with expected value failed */
        debugger_break();
    }
    else if (0 != memcmp(&expected_hash_len, &actual_hash_len, sizeof(expected_hash_len)))
    {
        /* Hash size compare of calculated value with expected value failed */
        debugger_break();
    }
    else
    {
        /* SHA256 calculation succeeded */
        debugger_break();
    }


    /* De-initialize the platform. This is currently a placeholder function which does not do anything. */
    mbedtls_platform_teardown(&ctx);

}

AES Example

This is an example on using the PSA Crypto API to generate an AES256 key, encrypting and decrypting multi-block data and using PKCS7 padding.

static psa_status_t cipher_operation (psa_cipher_operation_t * operation,
                                      const uint8_t          * input,
                                      size_t                   input_size,
                                      size_t                   part_size,
                                      uint8_t                * output,
                                      size_t                   output_size,
                                      size_t                 * output_len)
{
    psa_status_t status;
    size_t       bytes_to_write = 0;
    size_t       bytes_written  = 0;
    size_t       len            = 0;

    *output_len = 0;
    while (bytes_written != input_size)
    {
        bytes_to_write = (input_size - bytes_written > part_size ?
                          part_size :
                          input_size - bytes_written);

        status = psa_cipher_update(operation,
                                   input + bytes_written,
                                   bytes_to_write,
                                   output + *output_len,
                                   output_size - *output_len,
                                   &len);
        if (PSA_SUCCESS != status)
        {
            return status;
        }

        bytes_written += bytes_to_write;
        *output_len   += len;
    }

    status = psa_cipher_finish(operation, output + *output_len, output_size - *output_len, &len);
    if (PSA_SUCCESS != status)
    {
        return status;
    }

    *output_len += len;

    return status;
}

void psa_crypto_aes256cbcmultipart_example (void)
{
    enum
    {
        block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH(PSA_KEY_TYPE_AES), 
        key_bits   = 256,
        input_size = 100,
        part_size  = 10,
    };

    mbedtls_platform_context ctx         = {0};
    const psa_algorithm_t    alg         = PSA_ALG_CBC_PKCS7;
    psa_cipher_operation_t   operation_1 = PSA_CIPHER_OPERATION_INIT;
    psa_cipher_operation_t   operation_2 = PSA_CIPHER_OPERATION_INIT;
    size_t iv_len = 0;

    psa_key_handle_t     key_handle        = 0;
    size_t               encrypted_length  = 0;
    size_t               decrypted_length  = 0;
    uint8_t              iv[block_size]    = {0};
    uint8_t              input[input_size] = {0};
    uint8_t              encrypted_data[input_size + block_size] = {0};
    uint8_t              decrypted_data[input_size + block_size] = {0};
    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
    psa_key_lifetime_t   lifetime;

    /* Setup the platform; initialize the SCE */
    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))
    {
        /* Platform initialization failed */
        debugger_break();
    }

    if (PSA_SUCCESS != psa_crypto_init())
    {
        /* PSA Crypto Initialization failed */
        debugger_break();
    }

    /* Set key attributes */
    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT);
    psa_set_key_algorithm(&attributes, alg);

    /* To use wrapped keys instead of plaintext use PSA_KEY_TYPE_AES_WRAPPED. */
    psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
    psa_set_key_bits(&attributes, key_bits);

    lifetime = PSA_KEY_LIFETIME_VOLATILE;

    /* To use persistent keys:
     *......Use a lifetime value of PSA_KEY_LIFETIME_PERSISTENT
     * -    The file system must be initialized prior to calling the generate/import key functions.
     * -    Refer to the littlefs example to see how to format and mount the filesystem. */
    psa_set_key_lifetime(&attributes, lifetime);

    if (PSA_KEY_LIFETIME_IS_PERSISTENT(lifetime))
    {
        /* Set the id to a positive integer. */
        psa_set_key_id(&attributes, (psa_key_id_t) 5);
    }


    if (PSA_SUCCESS != psa_generate_random(input, sizeof(input)))
    {
        /* Random number generation for input data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        /* Generating AES 256 key and allocating to key slot failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_encrypt_setup(&operation_1, key_handle, alg))
    {
        /* Initializing the encryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_generate_iv(&operation_1, iv, sizeof(iv), &iv_len))
    {
        /* Generating the random IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_1, input, input_size, part_size, encrypted_data, sizeof(encrypted_data),
                              &encrypted_length))
    {
        /* Encryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_1))
    {
        /* Terminating the encryption operation failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_decrypt_setup(&operation_2, key_handle, alg))
    {
        /* Initializing the decryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_set_iv(&operation_2, iv, sizeof(iv)))
    {
        /* Setting the IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_2, encrypted_data, encrypted_length, part_size, decrypted_data,
                              sizeof(decrypted_data), &decrypted_length))
    {
        /* Decryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_2))
    {
        /* Terminating the decryption operation failed */
        debugger_break();
    }
    else if (0 != memcmp(input, decrypted_data, sizeof(input)))
    {
        /* Comparing the input data with decrypted data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_destroy_key(key_handle))
    {
        /* Destroying the key handle failed */
        debugger_break();
    }
    else
    {
        /* All the operations succeeded */
    }

    /* Close the SCE */
    mbedtls_platform_teardown(&ctx);
}

void psa_crypto_aes128xtsmultipart_example (void)
{
    enum
    {
        block_size = PSA_BLOCK_CIPHER_BLOCK_LENGTH(PSA_KEY_TYPE_AES), 
        key_bits   = 256,
        input_size = 32,
        part_size  = 16,
    };

    mbedtls_platform_context ctx         = {0};
    const psa_algorithm_t    alg         = PSA_ALG_XTS;
    psa_cipher_operation_t   operation_1 = PSA_CIPHER_OPERATION_INIT;
    psa_cipher_operation_t   operation_2 = PSA_CIPHER_OPERATION_INIT;
    size_t iv_len = 0;

    psa_key_handle_t     key_handle        = 0;
    size_t               encrypted_length  = 0;
    size_t               decrypted_length  = 0;
    uint8_t              iv[block_size]    = {0};
    uint8_t              input[input_size] = {0};
    uint8_t              encrypted_data[input_size] = {0};
    uint8_t              decrypted_data[input_size] = {0};
    psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
    psa_key_lifetime_t   lifetime;

    /* Setup the platform; initialize the SCE */
    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))
    {
        /* Platform initialization failed */
        debugger_break();
    }

    if (PSA_SUCCESS != psa_crypto_init())
    {
        /* PSA Crypto Initialization failed */
        debugger_break();
    }

    /* Set key attributes */
    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT | PSA_KEY_USAGE_DECRYPT);
    psa_set_key_algorithm(&attributes, alg);

    /* To use wrapped keys instead of plaintext use PSA_KEY_TYPE_AES_WRAPPED. */
    /* When using XTS mode, since there are two keys used, the key_bits value is twice the AES key length.
     * For AES 128 XTS mode, the key_bits value is 256. MbedTLS only supports AES 128 currently. */
    psa_set_key_type(&attributes, PSA_KEY_TYPE_AES);
    psa_set_key_bits(&attributes, key_bits);

    lifetime = PSA_KEY_LIFETIME_VOLATILE;

    /* To use persistent keys:
     *......Use a lifetime value of PSA_KEY_LIFETIME_PERSISTENT
     * -    The file system must be initialized prior to calling the generate/import key functions.
     * -    Refer to the littlefs example to see how to format and mount the filesystem. */
    psa_set_key_lifetime(&attributes, lifetime);

    if (PSA_KEY_LIFETIME_IS_PERSISTENT(lifetime))
    {
        /* Set the id to a positive integer. */
        psa_set_key_id(&attributes, (psa_key_id_t) 5);
    }


    if (PSA_SUCCESS != psa_generate_random(input, sizeof(input)))
    {
        /* Random number generation for input data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        /* Generating AES 256 key and allocating to key slot failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_encrypt_setup(&operation_1, key_handle, alg))
    {
        /* Initializing the encryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_generate_iv(&operation_1, iv, sizeof(iv), &iv_len))
    {
        /* Generating the random IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_1, input, sizeof(input), part_size, encrypted_data, sizeof(encrypted_data),
                              &encrypted_length))
    {
        /* Encryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_1))
    {
        /* Terminating the encryption operation failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_decrypt_setup(&operation_2, key_handle, alg))
    {
        /* Initializing the decryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_set_iv(&operation_2, iv, sizeof(iv)))
    {
        /* Setting the IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_2, encrypted_data, encrypted_length, part_size, decrypted_data,
                              sizeof(decrypted_data), &decrypted_length))
    {
        /* Decryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_2))
    {
        /* Terminating the decryption operation failed */
        debugger_break();
    }
    else if (0 != memcmp(input, decrypted_data, sizeof(input)))
    {
        /* Comparing the input data with decrypted data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_destroy_key(key_handle))
    {
        /* Destroying the key handle failed */
        debugger_break();
    }
    else
    {
        /* All the operations succeeded */
    }


    /* Close the SCE */
    mbedtls_platform_teardown(&ctx);
}

AES-CCM Example

This is an example on using the PSA Crypto API to generate an AES256 key, encrypting and decrypting multi-block data and using PKCS7 padding using AES-CCM.

    if (PSA_SUCCESS != psa_generate_random(input, sizeof(input)))
    {
        /* Random plaintext input generation failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        /* Key generation failed */
        debugger_break();
    }
    /* AES-CCM Encryption */
    else if (PSA_SUCCESS !=
             psa_aead_encrypt(key_handle, PSA_ALG_CCM, nonce, sizeof(nonce), additional_data, sizeof(additional_data),
                              input, sizeof(input), encrypt, sizeof(encrypt), &output_len))
    {
        /* AES-CCM Encryption failed */
        debugger_break();
    }
    /* AES-CCM Decryption */
    else if (PSA_SUCCESS !=
             psa_aead_decrypt(key_handle, PSA_ALG_CCM, nonce, sizeof(nonce), additional_data, sizeof(additional_data),
                              encrypt, output_len, decrypt, sizeof(decrypt), &output_len))
    {
        /* AES-CCM Decryption failed */
        debugger_break();
    }
    else if (0U != memcmp(input, decrypt, sizeof(input)))
    {
        /* The decrypted result did not match the plaintext input */
        debugger_break();
    }
    else
    {
        /* All operations were successful */
    }

AES-XTS Example

This is an example on using the PSA Crypto API to generate an AES128 XTS key, encrypting and decrypting multi-block data.

    if (PSA_SUCCESS != psa_generate_random(input, sizeof(input)))
    {
        /* Random number generation for input data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        /* Generating AES 256 key and allocating to key slot failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_encrypt_setup(&operation_1, key_handle, alg))
    {
        /* Initializing the encryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_generate_iv(&operation_1, iv, sizeof(iv), &iv_len))
    {
        /* Generating the random IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_1, input, sizeof(input), part_size, encrypted_data, sizeof(encrypted_data),
                              &encrypted_length))
    {
        /* Encryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_1))
    {
        /* Terminating the encryption operation failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_decrypt_setup(&operation_2, key_handle, alg))
    {
        /* Initializing the decryption (with PKCS7 padding) operation handle failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_set_iv(&operation_2, iv, sizeof(iv)))
    {
        /* Setting the IV failed */
        debugger_break();
    }
    else if (PSA_SUCCESS !=
             cipher_operation(&operation_2, encrypted_data, encrypted_length, part_size, decrypted_data,
                              sizeof(decrypted_data), &decrypted_length))
    {
        /* Decryption failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_cipher_abort(&operation_2))
    {
        /* Terminating the decryption operation failed */
        debugger_break();
    }
    else if (0 != memcmp(input, decrypted_data, sizeof(input)))
    {
        /* Comparing the input data with decrypted data failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_destroy_key(key_handle))
    {
        /* Destroying the key handle failed */
        debugger_break();
    }
    else
    {
        /* All the operations succeeded */
    }

CMAC Example

This is an example on using the PSA Crypto API to generate an AES256 key, followed by generation and verification of MAC for random data of known length.

    if (PSA_SUCCESS != psa_generate_random(input, sizeof(input)))
    {
        /* Random number generation failure */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        /* Key generation failure */
        debugger_break();
    }
    /* Steps to generate the MAC */
    else if (PSA_SUCCESS != psa_mac_sign_setup(&operation, key_handle, alg))
    {
        /* MAC Sign setup failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_mac_update(&operation, input, input_size))
    {
        /* MAC update failed */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_mac_sign_finish(&operation, AES_CMAC_mac, sizeof(AES_CMAC_mac), &mac_ret))
    {
        /* MAC Sign operation failed */
        debugger_break();
    }
    else
    {
        /* All the operations succeeded for MAC generation */
    }

    /* Steps to verify the generated MAC */

    if (PSA_SUCCESS != psa_mac_verify_setup(&verify_operation, key_handle, alg))
    {
        /* MAC verification setup failure */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_mac_update(&verify_operation, input, input_size))
    {
        /* MAC update failure */
        debugger_break();
    }
    else if (PSA_SUCCESS != psa_mac_verify_finish(&verify_operation, AES_CMAC_mac, mac_ret))
    {
        /* MAC verification failed */
        debugger_break();
    }
    else
    {
        /* All the operations succeeded for MAC verification */
    }

ECC Example

This is an example on using the PSA Crypto API to generate an ECC-P256R1 key, signing and verifying data after hashing it first using SHA256.

Note

Unlike RSA, ECDSA does not have any padding schemes. Thus the hash argument for the ECC sign operation MUST have a size larger than or equal to the curve size; i.e. for PSA_ECC_CURVE_SECP256R1 the payload size must be at least 256/8 bytes. nist.fips.186-4: " A hash function that provides a lower security strength than the security strength associated with the bit length of 'n' ordinarily should not be used, since this would reduce the security strength of the digital signature process to a level no greater than that provided by the hash function."

#define ECC_256_BIT_LENGTH       256
#define ECC_256_EXPORTED_SIZE    500
uint8_t exportedECC_SECP256R1Key[ECC_256_EXPORTED_SIZE];
size_t  exportedECC_SECP256R1Keylength = 0;
void psa_ecc256R1_example (void)
{
/* This example generates an ECC-P256R1 keypair, performs signing and verification operations.
 * It then exports the generated key into ASN1 DER format to a RAM array which can then be programmed to flash.
 * It then re-imports that key, and performs signing and verification operations. */
    unsigned char            payload[] = "ASYMMETRIC_INPUT_FOR_SIGN......";
    unsigned char            signature1[PSA_SIGNATURE_MAX_SIZE] = {0};
    unsigned char            signature2[PSA_SIGNATURE_MAX_SIZE] = {0};
    size_t                   signature_length1 = 0;
    size_t                   signature_length2 = 0;
    psa_key_attributes_t     attributes        = PSA_KEY_ATTRIBUTES_INIT;
    psa_key_attributes_t     read_attributes   = PSA_KEY_ATTRIBUTES_INIT;
    mbedtls_platform_context ctx               = {0};
    psa_key_handle_t         ecc_key_handle    = {0};

    psa_hash_operation_t hash_operation = {0};
    uint8_t              payload_hash[PSA_HASH_MAX_SIZE];
    size_t               payload_hash_len;

    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))
    {
        debugger_break();
    }

    if (PSA_SUCCESS != psa_crypto_init())
    {
        debugger_break();
    }

    /* Set key attributes */
    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH | PSA_KEY_USAGE_EXPORT);
    psa_set_key_algorithm(&attributes, PSA_ALG_ECDSA(PSA_ALG_SHA_256));

    /* To use wrapped keys instead of plaintext:
     * - Use PSA_KEY_TYPE_ECC_KEY_PAIR_WRAPPED(PSA_ECC_FAMILY_SECP_R1).*/
    psa_set_key_type(&attributes, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1));
    psa_set_key_bits(&attributes, ECC_256_BIT_LENGTH);

    /* To use persistent keys instead of volatile:
     * -     Use PSA_KEY_LIFETIME_PERSISTENT.
     * -    The file system must be initialized prior to calling the generate/import key functions.
     * -    Refer to the littlefs example to see how to format and mount the filesystem. */
    psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_VOLATILE);

    /* Generate ECC P256R1 Key pair */
    if (PSA_SUCCESS != psa_generate_key(&attributes, &ecc_key_handle))
    {
        debugger_break();
    }

    /* Test the key information */
    if (PSA_SUCCESS != psa_get_key_attributes(ecc_key_handle, &read_attributes))
    {
        debugger_break();
    }

    /* Calculate the hash of the message */
    if (PSA_SUCCESS != psa_hash_setup(&hash_operation, PSA_ALG_SHA_256))
    {
        debugger_break();
    }

    if (PSA_SUCCESS != psa_hash_update(&hash_operation, payload, sizeof(payload)))
    {
        debugger_break();
    }

    if (PSA_SUCCESS !=
        psa_hash_finish(&hash_operation, &payload_hash[0], sizeof(payload_hash), &payload_hash_len))
    {
        debugger_break();
    }

    /* Sign message using the private key
     * NOTE: The hash argument (payload_hash here) MUST have a size equal to the curve size;
     * i.e. for SECP256R1 the payload size must be 256/8 bytes.
     * Similarly for SECP384R1 the payload size must be 384/8 bytes.
     * nist.fips.186-4: " A hash function that provides a lower security strength than
     * the security strength associated with the bit length of 'n' ordinarily should not be used, since this
     * would reduce the security strength of the digital signature process to a level no greater than that
     * provided by the hash function." */
    if (PSA_SUCCESS !=
        psa_sign_hash(ecc_key_handle, PSA_ALG_ECDSA(PSA_ALG_SHA_256), payload_hash, payload_hash_len, signature1,
                      sizeof(signature1), &signature_length1))
    {
        debugger_break();
    }

    /* Verify the signature1 using the public key */
    if (PSA_SUCCESS !=
        psa_verify_hash(ecc_key_handle, PSA_ALG_ECDSA(PSA_ALG_SHA_256), payload_hash, payload_hash_len, signature1,
                        signature_length1))
    {
        debugger_break();
    }

    /* Export the key. The exported key can then be save to flash for later usage.  */
    if (PSA_SUCCESS !=
        psa_export_key(ecc_key_handle, exportedECC_SECP256R1Key, sizeof(exportedECC_SECP256R1Key),
                       &exportedECC_SECP256R1Keylength))
    {
        debugger_break();
    }

    /* Destroy the key and handle */
    if (PSA_SUCCESS != psa_destroy_key(ecc_key_handle))
    {
        debugger_break();
    }

    /* Import the previously exported key pair */
    if (PSA_SUCCESS !=
        psa_import_key(&attributes, exportedECC_SECP256R1Key, exportedECC_SECP256R1Keylength, &ecc_key_handle))
    {
        debugger_break();
    }

    /* Sign message using the private key */
    if (PSA_SUCCESS !=
        psa_sign_hash(ecc_key_handle, PSA_ALG_ECDSA(PSA_ALG_SHA_256), payload_hash, payload_hash_len, signature2,
                      sizeof(signature2), &signature_length2))
    {
        debugger_break();
    }

    /* Verify signature2 using the public key */
    if (PSA_SUCCESS !=
        psa_verify_hash(ecc_key_handle, PSA_ALG_ECDSA(PSA_ALG_SHA_256), payload_hash, payload_hash_len, signature2,
                        signature_length2))
    {
        debugger_break();
    }

    /* Signatures cannot be compared since ECC signatures vary for the same data unless Deterministic ECC is used which is not supported by the HW.
     * Only the verification operation can be used to validate signatures. */
}

RSA Example

This is an example on using the PSA Crypto API to generate an RSA2048 key, encrypting and decrypting multi-block data and using PKCS7 padding.

#define RSA_2048_BIT_LENGTH       2048
#define RSA_2048_EXPORTED_SIZE    1210

/* The RSA 2048 key pair export in der format is roughly as follows
 * RSA private keys:
 *  RSAPrivateKey ::= SEQUENCE {   ---------------------------------------  1 + 3
 *      version           Version, ---------------------------------------  1 + 1 + 1
 *      modulus           INTEGER, ---------------- n  -------------------  1 + 3 + 256 + 1
 *      publicExponent    INTEGER, ---------------- e  -------------------  1 + 4
 *      privateExponent   INTEGER, ---------------- d  -------------------  1 + 3 + 256 (276 for Wrapped)
 *      prime1            INTEGER, ---------------- p  -------------------  1 + 3 + (256 / 2)
 *      prime2            INTEGER, ---------------- q  -------------------  1 + 3 + (256 / 2)
 *      exponent1         INTEGER, ---------------- d mod (p-1)  ---------  1 + 2 + (256 / 2) (4 for Wrapped)
 *      exponent2         INTEGER, ---------------- d mod (q-1)  ---------  1 + 2 + (256 / 2) (4 for Wrapped)
 *      coefficient       INTEGER, ---------------- (inverse of q) mod p -  1 + 2 + (256 / 2) (4 for Wrapped)
 *      otherPrimeInfos   OtherPrimeInfos OPTIONAL ------------------------ 0 (not supported)
 *  }
 */

uint8_t exportedRSA2048Key[RSA_2048_EXPORTED_SIZE];
size_t  exportedRSA2048Keylength = 0;
void psa_rsa2048_example (void)
{
/* This example generates an RSA2048 keypair, performs signing and verification operations.
 * It then exports the generated key into ASN1 DER format to a RAM array which can then be programmed to flash.
 * It then re-imports that key, and performs signing and verification operations. */

    mbedtls_platform_context ctx        = {0};
    psa_key_handle_t         key_handle = {0};
    unsigned char            payload[]  = "ASYMMETRIC_INPUT_FOR_SIGN";
    unsigned char            signature1[PSA_SIGNATURE_MAX_SIZE] = {0};
    unsigned char            signature2[PSA_SIGNATURE_MAX_SIZE] = {0};
    size_t               signature_length1 = 0;
    size_t               signature_length2 = 0;
    psa_key_attributes_t attributes        = PSA_KEY_ATTRIBUTES_INIT;
    psa_key_attributes_t read_attributes   = PSA_KEY_ATTRIBUTES_INIT;

    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))
    {
        debugger_break();
    }

    if (PSA_SUCCESS != psa_crypto_init())
    {
        debugger_break();
    }

    /* Set key attributes */
    psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_HASH | PSA_KEY_USAGE_VERIFY_HASH | PSA_KEY_USAGE_EXPORT);
    psa_set_key_algorithm(&attributes, PSA_ALG_RSA_PKCS1V15_SIGN_RAW);

    /* To use wrapped keys instead of plaintext:
     * - Use PSA_KEY_TYPE_RSA_KEY_PAIR_WRAPPED. */
    psa_set_key_type(&attributes, PSA_KEY_TYPE_RSA_KEY_PAIR);
    psa_set_key_bits(&attributes, RSA_2048_BIT_LENGTH);

    /* To use persistent keys instead of volatile:
     * -    Use PSA_KEY_LIFETIME_PERSISTENT.
     * -    The file system must be initialized prior to calling the generate/import key functions.
     * -    Refer to the littlefs example to see how to format and mount the filesystem. */
    psa_set_key_lifetime(&attributes, PSA_KEY_LIFETIME_VOLATILE);

    /* Generate RSA 2048 Key pair */
    if (PSA_SUCCESS != psa_generate_key(&attributes, &key_handle))
    {
        debugger_break();
    }

    /* Test the key information */
    if (PSA_SUCCESS != psa_get_key_attributes(key_handle, &read_attributes))
    {
        debugger_break();
    }

    /* Sign message using the private key */
    if (PSA_SUCCESS !=
        psa_sign_hash(key_handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW, payload, sizeof(payload), signature1,
                      sizeof(signature1), &signature_length1))
    {
        debugger_break();
    }

    /* Verify the signature1 using the public key */
    if (PSA_SUCCESS !=
        psa_verify_hash(key_handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW, payload, sizeof(payload), signature1,
                        signature_length1))
    {
        debugger_break();
    }

    /* Export the key */
    if (PSA_SUCCESS !=
        psa_export_key(key_handle, exportedRSA2048Key, sizeof(exportedRSA2048Key), &exportedRSA2048Keylength))
    {
        debugger_break();
    }

    /* Destroy the key and handle */
    if (PSA_SUCCESS != psa_destroy_key(key_handle))
    {
        debugger_break();
    }

    /* Import the previously exported key pair */
    if (PSA_SUCCESS != psa_import_key(&attributes, exportedRSA2048Key, exportedRSA2048Keylength, &key_handle))
    {
        debugger_break();
    }

    /* Sign message using the private key */
    if (PSA_SUCCESS !=
        psa_sign_hash(key_handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW, payload, sizeof(payload), signature2,
                      sizeof(signature2), &signature_length2))
    {
        debugger_break();
    }

    /* Verify signature2 using the public key */
    if (PSA_SUCCESS !=
        psa_verify_hash(key_handle, PSA_ALG_RSA_PKCS1V15_SIGN_RAW, payload, sizeof(payload), signature2,
                        signature_length2))
    {
        debugger_break();
    }

    /* Compare signatures to verify that the same signature was generated */
    if (0 != memcmp(signature2, signature1, signature_length2))
    {
        debugger_break();
    }

    mbedtls_psa_crypto_free();
    mbedtls_platform_teardown(&ctx);
}

Function Documentation

mbedtls_platform_setup()

int mbedtls_platform_setup

(

mbedtls_platform_context *

ctx

)

This function initializes the SCE and the TRNG. It must be invoked before the crypto library can be used. This implementation is used if MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT is defined.

Example:

    mbedtls_platform_context ctx = {0};

    /* Setup the platform; initialize the SCE and the TRNG */
    if (PSA_SUCCESS != mbedtls_platform_setup(&ctx))

Return values

0	Initialization was successful.
MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED	SCE Initialization error.

mbedtls_platform_teardown()

void mbedtls_platform_teardown

(

mbedtls_platform_context *

ctx

)

This implementation is used if MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT is defined. It is intended to de-initialize any items that were initialized in the mbedtls_platform_setup() function, but currently is only a placeholder function.

Example:

    /* De-initialize the platform. This is currently a placeholder function which does not do anything. */
    mbedtls_platform_teardown(&ctx);

Return values

N/A

RM_PSA_CRYPTO_TRNG_Read()

fsp_err_t RM_PSA_CRYPTO_TRNG_Read	(	uint8_t *const	p_rngbuf,
		uint32_t	num_req_bytes,
		uint32_t *	p_num_gen_bytes
	)

Reads requested length of random data from the TRNG. Generate nbytes of random bytes and store them in p_rngbuf buffer.

Return values

FSP_SUCCESS	Random number generation successful
FSP_ERR_ASSERTION	NULL input parameter(s).
FSP_ERR_CRYPTO_UNKNOWN	An unknown error occurred.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• s_generate_16byte_random_data