# nxp/plug-and-trust architecture

> Architecture diagram of the GitHub repository nxp/plug-and-trust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nxp/plug-and-trust
- Repository: https://github.com/nxp/plug-and-trust

## Overview

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: [`sss/src/se05x/fsl_sss_se05x_apis.c`](https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_apis.c) (SE05x backend), [`sss/inc/fsl_sss_api.h`](https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_api.h) (SSS API), [`hostlib/hostLib/libCommon/smCom/smComT1oI2C.c`](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/smCom/smComT1oI2C.c) (smCom), [`sss/ex/src/ex_sss_boot.c`](https://github.com/nxp/plug-and-trust/blob/master/sss/ex/src/ex_sss_boot.c) (Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_example["Example app"]
  node_node_ecc_example["ECC sample"]
  node_node_ex_sss_ecc["ECC entry<br/>example<br/>[ex_sss_ecc.c]"]
  node_node_ex_boot["Bootstrap<br/>[ex_sss_boot.c]"]
  node_node_ex_auth["Auth setup<br/>session auth"]
end

subgraph group_group_sss["SSS layer"]
  node_node_sss_api["SSS API<br/>abstraction<br/>[fsl_sss_api.h]"]
  node_node_sss_se05x_api["SE05x API<br/>backend API"]
  node_node_sss_policy["Policies<br/>policy model<br/>[fsl_sss_policy.h]"]
  node_node_sss_openssl["OpenSSL<br/>host crypto"]
  node_node_sss_se05x_impl["SE05x backend<br/>device binding"]
  node_node_sss_se05x_mw["MW bridge<br/>middleware<br/>[fsl_sss_se05x_mw.c]"]
  node_node_sss_se05x_scp03["SCP03<br/>secure channel"]
end

subgraph group_group_hostlib["Host library"]
  node_node_host_smcom["smCom<br/>transport stack<br/>[smComT1oI2C.c]"]
  node_node_host_apdu["APDU core<br/>protocol<br/>[sm_apdu.c]"]
  node_node_host_scp03["SCP03 comms<br/>secure channel<br/>[nxScp03_Com.c]"]
  node_node_host_se05x_mw["SE05x mw<br/>device middleware<br/>[se05x_mw.c]"]
  node_node_host_se05x_apdu["SE05x APDUs<br/>apdu defs<br/>[se05x_APDU.c]"]
  node_node_host_tlv["TLV<br/>encoding<br/>[se05x_tlv.c]"]
end

subgraph group_group_platform["Platform"]
  node_node_platform_linux["Linux I2C<br/>platform adapter<br/>[i2c_a7.c]"]
  node_node_platform_timer["Timer<br/>platform adapter<br/>[sm_timer.c]"]
end

subgraph group_group_device["Secure element"]
  node_node_se05x_device{{"SE05x<br/>secure element"}}
end

node_node_ecc_example -->|"uses"| node_node_ex_sss_ecc
node_node_ex_sss_ecc -->|"boots"| node_node_ex_boot
node_node_ex_boot -->|"opens session"| node_node_sss_api
node_node_ex_boot -->|"configures auth"| node_node_ex_auth
node_node_sss_api -->|"backend"| node_node_sss_se05x_api
node_node_sss_api -->|"uses"| node_node_sss_policy
node_node_sss_api -.->|"host crypto"| node_node_sss_openssl
node_node_sss_se05x_api -->|"implemented by"| node_node_sss_se05x_impl
node_node_sss_se05x_impl -->|"maps to mw"| node_node_sss_se05x_mw
node_node_sss_se05x_impl -->|"secure channel"| node_node_sss_se05x_scp03
node_node_sss_se05x_impl -->|"delegates"| node_node_host_se05x_mw
node_node_sss_se05x_mw -->|"encodes"| node_node_host_apdu
node_node_host_se05x_mw -->|"uses"| node_node_host_se05x_apdu
node_node_host_se05x_mw -->|"formats"| node_node_host_tlv
node_node_host_apdu -->|"sends via"| node_node_host_smcom
node_node_host_scp03 -->|"protects"| node_node_host_smcom
node_node_host_smcom -->|"i2c backend"| node_node_platform_linux
node_node_platform_linux -->|"i2c"| node_node_se05x_device
node_node_platform_timer -->|"timing"| node_node_host_smcom
node_node_sss_se05x_scp03 -->|"relies on"| node_node_host_scp03
node_node_ex_auth -->|"selects"| node_node_sss_se05x_scp03
node_node_se05x_device -.->|"responses"| node_node_sss_se05x_impl

click node_node_ecc_example "https://github.com/nxp/plug-and-trust/tree/master/ecc_example"
click node_node_ex_sss_ecc "https://github.com/nxp/plug-and-trust/blob/master/sss/ex/ecc/ex_sss_ecc.c"
click node_node_ex_boot "https://github.com/nxp/plug-and-trust/blob/master/sss/ex/src/ex_sss_boot.c"
click node_node_ex_auth "https://github.com/nxp/plug-and-trust/blob/master/sss/ex/src/ex_sss_scp03_auth.c"
click node_node_sss_api "https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_api.h"
click node_node_sss_se05x_api "https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_se05x_apis.h"
click node_node_sss_policy "https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_policy.h"
click node_node_sss_openssl "https://github.com/nxp/plug-and-trust/blob/master/sss/src/openssl/fsl_sss_openssl_apis.c"
click node_node_sss_se05x_impl "https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_apis.c"
click node_node_sss_se05x_mw "https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_mw.c"
click node_node_sss_se05x_scp03 "https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_scp03.c"
click node_node_host_smcom "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/smCom/smComT1oI2C.c"
click node_node_host_apdu "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/infra/sm_apdu.c"
click node_node_host_scp03 "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/nxScp/nxScp03_Com.c"
click node_node_host_se05x_mw "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x/src/se05x_mw.c"
click node_node_host_se05x_apdu "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x_03_xx_xx/se05x_APDU.c"
click node_node_host_tlv "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x/src/se05x_tlv.c"
click node_node_platform_linux "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/platform/linux/i2c_a7.c"
click node_node_platform_timer "https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/platform/generic/sm_timer.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_ecc_example,node_node_ex_sss_ecc,node_node_ex_boot,node_node_ex_auth toneBlue
class node_node_sss_api,node_node_sss_se05x_api,node_node_sss_policy,node_node_sss_openssl,node_node_sss_se05x_impl,node_node_sss_se05x_mw,node_node_sss_se05x_scp03 toneAmber
class node_node_host_smcom,node_node_host_apdu,node_node_host_scp03,node_node_host_se05x_mw,node_node_host_se05x_apdu,node_node_host_tlv toneMint
class node_node_platform_linux,node_node_platform_timer toneRose
class node_node_se05x_device toneIndigo
```

## Components

### Example app

ECC integration sample and bootstrap code.

- [ECC sample](https://github.com/nxp/plug-and-trust/tree/master/ecc_example): app · Minimal ECC sign/verify example that drives the stack. · `ecc_example`
- [ECC entry](https://github.com/nxp/plug-and-trust/blob/master/sss/ex/ecc/ex_sss_ecc.c): example · Canonical ECC example entry point referenced by the README. · `sss/ex/ecc/ex_sss_ecc.c`
- [Bootstrap](https://github.com/nxp/plug-and-trust/blob/master/sss/ex/src/ex_sss_boot.c): session bootstrap · Opens sessions, selects ports, and initializes auth and object context. · `sss/ex/src/ex_sss_boot.c`
- [Auth setup](https://github.com/nxp/plug-and-trust/blob/master/sss/ex/src/ex_sss_scp03_auth.c): session auth · 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](https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_api.h): abstraction · Application-facing SSS entry points and shared orchestration. · `sss/inc/fsl_sss_api.h`
- [SE05x API](https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_se05x_apis.h): backend API · SSS bindings for secure-element operations. · `sss/inc/fsl_sss_se05x_apis.h`
- [Policies](https://github.com/nxp/plug-and-trust/blob/master/sss/inc/fsl_sss_policy.h): policy model · Common and SE05x-specific policy definitions. · `sss/inc/fsl_sss_policy.h`
- [OpenSSL](https://github.com/nxp/plug-and-trust/blob/master/sss/src/openssl/fsl_sss_openssl_apis.c): host crypto · Host-side crypto adapter used when OpenSSL is enabled. · `sss/src/openssl/fsl_sss_openssl_apis.c`
- [SE05x backend](https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_apis.c): device binding · Core SE05x backend logic for objects, policies, and secure-channel-aware operations. · `sss/src/se05x/fsl_sss_se05x_apis.c`
- [MW bridge](https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_mw.c): middleware · Maps SSS calls into SE05x middleware behavior and object handling. · `sss/src/se05x/fsl_sss_se05x_mw.c`
- [SCP03](https://github.com/nxp/plug-and-trust/blob/master/sss/src/se05x/fsl_sss_se05x_scp03.c): secure channel · 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](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/smCom/smComT1oI2C.c): transport stack · Communication stack including T=1 over I2C. · `hostlib/hostLib/libCommon/smCom/smComT1oI2C.c`
- [APDU core](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/infra/sm_apdu.c): protocol · Shared APDU framing and command/response handling. · `hostlib/hostLib/libCommon/infra/sm_apdu.c`
- [SCP03 comms](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/libCommon/nxScp/nxScp03_Com.c): secure channel · Low-level SCP03 communication helpers beneath SSS. · `hostlib/hostLib/libCommon/nxScp/nxScp03_Com.c`
- [SE05x mw](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x/src/se05x_mw.c): device middleware · SE05x middleware helpers and TLV/curve support. · `hostlib/hostLib/se05x/src/se05x_mw.c`
- [SE05x APDUs](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x_03_xx_xx/se05x_APDU.c): apdu defs · SE05x APDU definitions and implementations for device commands. · `hostlib/hostLib/se05x_03_xx_xx/se05x_APDU.c`
- [TLV](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/se05x/src/se05x_tlv.c): encoding · 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.

- [Linux I2C](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/platform/linux/i2c_a7.c): platform adapter · Linux host access path for I2C transport. · `hostlib/hostLib/platform/linux/i2c_a7.c`
- [Timer](https://github.com/nxp/plug-and-trust/blob/master/hostlib/hostLib/platform/generic/sm_timer.c): platform adapter · Generic timing support for the host stack. · `hostlib/hostLib/platform/generic/sm_timer.c`

### Secure element

External SE05x device boundary.

- **SE05x**: secure element · External SE05x/SE051/SE052 boundary that stores keys and executes protected operations.

## Connections

- 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.