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    |
+----------+---------+-----------+-----------+------------+------------+
| i.MX943  |   YES   |    YES    |    YES    |     NA     |     NA     |
+----------+---------+-----------+-----------+------------+------------+


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

+--------+----------------------------------+-------------------+-----------------+
| H/W IP |               Platform           |        HSM        |       SHE       |
+========+==================================+===================+=================+
|  ELE   |     i.MX8ULP/i.MX93/i.MX95/      |    /etc/ele/      |     N/A         |
|        |         i.MX91/i.MX943           |                   |                 |
|--------+----------------------------------+-------------------+-----------------+
|  V2X   |     i.MX95/i.MX943/i.MX8DXL      |   /etc/v2x_hsm/   |  /etc/v2x_she/  |
+--------+----------------------------------+-------------------+-----------------+
|  SECO  |       i.MX8DXL/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_she.conf                         (NVM-Daemon V2X SHE configuration file)
/etc/systemd/system/nvm_daemon_v2x_she.service (NVM-Daemon V2X SHE service file)
/etc/nvmd_v2x_hsm.conf                         (NVM-Daemon V2X HSM configuration file)
/etc/systemd/system/nvm_daemon_v2x_hsm.service (NVM-Daemon V2X HSM 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/     | ele_hsm_test      |
|        |        i.MX91/i.MX943           | ele_hsm_perf_test |
|--------+---------------------------------+-------------------+
|  V2X   |     i.MX95/i.MX8DXL/i.MX943     |   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/i.MX943 |   v2x_she_test  |
+--------+---------------------------------+-----------------+
|  SECO  |        i.MX8QXP/i.MX8DXL-DL1    |   seco_she_test |
+--------+---------------------------------+-----------------+


Note #3:
- V2X-HSM test can not be supported on i.MX95 A0, as no support for SG MUs.
- V2X-HSM test is partially supported on i.MX8DXL-DL2 board.
- 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:
--------------

	/* If Test Environment running multiple test apps which use ELE HSM and same nvm_daemon,
	 * then first need to check the status of daemon and execute stop command
	 * if nvm_daemon is already running
	 */

	systemctl status nvm_daemon;
	systemctl stop nvm_daemon;

	rm -rf /etc/ele/*;           //delete Storage/NVM directory old data
	rm -rf /var/lib/se/*;        //delete ELE-HSM tests vectors old key database

	systemctl start nvm_daemon;
	systemctl status nvm_daemon;
	ele_hsm_test;
	ele_hsm_perf_test;
	systemctl stop nvm_daemon;

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 SHE1 MU
	nvmd_conf_setup.sh config_id=0xc9; or
	nvmd_conf_setup.sh config_id=v2x_she1_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;

	systemctl start nvm_daemon_v2x_she.service;
	systemctl status nvm_daemon_v2x_she.service;
	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
	systemctl stop nvm_daemon_v2x_she.service;

	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;
	systemctl start nvm_daemon_v2x_hsm.service;
	systemctl status nvm_daemon_v2x_hsm.service;
	v2x_hsm_test;
	v2x_hsm_test -a;                  //execute all test vectors, supported on i.MX943 currently
	v2x_hsm_test shx_file;            //execute test vectors available in given shx
	systemctl stop nvm_daemon_v2x_hsm.service;

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

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

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

	nvmd_conf_setup.sh config_id=0x88; or
	nvmd_conf_setup.sh config_id=she_nvm;
	systemctl start nvm_daemon;
	systemctl status nvm_daemon;
	seco_she_test;
	seco_she_test -a;	//execute all test vectors
	systemctl stop nvm_daemon;

Note #5:
Before following the test steps, it is required to perform the cleanup/deletion of all
the files/contents of the Storage/NVM directory (before start of the NVM daemon)
for persistent data. Please note that the cleanup to be performed only when NVM
is not running.

Make sure that start NVM daemon step is properly done, i.e. it must provide fresh
context with the targeted IP. If the same NVM daemon has been already started by
some other test app (e.g. SMW tests) and currently running with previous context,
then performing start NVM daemon again will have no effect, and it will still
maintain the previous test app's NVM context, which may impact/fail further tests.

Hence, If the testing involves multiple test apps (e.g. smw, itest, ele-hsm..) which
may have cross impact due to usage of same NVM daemon, then below additional
steps also needed before other mandatory test steps:
	systemctl status <NVM_DAEMON_NAME>
	systemctl stop <NVM_DAEMON_NAME>

Here, NVM_DAEMON_NAME represents the NVM binary from test steps under consideration,
and the corresponding Storage/NVM directory can be referred from Table 2.
For e.g.
If following ELE-HSM Test section steps, NVM_DAEMON_NAME is nvm_daemon and NVM
directory is /etc/ele/ (refer - Table 2).
If following V2X-SHE Test section steps, NVM_DAEMON_NAME is nvm_daemon_v2x and NVM
directory is /etc/v2x_she/  (refer - Table 2).

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.

Note #8:
On i.MX943 board, SHE0 MU is been used by FCE so functionality of SHE is supported on
SHE1 MU only from LF-Q2 2025.

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/*                                    (ELE-HSM test vectors)

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/v2x_hsm_test_vectors/*           (V2X-HSM test vectors)
/usr/share/se/she_test_vectors/                (Path for V2X-SHE 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.