How nxp/plug-and-trust works
1. What this repo is
- This is NXP’s Plug & Trust Middleware Mini Package for talking to SE05x/SE051/SE052 secure elements from a host, specifically the minimal Linux/Raspberry Pi setup tested with T=1 over I2C.
2. Top-level architecture
- The repo is split into three main host-side layers:
- ecc_example/: a small application demonstrating ECC sign/verify.
- sss/: the Secure Subsystem Services (SSS) API layer used by applications.
- hostlib/hostLib/: the lower-level host library that implements communication, APDU framing, secure channel support, and SE05x-specific protocol handling.
3. Primary data flow
- Application code in ecc_example calls SSS APIs.
- SSS translates those requests into SE05x operations and keystore/object actions.
- hostlib converts them into APDUs and transport messages.
- The transport layer sends them over I2C to the secure element.
- Responses travel back through the same stack to the application.
4. Application boundary
- ecc_example/ecc_example is not a full framework; it is an integration sample showing how an app:
- opens a session,
- initializes a key store / object context,
- performs crypto operations against the secure element.
- The README points to sss/ex/ecc/ex_sss_ecc.c as the canonical example entry point.
5. SSS layer responsibilities
- sss/inc/ and sss/src/ define the application-facing abstraction:
- common SSS APIs,
- key store helpers,
- policy handling,
- backend-specific bindings.
- The sss/src/se05x/ subtree is the secure-element backend.
- sss/src/openssl/ and sss/src/mbedtls/ exist as host crypto adapters, but the mini package is primarily described with OpenSSL as the host crypto option.
6. SE05x-specific logic
- The SE05x backend contains the important device-facing logic:
- fsl_sss_se05x_apis.c
- fsl_sss_se05x_mw.c
- fsl_sss_se05x_scp03.c
- fsl_sss_se05x_policy.c
- fsl_sss_se05x_eckey.c
- This is where key objects, policies, secure channel setup, and ECC-specific behavior are mapped to the secure element model.
7. Host library responsibilities
- hostlib/hostLib/ is the transport/protocol layer beneath SSS.
- Major subareas:
- libCommon/smCom/: communication stack and T=1 over I2C support.
- se05x_03_xx_xx/ and se05x/src/: SE05x APDU definitions, TLV helpers, ECC curve data, middleware helpers.
- libCommon/nxScp/: SCP03 secure channel communication.
- libCommon/infra/: shared utility code, error handling, APDU helpers, platform abstractions.
8. Transport and platform boundary
- The repo is designed to be portable, but the mini package includes only the platform pieces needed for Raspberry Pi/Linux:
- hostlib/hostLib/platform/linux/i2c_a7.c for the I2C hardware access path.
- hostlib/hostLib/platform/generic/sm_timer.c for timing support.
- The README explicitly notes that porting to another platform mainly means replacing the I2C layer and possibly the timer layer.
9. Secure channel and authentication
- Session setup is not just “connect to device”; it can include different authentication modes and secure channels.
- The example bootstrap APIs in sss/ex/src/ex_sss_boot.c abstract:
- port selection,
- session opening,
- authentication setup,
- keystore/object initialization.
- SCP03 support is a notable architectural boundary: it sits between the host and the secure element to protect the session.
10. Configuration model
- Build-time behavior is controlled by CMake options such as:
- applet type (SE05X_A, SE05X_B, SE05X_C, SE051_H, AUTH, SE050_E)
- applet version (03_XX vs 07_02)
- host crypto (OPENSSL or none)
- authentication mode (None, UserID, PlatfSCP03, AESKey, ECKey, and combined variants)
- These options materially affect which code paths and protocol capabilities are compiled in.
11. Important conceptual boundary
- The secure element is treated as an external cryptographic boundary: keys, policies, and many operations live inside the device, while the host mostly orchestrates sessions, transports commands, and manages object references.
- This is the key architecture idea for diagramming the repo: application → SSS abstraction → hostlib/protocol → I2C transport → SE05x secure element.
12. What to draw in an architecture diagram
- Show at minimum:
- the example app at the top,
- the SSS API layer beneath it,
- the hostlib communication/protocol layer beneath that,
- the Linux I2C platform adapter at the bottom on the host side,
- and the SE05x device as the external target.
- Optionally annotate the side paths for OpenSSL host crypto, SCP03 authentication, and CMake-selected applet/version variants.
Main entry points: fsl_sss_se05x_apis.c SE05x backend · fsl_sss_api.h SSS API · smComT1oI2C.c smCom · ex_sss_boot.c Bootstrap
Components 20
Example app
ECC integration sample and bootstrap code.
- ECC sample · Minimal ECC sign/verify example that drives the stack.
ecc_example - ECC entry · Canonical ECC example entry point referenced by the README.
sss/ex/ecc/ex_sss_ecc.c - Bootstrap · Opens sessions, selects ports, and initializes auth and object context.
sss/ex/src/ex_sss_boot.c - Auth setup · Example-side secure channel and authentication wiring.
sss/ex/src/ex_sss_scp03_auth.c
SSS layer
Application-facing secure subsystem services and backend bindings.
- SSS API · Application-facing SSS entry points and shared orchestration.
sss/inc/fsl_sss_api.h - SE05x API · SSS bindings for secure-element operations.
sss/inc/fsl_sss_se05x_apis.h - Policies · Common and SE05x-specific policy definitions.
sss/inc/fsl_sss_policy.h - OpenSSL · Host-side crypto adapter used when OpenSSL is enabled.
sss/src/openssl/fsl_sss_openssl_apis.c - SE05x backend · Core SE05x backend logic for objects, policies, and secure-channel-aware operations.
sss/src/se05x/fsl_sss_se05x_apis.c - MW bridge · Maps SSS calls into SE05x middleware behavior and object handling.
sss/src/se05x/fsl_sss_se05x_mw.c - SCP03 · SSS-side SCP03 support for authenticated sessions.
sss/src/se05x/fsl_sss_se05x_scp03.c
Host library
Protocol, APDU, secure channel, and SE05x middleware.
- smCom · Communication stack including T=1 over I2C.
hostlib/hostLib/libCommon/smCom/smComT1oI2C.c - APDU core · Shared APDU framing and command/response handling.
hostlib/hostLib/libCommon/infra/sm_apdu.c - SCP03 comms · Low-level SCP03 communication helpers beneath SSS.
hostlib/hostLib/libCommon/nxScp/nxScp03_Com.c - SE05x mw · SE05x middleware helpers and TLV/curve support.
hostlib/hostLib/se05x/src/se05x_mw.c - SE05x APDUs · SE05x APDU definitions and implementations for device commands.
hostlib/hostLib/se05x_03_xx_xx/se05x_APDU.c - TLV · SE05x TLV helpers used by the protocol layer.
hostlib/hostLib/se05x/src/se05x_tlv.c
Platform
Linux and generic platform adapters for transport and timing.
Secure element
External SE05x device boundary.
- SE05x · External SE05x/SE051/SE052 boundary that stores keys and executes protected operations.
Connections 22
- ECC sample → ECC entry: uses · The sample app is backed by the canonical ECC example entry.
- ECC entry → Bootstrap: boots · Example code enters through shared bootstrap helpers.
- Bootstrap → SSS API: opens session · Bootstrap initializes the SSS session and object context.
- Bootstrap → Auth setup: configures auth · Bootstrap wires authentication mode and secure channel options.
- SSS API → SE05x API: backend · SSS exposes backend-specific secure-element APIs.
- SSS API → Policies: uses · Application-facing APIs apply policies and key constraints.
- SSS API → OpenSSL: host crypto · Optional host-side crypto adapter path.
- SE05x API → SE05x backend: implemented by · SE05x API calls are realized by the SE05x backend.
- SE05x backend → MW bridge: maps to mw · Backend logic translates into middleware-oriented operations.
- SE05x backend → SCP03: secure channel · Backend can negotiate and use SCP03 protected sessions.
- SE05x backend → SE05x mw: delegates · Device-facing work flows into hostlib middleware.
- MW bridge → APDU core: encodes · Middleware requests become APDU commands.
- SE05x mw → SE05x APDUs: uses · SE05x device commands are defined at the APDU layer.
- SE05x mw → TLV: formats · TLV helpers structure SE05x payloads.
- APDU core → smCom: sends via · APDUs are transported by the communication stack.
- SCP03 comms → smCom: protects · SCP03 wraps the transport path when authenticated.
- smCom → Linux I2C: i2c backend · T=1 over I2C uses the Linux hardware access layer.
- Linux I2C → SE05x: i2c · Linux host communicates with the secure element over I2C.
- Timer → smCom: timing · Timer support underpins transport retries and waits.
- SCP03 → SCP03 comms: relies on · SSS secure-channel setup depends on low-level SCP03 comms.
- Auth setup → SCP03: selects · Example auth configuration reaches SE05x SCP03 setup.
- SE05x → SE05x backend: responses · Device results flow back up through the backend stack.