Overview
========

Secure Enclave Userspace Library exposes the user application with API(s) for:
- HSM
- SHE

These API(s) are consumed and responded by the NXP HW IP(s):
- Secure Enclave like SECO, ELE400, ELE401, etc., for HSM API(s) and
- V2X for SHE, HSM API(s).

Scope of the document:
	1. Platforms supported by the library
	2. How to Build
	3. Installation steps
	4. Testing Steps
	5. Documentation
	6. Licensing
	7. Change Log

Abbreviations Used
==================

ELE: EdgeLock Secure Enclave
----------------------------
EdgeLock Secure Enclave is a preconfigured, self-managed and autonomous on-die
security subsystem, to help in implementing robust and secure system. This
built-in security subsystem provides scalable options to deploy the security
for thousands of edge applications.

SECO: Security Controller
---------------------------
SECO(Security Controller) is the security subsystem which primarily authenticate
the firmware and user images, authorizing their execution. This controller is
dedicated to specific security functions.

SHE: Secure Hardware Extension
------------------------------
SHE is designed by following the SHE functional specification. One typical example
of SHE use case is to generate and verify secure messages over a car CAN interface.

V2X: Vehicle to Everything
--------------------------
V2X is a crypto accelerator providing similar cryptographic capabilities as
ELE/SECO. It is mostly used for message signature generation and verification.

NVM (Non-Volatile Memory) Manager
---------------------------------
NVM Manager, is Linux Kernel daemon linked to shared library (libxxx_nvm.so),
It is a slave to the ELE FW, and manages storage as directed by FW. The storage
is maintained on the Linux Filesystem, at rest.


1. Supported Platforms
======================

Build Types
-----------
Secure Enclave library build types:
	- ele     (ELE-HSM)
	- seco    (SECO-SHE + SECO-HSM)
	- v2x     (V2X-SHE + V2X-HSM)


Table 1: Supported Secure Enclave Library Artifacts Type for each platform
--------------------------------------------------------------------------

+----------+-----------------------------------------------------------+
|          |                  Supported Library Artifacts Type         |
+----------+---------+-----------------------+-------------------------+
| Platform |   ele   |          v2x          |          SECO           |
+----------+---------+-----------+-----------+------------+------------+
|          | ELE-HSM |  V2X-SHE  |  V2X-HSM  |  SECO-HSM  |  SECO-SHE  |
+==========+=========+===========+===========+============+============+
| i.MX8ULP |   YES   |    NA     |     NA    |     NA     |     NA     |
+----------+---------+-----------+-----------+------------+------------+
| i.MX93   |   YES   |    NA     |     NA    |     NA     |     NA     |
+----------+---------+-----------+-----------+------------+------------+
| i.MX95   |   YES   |    YES    |     YES   |     NA     |     NA     |
+----------+---------+-----------+-----------+------------+------------+
| i.MX91   |   YES   |    NA     |     NA    |     NA     |     NA     |
+----------+---------+-----------+-----------+------------+------------+
| i.MX8DXL |   NA    |    YES    |     YES   |     YES    |     YES    |
+----------+---------+-----------+-----------+------------+------------+
| i.MX8QXP |   NA    |    NA     |     NA    |     YES    |     YES    |
+----------+---------+-----------+-----------+------------+------------+


Table 2: Secure Enclave Storage (NVM) directories
-------------------------------------------------

+--------+----------------------------------+-------------------+-----------------+
| H/W IP |               Platform           |        HSM        |       SHE       |
+========+==================================+===================+=================+
|  ELE   |   i.MX8ULP/i.MX93/i.MX95/i.MX91  |    /etc/ele/      |     N/A         |
|        |                                  |                   |                 |
|--------+----------------------------------+-------------------+-----------------+
|  V2X   |            i.MX95                |   /etc/v2x_hsm/   |  /etc/v2x_she/  |
+--------+----------------------------------+-------------------+-----------------+
|  V2X   |           i.MX8DXL               |   /etc/v2x_hsm/   |  /etc/v2x_she/  |
+--------+----------------------------------+-------------------+-----------------+
|  SECO  |           i.MX8DXL               |   /etc/hsm/       |  /etc/she/      |
+--------+----------------------------------+-------------------+-----------------+
|  SECO  |           i.MX8QXP               |   /etc/hsm/       |  /etc/she/      |
+--------+----------------------------------+-------------------+-----------------+


2. How to Build
===============

2.1 Environment
===============

Toolchain
---------

- Download the required toolchain

	https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

	e.g. gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu


Secure Enclave Build Procedure
------------------------------

-  Fetch the above repository into the local host
-  Configure the toolchain, and the environment varibles,
   "CROSS_COMPILE", "CC", "AR", "RANLIB".
-  Follow the compilation steps, as described below.


Secure Enclave library code repo
--------------------------------

	git clone https://github.com/nxp-imx/imx-secure-enclave.git

	cd imx-secure-enclave/

	git checkout lf-6.6.36_2.1.0


Secure Enclave Environment Setup
---------------------------------

	export CROSS_COMPILE=$TOOLCHAIN_PATH;
	export CC=${CROSS_COMPILE}gcc;
	export AR=${CROSS_COMPILE}ar;
	export RANLIB=${CROSS_COMPILE}ranlib;

	Example:
	--------

	export CROSS_COMPILE=/opt/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-;
	export CC=${CROSS_COMPILE}gcc;
	export AR=${CROSS_COMPILE}ar;
	export RANLIB=${CROSS_COMPILE}ranlib;


2.2 Secure Enclave Library build steps
======================================

Build Types: ele (PLAT=ele) or (PLAT=seco) or v2x (No PLAT input)

-To clean

	make PLAT=$PLAT clean;

-To compile libraries

	make PLAT=$PLAT COMPATIBLE_MACHINE=$MACHINE libs;

-To compile libraries and install

	make PLAT=$PLAT COMPATIBLE_MACHINE=$MACHINE libs install;

-To compile libraries and install, with custom installation path

	make PLAT=$PLAT COMPATIBLE_MACHINE=$MACHINE DESTDIR=$DESTDIR_PATH libs install;

Note #1:
v2x is the default build type/platform, and PLAT input is not required in the
make commands.

Note #2:
export is the default destination/installation directory name. It can be changed
by using DESTDIR variable with Make compilation and installation command.

Installation involves copying of the compiled shared libraries, binaries, tests,
and other required files to an installation folder. The folder contains the items
which are needed to be exported/copied on the board.

Note #3:
Building library for i.MX8X platform require COMPATIBLE_MACHINE value.

Examples:
---------

-To compile libraries only

ele:

	make PLAT=ele clean; make clean;
	make PLAT=ele libs;

v2x:

	make PLAT=ele clean; make clean;
	make libs;

seco:

	make PLAT=seco COMPATIBLE_MACHINE=mx8dxl-nxp-bsp clean; make clean;
	make libs;

-To compile libraries and install

ele:

	make PLAT=ele clean; make clean;
	make PLAT=ele libs install;

v2x:

	make PLAT=ele clean; make clean;
	make libs install;

seco:

	make PLAT=seco COMPATIBLE_MACHINE=mx8dxl-nxp-bsp clean; make clean;
	make libs install;

-To get v2x and ele library artifacts in the installation folder (Two-Step process)

v2x + ele:

	rm -rf export;make PLAT=ele clean; make clean;
	make libs install;tree export;          // Compile and Install V2X artifacts
	make clean;                             // Clean V2X specific compiled object files and temp data
	make PLAT=ele libs install;tree export; // Compile and Install ELE artifacts


3. Installation Steps
=====================
Secure Enclave library Artifacts to be installed on the Board's rootfs as
follows:

Shared Library versioning
-------------------------
1.0 versioning represents that the library is targeted for ELE (ELE-HSM), or
while 0.1 represents that library is for SECO (SECO-HSM), V2X (V2X-SHE, V2X-HSM).


ELE-HSM: SECO-HSM: Library Artifacts
------------------------------------
/usr/lib/libele_hsm.so -> libele_hsm.so.1      (ELE-HSM Shared library)
/usr/lib/libele_hsm.so.1 -> libele_hsm.so.1.0  (ELE-HSM Shared library)
/usr/lib/libele_hsm.so.1.0                     (ELE-HSM Shared library)
/usr/lib/libele_nvm.so -> libele_nvm.so.1      (ELE-NVM Shared library)
/usr/lib/libele_nvm.so.1 -> libele_nvm.so.1.0  (ELE-NVM Shared library)
/usr/lib/libele_nvm.so.1.0                     (ELE-NVM Shared library)
/usr/lib/lib_hsm.so -> lib_hsm.so.0            (SECO-HSM Shared library)
/usr/lib/lib_hsm.so.0 -> lib_hsm.so.0.1        (SECO-HSM Shared library)
/usr/lib/lib_hsm.so.0.1                        (SECO-HSM Shared library)
/usr/lib/lib_nvm.so -> lib_nvm.so.0            (SECO-NVM Shared library)
/usr/lib/lib_nvm.so.0 -> lib_nvm.so.0.1        (SECO-NVM Shared library)
/usr/lib/lib_nvm.so.0.1                        (SECO-NVM Shared library)
/usr/bin/nvm_daemon                            (NVM Daemon)
/etc/nvmd.conf                                 (NVM-Daemon configuration file)
/etc/systemd/system/nvm_daemon.service         (NVM-Daemon service file)
/usr/bin/nvmd_conf_setup.sh                    (NVM-Daemon configuration helper script)

V2X: V2X-SHE + V2X-HSM: Library Artifacts
-----------------------------------------
/usr/lib/lib_she.so -> lib_she.so.0            (V2X-SHE Shared library)
/usr/lib/lib_she.so.0 -> lib_she.so.0.1        (V2X-SHE Shared library)
/usr/lib/lib_she.so.0.1                        (V2X-SHE Shared library)
/usr/lib/lib_nvm.so -> lib_nvm.so.0            (V2X-NVM Shared library)
/usr/lib/lib_nvm.so.0 -> lib_nvm.so.0.1        (V2X-NVM Shared library)
/usr/lib/lib_nvm.so.0.1                        (V2X-NVM Shared library)
/usr/lib/lib_hsm.so -> lib_hsm.so.0            (V2X-HSM Shared library)
/usr/lib/lib_hsm.so.0 -> lib_hsm.so.0.1        (V2X-HSM Shared library)
/usr/lib/lib_hsm.so.0.1                        (V2X-HSM Shared library)
/usr/bin/nvm_daemon_v2x                        (NVM Daemon V2X)
/etc/nvmd_v2x.conf                             (NVM-Daemon V2X configuration file)
/etc/systemd/system/nvm_daemon_v2x.service     (NVM-Daemon V2X service file)
/usr/bin/nvmd_conf_setup.sh                    (NVM-Daemon configuration helper script)


4. Testing Steps: Compilation, Installation & Execution
=======================================================

Table 3: Secure Enclave HSM Tests with their target Platform/IP
-----------------------------------------------------------

+--------+---------------------------------+-------------------+
|   IP   |              Platform           |     HSM Test      |
+========+=================================+===================+
|  ELE   |  i.MX8ULP/i.MX93/i.MX95/i.MX91  | ele_hsm_test      |
|        |                                 | ele_hsm_perf_test |
|--------+---------------------------------+-------------------+
|  V2X   |        i.MX95/i.MX8DXL          |   v2x_hsm_test    |
+--------+---------------------------------+-------------------+
|  SECO  |        i.MX8DXL/i.MX8QXP        |   seco_hsm_test   |
+--------+---------------------------------+-------------------+

Table 4: Secure Enclave SHE Tests with their target Platform/IP
-----------------------------------------------------------

+--------+---------------------------------+-----------------+
|   IP   |              Platform           |     SHE Test    |
+========+=================================+=================+
|  V2X   |        i.MX95/i.MX8DXL-DL3      |   v2x_she_test  |
+--------+---------------------------------+-----------------+
|  SECO  |        i.MX8QXP/i.MX8DXL-DL1    |   seco_she_test |
+--------+---------------------------------+-----------------+


Note #3:
- i.MX95 Platform is newly added. The FW and ROM APIs of ELE-HSM/V2X-SHE, are
  under testing using this library.
- V2X-HSM support has not been tested yet on i.MX95.
- i.MX8DXL-DL2 board dont support SHE

Pre-requisites for Secure Enclave Tests
---------------------------------------

OpenSSL
-------

For Library compilation only (without tests), there is no dependency on OpenSSL.
But with Secure Enclave (ele/ELE-HSM) tests compilation, OpenSSL configured and
compiled setup is required. By Default, the OpenSSL directory is expected at the
same directory level as of Secure Enclave directory.

- OpenSSL repo

	git clone https://github.com/openssl/openssl.git

	cd openssl/

	git checkout openssl-3.0

- OpenSSL Configure and Build Steps:

	export CROSS_COMPILE=$TOOLCHAIN_PATH;
	./Configure -I./include linux-aarch64 shared --prefix=/usr/local --openssldir=lib/ssl;
	make clean; make depend; make -j32;

	Example:
	--------
	export CROSS_COMPILE=/opt/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-;
	./Configure -I./include linux-aarch64 shared --prefix=/usr/local --openssldir=lib/ssl;
	make clean; make depend; make -j32;


Mbed-TLS
--------

For Library compilation only (without tests), there is no dependency on Mbed-TLS.
But with Secure Enclave tests compilation, Mbed-TLS configured and compiled setup
is required. By Default, the Mbed-TLS directory is expected at the same directory
level as of Secure Enclave directory.

- Mbed-TLS repo

	git clone https://github.com/Mbed-TLS/mbedtls.git

	cd mbedtls

	git checkout master

- Mbed-TLS Configure and Build Steps:

	// setup
	export CROSS_COMPILE=$TOOLCHAIN_PATH;
	export CC=${CROSS_COMPILE}gcc;

	git submodule update --init;

	// configure & build
	cmake -DUSE_SHARED_MBEDTLS_LIBRARY=ON -DUSE_STATIC_MBEDTLS_LIBRARY=OFF \
	-DENABLE_TESTING=OFF -DENABLE_PROGRAMS=OFF \
	-DCMAKE_C_COMPILER=${CROSS_COMPILE}gcc \
	-DMBEDTLS_CONFIG_FILE='./include/mbedtls/mbedtls_config.h' \
	-DCMAKE_C_FLAGS=' -mstrict-align' ;

	make;


Secure Enclave Tests Build Steps
--------------------------------

-To compile libraries, tests and install

	make PLAT=$PLAT COMPATIBLE_MACHINE=$MACHINE install_tests;

-To compile libraries, tests and install, with custom OpenSSL path

	make PLAT=$PLAT OPENSSL_PATH=$OPENSSL_DIR_PATH install_tests;

-To compile libraries, tests and install, with custom Mbed-TLS path

	make PLAT=$PLAT MBEDTLS_PATH=$MBEDTLS_DIR_PATH install_tests;

-To compile libraries, tests and install, with custom installation path

	make PLAT=$PLAT DESTDIR=$DESTDIR_PATH install_tests;

Note #4:
OPENSSL_PATH & MBEDTLS_PATH variables can be used with Make compilation command
to change the default OpenSSL or Mbed-TLS path.

Variable COMPATIBLE_MACHINE=$MACHINE to be added for building the library on i.MX8X.

Examples:
---------

-To compile libraries, tests and install:

ele:

	rm -rf export;make PLAT=ele clean; make clean;
	make PLAT=ele install_tests;tree export;

v2x:

	rm -rf export;make PLAT=ele clean; make clean;
	make install_tests;tree export;

seco:

	rm -rf export;make PLAT=seco COMPATIBLE_MACHINE=mx8dxl-nxp-bsp clean; make clean;
	make install_tests;tree export;


-To get v2x and ele artifacts (including tests) in the installation folder, (Two-step process)

v2x + ele:

	rm -rf export;make PLAT=ele clean; make clean;
	make install_tests;tree export;          // Compile and Install V2X artifacts
	make clean;                              // Clean V2X specific compiled object files and temp data
	make PLAT=ele install_tests;tree export; // Compile and Install ELE artifacts

Test Steps on the Boards
------------------------

ELE-HSM Tests:
--------------

	service nvm_daemon start;
	service nvm_daemon status;
	ele_hsm_test;
	ele_hsm_perf_test;
	service nvm_daemon stop;

V2X-SHE Test:
-------------

	# To start NVM on SHE MU (default configuration)
	nvmd_conf_setup.sh config_id=0xc8; or
	nvmd_conf_setup.sh config_id=v2x_she_nvm;

	# To start NVM on DEBUG MU (applicable for i.MX95 only)
	nvmd_conf_setup.sh config_id=0xe0; or
	nvmd_conf_setup.sh config_id=V2X_SHE_DEBUG_MU_NVM;

	service nvm_daemon_v2x start;
	service nvm_daemon_v2x status;
	v2x_she_test $1 $2 $3;
	v2x_she_test -a;                  //execute all test vectors
	v2x_she_test shx_file;            //execute test vectors available in given shx
	service nvm_daemon_v2x stop;

	Example for v2x_she_test args:
	------------------------------
	v2x_she_test 0 2 1
	v2x_she_test 0 4 2
	v2x_she_test 1 3 2
	# Refer v2x_she_test usage for more details

V2X-HSM Test:
-------------

	nvmd_conf_setup.sh config_id=0xd0; or
	nvmd_conf_setup.sh config_id=v2x_hsm_nvm;
	service nvm_daemon_v2x start;
	service nvm_daemon_v2x status;
	v2x_hsm_test;
	service nvm_daemon_v2x stop;

SECO-HSM Test:
-------------

	nvmd_conf_setup.sh config_id=0x80; or
	nvmd_conf_setup.sh config_id=hsm_nvm;
	service nvm_daemon start;
	service nvm_daemon status;
	seco_hsm_test;
	service nvm_daemon stop;

SECO-SHE Test:
-------------

	nvmd_conf_setup.sh config_id=0x88; or
	nvmd_conf_setup.sh config_id=she_nvm;
	service nvm_daemon start;
	service nvm_daemon status;
	seco_she_test;
	service nvm_daemon stop;

Note #5:
Before running the tests for the first time, it is required to perform the cleanup
of the Storage/NVM directory (before start of the NVM Daemon) for persistent data.
The NVM directory may contain the persistent data of some test applications,
other than the secure enclave tests. In case of conflicting NVM data with other
test applications or previous runs of itself, the secure enclave tests may fail.

Note #6:
nvmd_conf_setup.sh can help in setting up the configurations for NVM Daemon,
before starting it. For e.g., config_id 0xc8 represents configuration for V2X-SHE.
Refer the usage of "nvmd_conf_setup.sh" for more details.

Note #7:
seco_she_test/v2x_she_test will return failure if functional test/test vector try
to re-write the key with same value.

Ensure that following Secure Enclave Tests Artifacts are installed on the
Board's rootfs:

ELE: ELE-HSM: Tests Artifacts
-----------------------------
/usr/bin/ele_hsm_test                                               (ELE-HSM test app)
/usr/bin/ele_hsm_perf_test                                          (ELE-HSM Performance test app)
/usr/share/se/test_vectors/psa/el2go_aes_test.blob                  (ELE-HSM test blob file)
/usr/share/se/test_vectors/psa/test_vectors_set0_kgen_n.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set0_kgen_p.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set0_kgen_volatile_ap.tv   (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set0_kgen_persistent_ap.tv (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set0_kgen_permanent_ap.tv  (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set1_cipher_n.tv        (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set1_cipher_p.tv        (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set1_cipher_ap.tv       (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set2_mac_n.tv           (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set2_mac_p.tv           (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set2_mac_ap.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set3_sign_verify_n.tv   (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set3_sign_verify_p.tv   (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set3_sign_verify_ap.tv  (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set4_hash_n.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set4_hash_p.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set4_hash_ap.tv         (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set5_data_storage_p.tv  (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set5_data_storage_ap.tv (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set6_auth_enc_ap.tv     (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set7_rng_ap.tv          (ELE-HSM test vector)
/usr/share/se/test_vectors/psa/test_vectors_set8_gc_acrypto_ap.tv   (ELE-HSM test vector)

V2X: V2X-SHE + V2X-HSM: Tests Artifacts
---------------------------------------
/usr/bin/v2x_she_test                          (V2X-SHE test app)
/usr/bin/v2x_hsm_test                          (V2X-HSM test app)
/usr/share/se/she_test_vectors/*               (V2X-SHE test vectors)
/usr/share/se/test_vectors/non_psa/readme.tv   (V2X test vectors readme)

SECO: SECO-HSM + SECO-SHE: Tests Artifacts
---------------------------------------
/usr/bin/seco_she_test                          (SHE-HSM test app)
/usr/bin/seco_hsm_test                          (SECO-HSM test app)
/usr/share/se/she_test_vectors/*                (SHE test vectors)

5. Documentation
================

Secure Enclave (HSM/SHE) APIs Documents:
----------------------------------------

	https://github.com/nxp-imx/imx-secure-enclave/tree/lf-6.6.36_2.1.0/doc


6. Licenses
===========

Almost all sources are under the BSD 3-Clause License.
For more details, please refer SCR file.


7. Changelog
============

Known Limitations
-----------------

- ELE-HSM

  i.MX95:

  HMAC operations Not Supported
  Key Exchange API Not Supported
  Key Import API Not Supported

- V2X-SHE

  The total (shared + non-shared) number of key-store must be <=5.
  The processes will fail non-deterministically at any point, if number of
  key-store is greater than 5.

  If such a case arises, it is required to ensure NVM clean-up, followed by
  board restart.

- i.MX8DXL DL2/i.MX8QXP C0 FIPS
  Following operations are disabled on FIPS part
  - ECIES encryption/decryption.
  - Butterfly key expansion.
  - Public key reconstruction.
  - Public key decompression.
  - Key store open with SHE flag set.
  - All Generic crypto services.
  - All SM2/3/4 modes disabled.

lf-6.6.23_2.0.0 : Added Features
---------------------------------

- ELE-HSM

 Added New Algorithms (TLS 1.3, HKDF Extract, HKDF Expand) support for Key Exchange API
 Added Data Delete API support and Test
 Added NVM Chunk Delete API support
 Added Generic Crypto: Cipher API support and Test
 Added Generic Crypto: AEAD API support and Test
 Added SHA-3 algorithms support

- V2X-SHE

 Added Test Vectors support
 All SHE API(s) are supported on i.MX95.
 Refer to the SHE API document through Documentation section.

lf-6.6.36_2.1.0 : New Features
------------------------------

- ELE-HSM

 Added TLS 1.2 support and tests
 Added MD5 and SHA-1 functional tests
 Added HKDF functional tests
 Added Encrypted Data Storage test vectors
 Enhanced WRITE FUSE API to support dynamic word size

- V2X-SHE

 Increased Test Vectors

- SECO-HSM + SECO-SHE

 Added support for i.MX8DXL and i.MX8QXP Platform.