Changes between Initial Version and Version 1 of venice/edgelock

Timestamp:

08/11/2025 10:52:14 PM (5 hours ago)

Author:

Tim Harvey

Comment:

initial page

venice/edgelock

@@ +1 @@
+[[PageOutline]]
+
+= NXP !EdgeLock Secure Enclave
+While the i.MX8M does have its own internal !EdgeLock Secure Enclave it only allows up to FIPS level 2 and in some cases level 3 is required (which requires the keys are stored in a different IC).
+
+The SE05x speaks SCP03 on top of I2C and can co-exist with other I2C devices. It is often used within OPTEE with a trampoline driver that hooks into Linux with an SMC call to allow Linux owning the I2C bus but OPTEE still allowed controlled access
+
+The NXP !EdgeLock SE05x Plug & Trust middleware package is a software stack provided by NXP for integrating the SE050 with Linux systems.
+ - Supports cryptographic operations like ECC, RSA, AES, and more, leveraging the SE050’s hardware security.
+ - Provides APIs for session management, key storage, and cryptographic functions.
+ - Includes support for secure communication protocols like !GlobalPlatform Secure Channel Protocol 03 (SCP03) over an I²C interface.
+ - Offers pre-integrated libraries for Linux, simplifying integration with host systems.
+
+The package can be downloaded from NXP's website while derivatives for specific use cases are available github NXP plug-and-trust repository:
+ * https://github.com/NXP/plug-and-trust - middleware mini package with minimum files requires to connect to SE05x using t1oi2c protocol
+
+References:
+ * [https://www.nxp.com/products/SE052F SE052F Product Page]
+ * [https://www.nxp.com/docs/en/application-note/AN14277.pdf AN14277 SE052 Configuration Details]
+ * [https://www.nxp.com/docs/en/application-note/AN13013.pdf AN13013 Get started with EdgeLock SE05x support package]
+
+
+== Hardware
+The following Gateworks boards have a SE05x chip on-board:
+||= Family =||= Board =||= Chip =||= bus/address =||= reset =||
+|| Venice   || GW8201-C+ || SE052F || I2C2@0x48 || N/A ||
+
+
+== Software
+The SE05x family uses a T=1 over I2C (T1oI2C) protocol, not standard I2C register based communication. It encapsulates its communication in a higher-level protocol (ISO/IEC 7816-4 APDUs over I2C). For this reason Linux and U-Boot can detect the device as long as the I2C frame addressed to the device contains at least one byte of data but can not access registers over I2C:
+ * U-Boot device detection: 
+{{{#!bash
+u-boot=> i2c dev 1 && i2c probe 0x48
+Setting bus to 1
+Valid chip addresses: 48
+}}}
+  - the valid chip address above confirms SCL/SDA/VDD_3V3/GND are wired correctly and powered
+
+Because there is no U-Boot or Linux kernel driver there does not need to be any device-tree node for the device.
+
+Note the SE052F errata sheet notes a potential problem where an acknowledged I2C frame addressed to the device must contain at least one byte of data. If not the SE052F may enter an unresponsive state requiring a power cycle. In a shared bus scenario if other devices send incomplete or malformed frames they could trigger this.
+
+=== NXP Plug & Trust Middleware
+The NXP Plug & Trust middleware communicates with the SE05x directly in userspace via the I2C device file (e.g., /dev/i2c-1). It uses the Linux I2C userspace interface (ioctl calls) to send T1oI2C APDUs, bypassing the need for a dedicated kernel driver. The middleware handles all protocol details, including authentication (e.g., SCP03) and command formatting. Because this is in userspace there is no dt entry needed as long as the I2C bus is enabled.
+
+There are multiple flavors of the NXP Plug & Trust Middleware below are very minimal examples of getting it up and running by building software on the target board itself.
+
+==== Full package (zip downloaded from NXP)
+You can download the full package middleware by going to https://www.nxp.com/products/SE052F selecting 'Design Resources' then 'Software' then download '!EdgeLock SE05x Plug & Trust Middleware. (NXP account required).
+
+Notes:
+ - example apps take a 'port' argument identifying the bus and address via <busdev>:<slaveaddr> (ie '/dev/i2c-1:0x48' for GW8201). Note that while the busdev is a Linux path that exists the ':0x48' will not exist in a device path)
+ - the ssscli ssscli tool isnt' a standalone binary; its a python based CLI installed via setup.py after building the middleware libraries.
+ - there are fairly detailed HTML docs within the docs directory 
+
+Building:
+{{{#!bash
+# install pre-requisites
+apt update && apt install -y build-essential git cmake python3 python3-pip python3-setuptools python3-wheel libssl-dev libusb-1.0-0-dev pkg-config unzip wget
+
+# unzip release package
+unzip SE-PLUG-TRUST-MW_04.07.01.zip
+cd simw-top
+
+# script uses hostname to determine system its running on, needs to be imx8 if building on imx8m target
+hostname imx8 
+# create various cmake projects in ~/simw-top_build
+python3 ./scripts/create_cmake_projects.py
+# list example projects
+ls ~/simw-top_build
+# build imx_native_se050_t1oi2c
+cd ~/simw-top_build/imx_native_se050_t1oi2c
+# configure it (see ~/simw-top/doc/scripts/cmake_options.html)
+cmake . \
+-DPTMW_Applet=SE05X_C \
+-DPTMW_SE05X_Ver=07_02 \
+-DPTMW_HostCrypto=OPENSSL \
+-DPTMW_Host=iMXLinux \
+-DPTMW_HostOS=Linux \
+
+# build it
+cmake --build . -j$(nproc)
+# install it
+make install
+# update library cache
+ldconfig /usr/local/lib/
+# install ssscli python tool
+cd ~/simw-top/pycli/src/
+python3 setup.py develop
+}}}
+
+The ssscli tool is a Python based tool to manipulate the SE050 Secure Element. See ~/simw-top/doc/cli-tool.html for details. It can be used to:
+ - Insert Keys, Certficates
+ - Generate Keys
+ - Attach policies to objects
+ - Control Cloud for CLI (To Be Done)
+
+Running some examples:
+ * ssscli:
+{{{#!bash
+# ssscli --version
+ssscli, version v04.07.01
+}}}
+ * se05x_GetInfo (show device configuration)
+{{{#!bash
+# se05x_GetInfo 
+App   :INFO :Running se05x_GetInfo /dev/i2c-1:0x48
+App   :INFO :If you want to over-ride the selection, use ENV=EX_SSS_BOOT_SSS_PORT or pass in command line arguments.
+App   :INFO :PlugAndTrust_v04.07.01_20250519
+sss   :INFO :atr (Len=35)
+      01 A0 00 00    03 96 04 03    E8 00 FE 02    0B 03 E8 00 
+      01 00 00 00    00 64 13 88    0A 00 65 53    45 30 35 31 
+      00 00 00 
+App   :WARN :#####################################################
+App   :INFO :uid (Len=18)
+      04 00 50 01    A4 D8 98 71    0E EC 5D 04    57 48 BA 98 
+      1E 90 
+App   :INFO :Running se05x_GetInfo
+App   :INFO :If you want to over-ride the selection, use ENV=EX_SSS_BOOT_SSS_PORT or pass in command line arguments.
+sss   :INFO :atr (Len=35)
+      01 A0 00 00    03 96 04 03    E8 00 FE 02    0B 03 E8 00 
+      01 00 00 00    00 64 13 88    0A 00 65 53    45 30 35 31 
+      00 00 00 
+sss   :INFO :Newer version of Applet Found
+sss   :INFO :Compiled for 0x70200. Got newer 0x70216
+sss   :WARN :Communication channel is Plain.
+sss   :WARN :!!!Not recommended for production use.!!!
+App   :WARN :#####################################################
+App   :INFO :Applet Major = 7
+App   :INFO :Applet Minor = 2
+App   :INFO :Applet patch = 22
+App   :INFO :AppletConfig = 26F2
+App   :INFO :With    ECDSA_ECDH_ECDHE
+App   :INFO :WithOut EDDSA
+App   :INFO :WithOut DH_MONT
+App   :INFO :With    HMAC
+App   :INFO :With    RSA_PLAIN
+App   :INFO :With    RSA_CRT
+App   :INFO :With    AES
+App   :INFO :WithOut DES
+App   :INFO :With    PBKDF
+App   :INFO :With    TLS
+App   :INFO :WithOut MIFARE
+App   :INFO :With    I2CM
+App   :INFO :Internal = FFFF
+App   :WARN :#####################################################
+App   :INFO :Tag value - proprietary data 0xFE = 0xFE
+App   :INFO :Length of following data 0x45 = 0x4F
+App   :INFO :Tag card identification data (Len=2)
+      DF 28 
+App   :INFO :Length of card identification data = 0x4C
+App   :INFO :Tag configuration ID (Must be 0x01) = 0x01
+App   :INFO :Configuration ID (Len=12)
+      00 05 B5 01    1B 7D B8 1B    89 99 D0 5D 
+App   :INFO :OEF ID (Len=2)
+      B5 01 
+App   :INFO :Tag patch ID (Must be 0x02) = 0x02
+App   :INFO :Patch ID (Len=8)
+      00 00 00 00    00 00 00 00 
+App   :INFO :Tag platform build ID1 (Must be 0x03) = 0x03
+App   :INFO :Platform build ID (Len=24)
+      4A 33 52 36    30 30 30 33    37 33 31 38    31 32 30 30 
+      6D 20 B6 19    7D 63 5E 7C 
+App   :INFO :JCOP Platform ID = J3R6000373181200
+App   :INFO :Tag FIPS mode (Must be 0x05) = 0x05
+App   :INFO :FIPS mode var = 0x01
+App   :INFO :Tag pre-perso state (Must be 0x07) = 0x07
+App   :INFO :Bit mask of pre-perso state var = 0x00
+App   :INFO :Tag ROM ID (Must be 0x08) = 0x08
+App   :INFO :ROM ID (Len=8)
+      B3 37 5F E9    B5 50 8B C4 
+App   :INFO :Tag JCOP OS Core ID (Must be 0x0A) = 0x0A
+App   :INFO :JCOP OS Core (Len=8)
+      55 60 6F D4    BE EC F3 CD 
+App   :INFO :Status Word (SW) (Len=2)
+      90 00 
+App   :INFO :se05x_GetInfoPlainApplet Example Success !!!...
+App   :WARN :#####################################################
+App   :INFO :cplc_data.IC_fabricator (Len=2)
+      47 90 
+App   :INFO :cplc_data.IC_type1 (Len=2)
+      D6 00 
+App   :INFO :cplc_data.Operating_system_identifier (Len=2)
+      47 00 
+App   :INFO :cplc_data.Operating_system_release_date (Len=2)
+      00 00 
+App   :INFO :cplc_data.Operating_system_release_level (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_fabrication_date (Len=2)
+      42 44 
+App   :INFO :cplc_data.IC_Serial_number (Len=4)
+      36 90 47 21 
+App   :INFO :cplc_data.IC_Batch_identifier (Len=2)
+      11 91 
+App   :INFO :cplc_data.IC_module_fabricator (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_module_packaging_date (Len=2)
+      00 00 
+App   :INFO :cplc_data.ICC_manufacturer (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_embedding_date (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_OS_initializer (Len=2)
+      17 57 
+App   :INFO :cplc_data.IC_OS_initialization_date (Len=2)
+      48 36 
+App   :INFO :cplc_data.IC_OS_initialization_equipment (Len=4)
+      39 30 34 37 
+App   :INFO :cplc_data.IC_personalizer (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_personalization_date (Len=2)
+      00 00 
+App   :INFO :cplc_data.IC_personalization_equipment_ID (Len=4)
+      00 00 00 00 
+App   :INFO :cplc_data.SW (Len=2)
+      90 00 
+App   :INFO :ex_sss Finished
+}}}
+ - The 'Newer version of Applet Found' 'Compiled for 0x70200. Got newer 0x70216' simply means that the middleware was built for an earlier version of the chip which is ok as the middleware is backward compatible. At the time of this writing the middleware does not have an option for PTMW_Applet=SE052F 
+ - The 'Communication channel is Plain' and '!!!Not recommended for production use.!!!' means that we are not using SCP03 which you should use for production use and must be enabled by building with '-DPTMW_SE05X_Auth=PlatfSCP03 -DPTMW_SCP=SCP03_SSS' and providing keys with  -DPTMW_SCP03KeyFile or EX_SSS_BOOT_SCP03_PATH env var)
+
+
+==== Plug and Trust middleware mini package (github)
+NXP provides derivatives of the full Plug & Trust middleware package for specific use cases via github. For development purposes still look at the full package as well as it contains large amounts of examples, tools and additional documentation.
+
+Example:
+{{{#!bash
+# install pre-requisites
+apt update && apt install -y build-essential git cmake python3 python3-pip python3-setuptools python3-wheel libssl-dev libusb-1.0-0-dev pkg-config unzip wget
+
+# fetch code
+git clone https://github.com/NXP/plug-and-trust
+cd plug-and-trust
+
+# configure
+cd ecc_example
+mkdir build
+cd build
+cmake ..
+
+# build
+cmake --build .
+
+# execute
+./ex_ecc /dev/i2c-1:0x48
+}}}
+
+Notes:
+ * see https://github.com/NXP/plug-and-trust/blob/master/simwlib_cmake_options.cmake for cmake options
+ * A reset GPIO is configured and toggled to reset the device which may be invalid for your hardware. See (hostlib/hostLib/platform/rsp/se05x_reset.c for reset configuration
+ * The port/address 
+
+=== Plug and Trust middleware nano package (github)
+The Plug and Trust middleware nano package  is a minimalistic version of the Plug & Trust middleware optimized for constrained devices. It also provides an integration with Zephyr OS and an example of Qi 1.3 authentication
+
+Example:
+ * build
+{{{#!bash
+# install pre-requisites
+apt update && apt install -y build-essential git cmake python3 python3-pip python3-setuptools python3-wheel libssl-dev libusb-1.0-0-dev pkg-config unzip wget
+
+# fetch code
+git clone https://github.com/NXPPlugNTrust/nano-package
+cd nano-package
+
+# configure
+cd examples/se05x_GetInfo/linux
+mkdir build
+cd build
+cmake ../
+
+# build
+make
+}}}
+ * execute
+{{{#!bash
+# ./ex_se05x_GetInfo 
+Se05x Getinfo Example !
+Plug and Trust nano package - version: 1.5.4 
+I2C driver supports plain i2c-level commands.
+##################################################### 
+Close i2c device 3.
+Plug and Trust nano package - version: 1.5.4 
+I2C driver supports plain i2c-level commands.
+##################################################### 
+Applet Major = 7 
+Applet Minor = 2 
+Applet patch = 22 
+AppletConfig = 26F2 
+With    ECDSA_ECDH_ECDHE 
+WithOut EDDSA 
+WithOut DH_MONT 
+With    HMAC 
+With    RSA_PLAIN 
+With    RSA_CRT 
+With    AES 
+WithOut DES 
+With    PBKDF 
+With    TLS 
+WithOut MIFARE 
+With    I2CM 
+##################################################### 
+Tag value - proprietary data 0xFE = 0xFE
+Length of following data 0x45 = 0x4F
+Length of card identification data = 0x4C
+Tag configuration ID (Must be 0x01) = 0x01
+OEF ID = 0xB5 0x01
+Tag patch ID (Must be 0x02) = 0x02
+Tag platform build ID1 (Must be 0x03) = 0x03
+JCOP Platform ID = J3R6000373181200 
+Tag FIPS mode (Must be 0x05) = 0x05 
+FIPS mode var = 0x01 
+Tag pre-perso state (Must be 0x07) = 0x07 
+Bit mask of pre-perso state var = 0x00 
+Tag ROM ID (Must be 0x08) = 0x08 
+se05x_GetInfoPlainApplet Example Success !!!... 
+##################################################### 
+Close i2c device 3.
+SE05x Getinfo Example Success ! 
+}}}
+
+Notes
+ - the bus path and address are hard coded in  lib/platform/linux/sm_i2c.c: SE05X_I2C_DEV_NAME, SE05X_I2C_DEV_ADDR
+