# prasadrahul/hsm-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/prasadrahul/hsm-simulator
- Repository: https://github.com/prasadrahul/hsm-simulator

## Overview

##### Project type and purpose
- This is a backend-only Spring Boot microservice (“hsm-simulator”) that exposes a REST API to simulate HSM operations locally.
- It wraps SoftHSM2 via the Java SunPKCS11 provider to offer key generation, metadata lookup, encryption/decryption, and key listing just like AWS CloudHSM.

##### File structure
- Top‐level files: Dockerfile, SoftHsmProvider.cfg, pom.xml, application.properties → build, runtime config, containerization.
- src/main/java/com/hsm/simulator:
- HsmServerApplication.java – Spring Boot entry point
- config/PKCS11Config.java – loads SunPKCS11 provider pointing at libsofthsm2.so and SoftHsmProvider.cfg
- controller/KeyController.java – defines REST endpoints (/api/keys/…)
- service/KeyService.java – business logic for key ops, delegates to the crypto provider
- No frontend or database; uses in‐memory HSM slots via SoftHSM2 backend.

##### README
- Confirms Java17+, Spring Boot 3.x, SoftHSM2 requirement.
- Lists five API endpoints for key gen, listing, metadata, encrypt, decrypt.
- Emphasizes local testing, pluggable backend, developer‐friendly.

##### Main components
a. External Clients
- Postman, CLI, automated tests
b. Spring Boot REST API
- Controllers (KeyController)
- Service Layer (KeyService)
- Configuration (PKCS11Config)
c. Crypto Provider Layer
- SunPKCS11 Java Security provider
- SoftHSM2 native library (libsofthsm2.so)
- SoftHsmProvider.cfg binds PKCS#11 slot configuration
d. HSM Slot & Key Store
- In‐memory token slots managed by SoftHSM2
e. Infrastructure
- Host OS (or Docker container) running SoftHSM2
- Dockerfile for containerizing the simulator + SoftHSM2

##### Relationships and interactions
1) Client → HTTP(S) Request → REST Controller
2) Controller → delegates to Service Layer
3) Service Layer → calls Java Crypto API (Cipher, KeyPairGenerator) via SunPKCS11 provider
4) SunPKCS11 provider → native bridge → libsofthsm2.so → SoftHSM2 token slot
5) SoftHSM2 executes crypto operation, returns result back up the chain
6) Service Layer → wraps result → Controller → HTTP Response → Client

##### Architectural patterns & principles
- Layered architecture: presentation (REST), business (service), infrastructure (crypto provider)
- Dependency injection: PKCS11Config injects Provider into the JCE framework
- Single‐responsibility per package
- Pluggable backend: swap SoftHSM2 for any PKCS#11‐compliant HSM

##### Technologies & frameworks
- Java 17, Spring Boot 3.x (spring-boot-starter-web)
- JCA / JCE (SunPKCS11 provider)
- SoftHSM2 (native library)
- Docker (optional container)
- Maven (build)

##### Final checklist
- Components: Client, Controller, Service, Config, SunPKCS11, SoftHSM2 token
- Labels: file names (PKCS11Config), endpoints, libraries (libsofthsm2.so)
- Detail: call flows for generate, list, encrypt, decrypt, metadata

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["External Client\n(Postman, CLI, Tests)"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container" 
        style Docker Container fill:#f8f9fa,stroke:#adb5bd

        %% Spring Boot Application Layer
        subgraph "Spring Boot Application"
            style Spring Boot Application fill:#cce5ff,stroke:#66b0ff
            Entry["HsmServerApplication"]:::app
            Controller["KeyController\n(/api/keys/…)"]:::app
            Service["KeyService"]:::app
            Config["PKCS11Config\n(uses SoftHsmProvider.cfg)"]:::config
        end

        %% Crypto Provider Layer
        subgraph "Crypto Provider Layer"
            style Crypto Provider Layer fill:#d4edda,stroke:#82c97a
            SunPKCS11["SunPKCS11 Provider"]:::provider
            SoftHSM2["SoftHSM2\n(libsofthsm2.so)"]:::provider
            HSMSlot["In-Memory HSM Slots"]:::provider
        end

        %% Supporting Files
        AppProps["application.properties"]:::config
        DockerfileNode["Dockerfile"]:::infra
        POM["pom.xml"]:::infra
    end

    %% Host OS
    HostOS[(Host OS)]:::external

    %% Interactions
    Client -->|"HTTP Request"| Controller
    Controller -->|"delegate()"| Service
    Service -->|"use JCE APIs"| SunPKCS11
    Config -->|"register()"| SunPKCS11
    SunPKCS11 -->|"native bridge"| SoftHSM2
    SoftHSM2 -->|"operate on"| HSMSlot
    HSMSlot -->|"result"| SoftHSM2
    SoftHSM2 -->|"return"| SunPKCS11
    SunPKCS11 -->|"crypto result"| Service
    Service -->|"wrap result"| Controller
    Controller -->|"HTTP Response"| Client

    %% Docker Execution Context
    SoftHSM2 --> HostOS
    HostOS --> DockerContainer

    %% Click Events
    click Entry "https://github.com/prasadrahul/hsm-simulator/blob/main/src/main/java/com/hsm/simulator/HsmServerApplication.java"
    click Controller "https://github.com/prasadrahul/hsm-simulator/blob/main/src/main/java/com/hsm/simulator/controller/KeyController.java"
    click Service "https://github.com/prasadrahul/hsm-simulator/blob/main/src/main/java/com/hsm/simulator/service/KeyService.java"
    click Config "https://github.com/prasadrahul/hsm-simulator/blob/main/src/main/java/com/hsm/simulator/config/PKCS11Config.java"
    click SoftHSM2 "https://github.com/prasadrahul/hsm-simulator/blob/main/SoftHsmProvider.cfg"
    click AppProps "https://github.com/prasadrahul/hsm-simulator/blob/main/src/main/resources/application.properties"
    click DockerfileNode "https://github.com/prasadrahul/hsm-simulator/tree/main/Dockerfile"
    click POM "https://github.com/prasadrahul/hsm-simulator/blob/main/pom.xml"

    %% Styles
    classDef app fill:#cce5ff,stroke:#66b0ff;
    classDef provider fill:#d4edda,stroke:#82c97a;
    classDef external fill:#e2e3e5,stroke:#b0b0b0;
    classDef config fill:#fff3cd,stroke:#f0ad4e;
    classDef infra fill:#f5c6cb,stroke:#e4606d;
```
