How prasadrahul/hsm-simulator works
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