https://github.com/prasadrahul/hsm-simulator
HSM-Simulator is a lightweight Java-based wrapper over SoftHSM2 designed to simulate the behavior of an HSM such as AWS CloudHSM. It provides REST APIs for key management and cryptographic operations using the PKCS#11 interface, making it ideal for local development, integration testing, and prototyping secure applications.
https://github.com/prasadrahul/hsm-simulator
cloudhsm hsm java pkcs11 security simulator softhsm spring-boot
Last synced: about 1 month ago
JSON representation
HSM-Simulator is a lightweight Java-based wrapper over SoftHSM2 designed to simulate the behavior of an HSM such as AWS CloudHSM. It provides REST APIs for key management and cryptographic operations using the PKCS#11 interface, making it ideal for local development, integration testing, and prototyping secure applications.
- Host: GitHub
- URL: https://github.com/prasadrahul/hsm-simulator
- Owner: prasadrahul
- License: apache-2.0
- Created: 2025-04-11T14:15:35.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-11T16:12:00.000Z (about 1 year ago)
- Last Synced: 2025-04-12T03:59:04.090Z (about 1 year ago)
- Topics: cloudhsm, hsm, java, pkcs11, security, simulator, softhsm, spring-boot
- Language: Java
- Homepage:
- Size: 12.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hsm-simulator
A HSM simulator using SoftHSM and PKCS#11 for local testing of CloudHSM-like cryptographic operations.
# SoftHSM Wrapper - Java HSM Simulator
This project provides a Java-based wrapper for SoftHSM2 using the SunPKCS11 provider to simulate AWS CloudHSM-like functionalities. The goal is to create a local, developer-friendly environment to prototype, test, and simulate cryptographic operations similar to a real Hardware Security Module (HSM).
## Features
- Java + Spring Boot REST API
- AES-GCM encryption & decryption
- Key generation and listing
- Metadata lookup
- In-memory key simulation
- Pluggable for SoftHSM2 backend
- Ideal for testing HSM client logic locally
## Requirements
- Java 17+
- SoftHSM2 installed (libsofthsm2.so)
- Spring Boot 3.x
- Docker (optional)
## API Endpoints
| Method | Endpoint | Description |
|--------|----------------------------|------------------------|
| POST | `/api/keys/generate` | Generate new key |
| GET | `/api/keys` | List all keys |
| GET | `/api/keys/{id}` | Get metadata |
| POST | `/api/keys/{id}/encrypt` | Encrypt plaintext |
| POST | `/api/keys/{id}/decrypt` | Decrypt ciphertext |
## HSM related API Endpoints
| Method | Endpoint | Parameter(s) / Request Body | Description |
|--------|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| POST | `/api/v1/tool/generateSymmetricKey` | `{ "keyType": "AES_128", "id": "02", "label": "SymKeyLabel" }` | Generate symmetric keys |
| POST | `/api/v1/tool/generateAsymmetricKeyPair` | `{ "keyType": "RSA", "id": "01", "label": "AsymKeyLabel" }` | Generate an asymmetric key pair |
| GET | `/api/v1/tool/listKeys` | `type` (Query: Optional, e.g., 'cert', 'privkey', 'pubkey', etc.) | List all keys |
| GET | `/api/v1/tool/listMechanisms` | None | List all mechanisms |
| GET | `/api/v1/slots/{slotId}/keys` | `slotId` (Path: Integer) | List all keys in a specific slot |
| GET | `/api/v1/slots` | None | List all available slots |
| POST | `/api/v1/data/sign/{selectedKeyAlias}` | `{ "message": "example message", "signAlgo": "SHA256withRSA" }` | Sign a message using a key alias |
| POST | `/api/v1/data/verify/{selectedKeyAlias}` | `{ "message": "example message", "base64Signature": "base64EncodedSignature", "verifyAlgo": "SHA256withECDSA" }` | Verify a signature using a key alias |
| POST | `/api/v1/generateKey` | `{ "algorithm": "AES", "keySize": 256, "alias": "symmetricKeyAlias" }` | Generate a symmetric key |
| POST | `/api/v1/generateKeyPair` | `{ "algorithm": "RSA", "keySize": 2048, "ecCurve": "secp256r1", "alias": "keyPairAlias" }` | Generate a key pair |
| POST | `/api/v1/encrypt/{algorithm}` | `{ "plainText": "example text" }` | Encrypt a message |
| POST | `/api/v1/decrypt/{algorithm}` | `{ "base64Encrypted": "base64EncodedText" }` | Decrypt a message |
| GET | `/api/v1/random/{byteCount}` | `byteCount` (Path: Positive Integer, e.g., 16 or 32) | Generate random bytes |
## Login and Authentication
This API does not implement authentication or authorization. It is intended for local development and testing purposes only. In a production environment, you should implement proper security measures.
| Method | Endpoint | Parameter(s) / Request Body | Description |
|--------|---------------------------|------------------------------------------------|---------------------------------|
| POST | `/api/v1/auth/login` | `{ "username": "user", "password": "pass" }` | Authenticate and obtain a token |
| POST | `/api/v1/auth/logout` | None | NA |
| GET | `/api/v1/auth/status` | None | NA |
## Swagger API Documentation
Refer to the API documentation for detailed request and response formats.
- http://localhost:8080/swagger-ui/index.html
## License
This project is licensed under the Apache 2.0 License - see the [LICENSE](./LICENSE) file for details.
## Acknowledgements
- [SoftHSM2](https://github.com/opendnssec/SoftHSMv2) - BSD-2-Clause Licensed
- Java SunPKCS11 provider - part of OpenJDK
- [OpenSC](https://github.com/OpenSC/OpenSC) - LGPL-2.1 Licensed
- [Spring Boot](https://spring.io/projects/spring-boot) - Apache 2.0 Licensed
- [Springdoc](https://springdoc.org/) - Apache 2.0 Licensed
**Note:** This project is intended as a development and testing tool. It is not a replacement for certified HSM systems in production.