# nxp-auto-linux/pkcs11-hse architecture

> Architecture diagram of the GitHub repository nxp-auto-linux/pkcs11-hse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nxp-auto-linux/pkcs11-hse
- Repository: https://github.com/nxp-auto-linux/pkcs11-hse

## Overview

##### Project type and purpose
- This is a middleware/security‐library project. It implements a PKCS#11 module (“pkcs11-hse.so”) that sits between standard crypto libraries (OpenSSL/libp11) and NXP’s HSE (Hardware Secure Engine).
- Purpose: allow host applications (or tools like OpenSC’s pkcs11-tool) to perform key generation, storage, and cryptographic operations inside the secure HSE, via the standard PKCS#11 API.

##### File structure
- Top level contains build scripts (Makefile, common.mk), configuration (.checkpatch.conf), and license files.
- `libhse/`: internal HSE user-mode API, memory abstractions, header definitions.
- `libpkcs/`: implements the PKCS#11 interface (C files for C_Initialize, C_GenerateKeyPair, etc.), plus redistribution headers.
- `examples/`: sample host applications demonstrating use of pkcs11-hse.so (e.g., key generation, encryption, TrustZone provisioning).
- No “frontend/backend” split; it’s a native C library, built via Makefiles, cross‐compiled for aarch64.

##### README for additional insights
- Describes cross‐compiling prerequisites: OpenSSL and libp11 for aarch64, then building pkcs11-hse.so.
- Explains runtime usage: host app links against libp11 and libcrypto, loads the PKCS#11 module, and drives HSE operations.
- Also shows how to integrate with OpenSC’s pkcs11-tool for manual key provisioning.

##### Elements
- **Rectangles**: Host App, libp11, pkcs11-hse.so, libhse, HSE Hardware
- Runtime components in another (e.g., green)
- Hardware in a distinct shade (e.g., gray)
- **Labels**: function calls (C_Initialize, C_GenerateKeyPair, HSE_EncryptCmd, etc.), file/folder names if helpful.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build Stage
    subgraph "Build Stage"
        direction TB
        CC["Cross-Compile Toolchain"]:::build
        OpenSSL["OpenSSL (libcrypto)"]:::build
        LibP11Build["libp11"]:::build
        PKCSModuleBuild["pkcs11-hse.so"]:::build
        CC -->|"compiles"| OpenSSL
        CC -->|"compiles"| LibP11Build
        CC -->|"compiles"| PKCSModuleBuild
    end

    %% Runtime Stage
    subgraph "Runtime Stage"
        direction TB
        HostApp["Host Application (examples/OpenSC)"]:::runtime
        LibP11["libp11"]:::runtime
        PKCSModule["pkcs11-hse.so"]:::runtime
        HSEAPI["libhse (HSE User-Mode API)"]:::runtime
        HSEHardware["NXP HSE Hardware"]:::hardware

        HostApp -->|"dlopen"| LibP11
        LibP11 -->|"loads"| PKCSModule
        PKCSModule -->|"calls libhse API"| HSEAPI
        HSEAPI -->|"sends commands"| HSEHardware
        HSEHardware -->|"returns results"| HSEAPI
        HSEAPI -->|"returns"| PKCSModule
        PKCSModule -->|"returns"| LibP11
        LibP11 -->|"returns"| HostApp
    end

    %% Click Events
    click HostApp "https://github.com/nxp-auto-linux/pkcs11-hse/tree/release/bsp44.0/examples/"
    click LibP11Build "https://github.com/nxp-auto-linux/pkcs11-hse/blob/release/bsp44.0/libpkcs/include/pkcs11-unix.h"
    click PKCSModuleBuild "https://github.com/nxp-auto-linux/pkcs11-hse/blob/release/bsp44.0/libpkcs/pkcs11.c"
    click PKCSModule "https://github.com/nxp-auto-linux/pkcs11-hse/blob/release/bsp44.0/libpkcs/pkcs11_generate.c"
    click HSEAPI "https://github.com/nxp-auto-linux/pkcs11-hse/blob/release/bsp44.0/libhse/libhse.h"

    %% Styles
    classDef build fill:#CCEEFF,stroke:#222,stroke-width:1px
    classDef runtime fill:#EEFFCC,stroke:#222,stroke-width:1px
    classDef hardware fill:#CCCCCC,stroke:#222,stroke-width:1px
```
