250 lines
18 KiB
Markdown
250 lines
18 KiB
Markdown
<!-- ©AngelaMos | 2026 -->
|
|
<!-- README.md -->
|
|
|
|
```
|
|
██╗ ██╗███████╗███╗ ███╗ ███████╗███╗ ███╗██╗ ██╗██╗ █████╗ ████████╗ ██████╗ ██████╗
|
|
██║ ██║██╔════╝████╗ ████║ ██╔════╝████╗ ████║██║ ██║██║ ██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗
|
|
███████║███████╗██╔████╔██║ █████╗ ██╔████╔██║██║ ██║██║ ███████║ ██║ ██║ ██║██████╔╝
|
|
██╔══██║╚════██║██║╚██╔╝██║ ██╔══╝ ██║╚██╔╝██║██║ ██║██║ ██╔══██║ ██║ ██║ ██║██╔══██╗
|
|
██║ ██║███████║██║ ╚═╝ ██║ ███████╗██║ ╚═╝ ██║╚██████╔╝███████╗██║ ██║ ██║ ╚██████╔╝██║ ██║
|
|
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
|
|
```
|
|
|
|
[](https://github.com/CarterPerez-dev/Cybersecurity-Projects/tree/main/PROJECTS/advanced/hsm-emulator)
|
|
[](https://ziglang.org)
|
|
[](https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/errata01/os/pkcs11-base-v2.40-errata01-os.html)
|
|
[](https://github.com/OpenSC/OpenSC)
|
|
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
|
|
> A software **Hardware Security Module** that compiles to a real Cryptoki (PKCS#11) shared object. Load it with `pkcs11-tool`, OpenSSL, or any PKCS#11 host the same way you would a real smartcard or HSM. It speaks the C ABI byte for byte, generates and stores keys, signs and encrypts, and keeps private key material sealed on disk and zeroized in RAM.
|
|
|
|
[](https://youtu.be/Na-bmX9px4g)
|
|
[](https://youtu.be/Na-bmX9px4g)
|
|
|
|
|
|
## Why PKCS#11 in Zig
|
|
|
|
PKCS#11 (Cryptoki) is the C-ABI standard that smartcards, YubiKeys, and cloud HSMs all speak. A conforming module is a `.so` that exports one function, `C_GetFunctionList`, returning a 68-entry table of function pointers in a *fixed canonical order*. Get one struct offset or one pointer slot wrong and the host loads garbage.
|
|
|
|
That makes it a near-perfect showcase for Zig's C interop: `extern struct` with natural alignment, `callconv(.c)`, a version script that exports exactly one symbol, and a hand-written ABI that is **machine-checked against the official OASIS headers at build time**. On top of that ABI sits a real HSM: a login model, an attribute-bag object store, a full set of cryptographic mechanisms, and encrypted-at-rest key storage.
|
|
|
|
## What Works Today
|
|
|
|
This is not a stub. A host can drive the module through a complete key lifecycle, and every capability below is exercised by a cross-process `pkcs11-tool` run, an in-process smoke harness against the built `.so`, and unit tests.
|
|
|
|
**The ABI and the module**
|
|
- Loads under OpenSC `pkcs11-tool` 0.26.1, enumerates the slot and token (`-L`), advertises **21 mechanisms** (`-M`)
|
|
- Exports **only** `C_GetFunctionList` (verified with `objdump -T`); 34 `__ubsan_*` symbols are kept out of the dynamic table
|
|
- The full v2.40 ABI hand-written in `src/ck.zig`: every type, 200+ constants, every struct, and the 68-entry `CK_FUNCTION_LIST` in canonical order
|
|
- A build-time cross-check (`zig build test`) translates the vendored OASIS headers and asserts `@sizeOf` / `@offsetOf` / constant equality **and per-function C-ABI signatures** against `ck.zig`. Spec compliance is a compile-time invariant, not a hope
|
|
|
|
**Tokens, sessions, login**
|
|
- `C_InitToken` / `C_InitPIN` / `C_SetPIN` / `C_Login` / `C_Logout` with a real Security Officer and User role split
|
|
- PINs are stretched with **Argon2id** (t=3, m=64 MiB, p=1); only salt and hash touch disk, never the PIN
|
|
- Three wrong attempts trip a lockout (`CKR_PIN_LOCKED`), reflected in the token flags
|
|
- Read-only versus read-write session enforcement and the full session state machine
|
|
|
|
**Objects**
|
|
- `C_CreateObject` / `C_CopyObject` / `C_DestroyObject` / `C_GetObjectSize`
|
|
- Two-call `C_GetAttributeValue`, per-attribute, with `CKR_ATTRIBUTE_SENSITIVE` for sealed key material
|
|
- `C_FindObjects` triad with `CKA_PRIVATE` login gating (private objects are invisible before login)
|
|
- `CKA_MODIFIABLE` / `CKA_DESTROYABLE` honored
|
|
|
|
**Cryptography**
|
|
- Digest: SHA-256 / SHA-384 / SHA-512, single-shot and multi-part
|
|
- HMAC: HMAC-SHA-256 / 384 / 512, with constant-time tag verification
|
|
- AES: CBC, CBC-PAD, and GCM (128 and 256-bit keys), encrypt and decrypt, with streaming GCM that buffers until the tag verifies
|
|
- ECDSA: P-256 and P-384 keygen, `CKM_ECDSA` and `CKM_ECDSA_SHA256`, cross-verified against OpenSSL
|
|
- RSA via libcrypto: 2048 to 4096-bit keygen, PKCS#1 v1.5, PSS, and OAEP; sign / verify / encrypt / decrypt and Sign / VerifyRecover
|
|
- Key management: `C_GenerateKey` (AES), `C_GenerateKeyPair` (RSA / EC), `C_WrapKey` / `C_UnwrapKey` (AES-KEY-WRAP RFC 3394 and RSA-OAEP), `C_DeriveKey` (ECDH), `C_DigestKey`
|
|
- RNG: `C_GenerateRandom` drawn from `std.Io.randomSecure` (the OS CSPRNG)
|
|
|
|
**Encrypted at rest, zeroized in RAM**
|
|
- Token objects persist to a file. Sensitive attribute *values* are sealed with AES-256-GCM under a per-token master key
|
|
- The master key is wrapped under a single User-PIN keyslot (Argon2id-derived KEK). There is no Security-Officer keyslot for user secrets by design
|
|
- On `C_Logout`, `C_CloseAllSessions`, and `C_Finalize`, sealed secrets are re-sealed and the master key is wiped with `std.crypto.secureZero`. A failed re-seal fails closed (the plaintext is scrubbed in place)
|
|
|
|
See [`learn/CONFORMANCE.md`](learn/CONFORMANCE.md) for the precise return code at every deliberate boundary.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
git clone https://github.com/CarterPerez-dev/Cybersecurity-Projects.git
|
|
cd Cybersecurity-Projects/PROJECTS/advanced/hsm-emulator
|
|
./install.sh
|
|
```
|
|
|
|
`install.sh` checks for Zig 0.16, OpenSC, and OpenSSL, builds the module in ReleaseSafe, runs the ABI cross-check plus the smoke test, and confirms `pkcs11-tool` can load it. Then drive it like any real token. Point both storage paths at a scratch directory so you do not write into `$HOME`:
|
|
|
|
```bash
|
|
export ANGELAMOS_HSM_TOKEN=/tmp/hsm-token
|
|
export ANGELAMOS_HSM_OBJECTS=/tmp/hsm-objects
|
|
MOD=zig-out/lib/libhsm.so
|
|
|
|
pkcs11-tool --module $MOD -L # list slots and token
|
|
pkcs11-tool --module $MOD -M # list 21 mechanisms
|
|
|
|
pkcs11-tool --module $MOD --init-token --label demo --so-pin 12345678
|
|
pkcs11-tool --module $MOD --init-pin --so-pin 12345678 --pin 1234
|
|
pkcs11-tool --module $MOD -l --pin 1234 \
|
|
--keypairgen --key-type rsa:2048 --label signer
|
|
pkcs11-tool --module $MOD -l --pin 1234 \
|
|
--sign --mechanism SHA256-RSA-PKCS --label signer \
|
|
--input-file message.bin --output-file sig.bin
|
|
```
|
|
|
|
```
|
|
Available slots:
|
|
Slot 0 (0x0): AngelaMos HSM Emulator Slot 0
|
|
token state: uninitialized
|
|
```
|
|
|
|
> [!TIP]
|
|
> This project uses [`just`](https://github.com/casey/just) as a command runner. Type `just` to see everything. `just spy -L` wraps the module in `pkcs11-spy.so` and logs every Cryptoki call with its arguments and return code. It is the fastest way to watch the ABI work.
|
|
>
|
|
> Install: `curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin`
|
|
|
|
## Learn
|
|
|
|
This project ships a full teaching track. Read it in order, or jump to what you need.
|
|
|
|
| Doc | What it covers |
|
|
|-----|----------------|
|
|
| [`learn/00-OVERVIEW.md`](learn/00-OVERVIEW.md) | What an HSM is, why it exists, and a 10-minute tour |
|
|
| [`learn/01-CONCEPTS.md`](learn/01-CONCEPTS.md) | Key sensitivity, the login model, encryption at rest, constant-time, padding oracles, with real breaches |
|
|
| [`learn/02-ARCHITECTURE.md`](learn/02-ARCHITECTURE.md) | The three-layer design, object model, locking, the threat model |
|
|
| [`learn/03-IMPLEMENTATION.md`](learn/03-IMPLEMENTATION.md) | A code walkthrough of the ABI, an end-to-end operation, and the secret-handling patterns |
|
|
| [`learn/MECHANICS.md`](learn/MECHANICS.md) | How each cryptographic mechanism actually works, byte by byte |
|
|
| [`learn/CONFORMANCE.md`](learn/CONFORMANCE.md) | The v2.40 conformance statement: every narrowed behavior and its exact return code |
|
|
| [`learn/04-CHALLENGES.md`](learn/04-CHALLENGES.md) | Extension ideas from beginner to expert |
|
|
|
|
## Architecture
|
|
|
|
The same three-layer split SoftHSM2 uses: a thin C-ABI façade over typed core state over the store and crypto backends.
|
|
|
|
```
|
|
PKCS#11 host (pkcs11-tool, OpenSSL, p11-kit)
|
|
│ C ABI
|
|
▼
|
|
┌───────────────────────────────────────────┐
|
|
│ C_GetFunctionList (src/main.zig) │ one exported symbol,
|
|
│ 68-entry CK_FUNCTION_LIST │ one version script
|
|
└───────────────────────┬─────────────────────┘
|
|
│
|
|
┌───────────────────────┴─────────────────────┐
|
|
│ ABI façade src/ck.zig + src/api/*.zig │ hand-written Cryptoki ABI
|
|
│ general · slot_token · session · object · │ + per-call entry points,
|
|
│ crypto_ops · keymgmt · random │ argument and FSM validation
|
|
└───────────────────────┬─────────────────────┘
|
|
│
|
|
┌───────────────────────┴─────────────────────┐
|
|
│ core state src/core/*.zig │ global instance behind a lock,
|
|
│ state · session · object_store · token │ sessions, objects, PIN, master key
|
|
└───────────────────────┬─────────────────────┘
|
|
│
|
|
┌───────────────────────┴─────────────────────┐
|
|
│ crypto src/crypto/*.zig │ pure-Zig std.crypto for AES/EC/
|
|
│ digest · mac · cipher · ecdsa · rsa · │ hash/HMAC/ECDH, libcrypto for RSA,
|
|
│ keystore · pin · openssl │ Argon2id KDF, GCM envelope at rest
|
|
└───────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Design decisions:** non-RSA crypto is pure-Zig `std.crypto`. RSA links libcrypto (OpenSSL EVP) because `std.crypto` has no public RSA. The RSA binding is hand-written `extern` declarations, not `@cImport`, so the production `.so` exports nothing but `C_GetFunctionList`. The RNG is `std.Io.randomSecure`, which draws fresh entropy from the OS on every call (`getrandom(2)` on Linux) and keeps no CSPRNG state in process memory. The ABI is structured for v2.40 with room to add the v3.0 `C_GetInterface` surface later.
|
|
|
|
## Build and Test
|
|
|
|
```bash
|
|
zig build # build the module → zig-out/lib/libhsm.so (Debug)
|
|
zig build --release=safe # the shipped artifact: ReleaseSafe, UB checks as traps
|
|
zig build test # ABI cross-check vs OASIS headers + the unit suite
|
|
zig build smoke # dlopen the built .so and exercise the whole ABI as a host would
|
|
just ci # fmt-check + test + smoke
|
|
```
|
|
|
|
The smoke harness in `examples/smoke.zig` is not a unit test. It `dlopen`s the *actual built shared object* and calls through the function list exactly like an external host, so it catches export and ABI-shape bugs that in-process tests cannot. It walks a full lifecycle: init, login, keygen, sign, encrypt, wrap, derive, GCM streaming, dual-function, recover, operation-state, and the conformance edges.
|
|
|
|
> [!NOTE]
|
|
> Plain `zig build` produces a **Debug** binary. The shipped artifact is `--release=safe` (ReleaseSafe), which keeps every undefined-behavior check live and turns it into a fail-closed trap rather than silent corruption. Set both `ANGELAMOS_HSM_TOKEN` and `ANGELAMOS_HSM_OBJECTS` to a scratch path for tests and tool runs, or the module falls back to `$HOME/.angelamos-hsm-*`.
|
|
|
|
## Run in Docker
|
|
|
|
No Zig or OpenSC on the host? The container builds the module and drives it end to end through `pkcs11-tool`: token init, RSA and EC keygen and signing, AES-CBC round-trip, all inside the image.
|
|
|
|
```bash
|
|
just docker-demo # build the image, then run the full pkcs11-tool demo
|
|
```
|
|
|
|
Or with Docker directly:
|
|
|
|
```bash
|
|
docker build -t angelamos-hsm:latest .
|
|
docker run --rm angelamos-hsm:latest
|
|
```
|
|
|
|
A multi-stage build compiles the module in ReleaseSafe in a `debian-slim` builder, then ships only the `.so` plus `opensc` and `libssl3` in a roughly 96 MB runtime image. The demo exits non-zero if any signature fails to verify.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
hsm-emulator/
|
|
├── build.zig # addLibrary(.dynamic), version script, sanitize_c=.trap,
|
|
│ # libcrypto link, translate-c ABI cross-check, test + smoke
|
|
├── build.zig.zon # package manifest
|
|
├── pkcs11.map # version script: exports only C_GetFunctionList
|
|
├── src/
|
|
│ ├── ck.zig # the hand-written Cryptoki v2.40 ABI (types, constants, structs, list)
|
|
│ ├── config.zig # identity strings, key-size bounds, mechanism list (no magic numbers)
|
|
│ ├── util.zig # comptime helpers (space-padded fixed fields)
|
|
│ ├── main.zig # exported C_GetFunctionList + the wired 68-slot table
|
|
│ ├── core/
|
|
│ │ ├── state.zig # global instance behind a lock, init-args parsing, generation counter
|
|
│ │ ├── lock.zig # spinlock wrapper over std.atomic.Mutex
|
|
│ │ ├── env.zig # reads std.c.environ for storage paths at the C boundary
|
|
│ │ ├── token.zig # token record: PIN slots, fail counters, wrapped master key
|
|
│ │ ├── session.zig # session table, op-state unions, the RUP-safe GCM buffer
|
|
│ │ └── object_store.zig# attribute-bag objects, the selective-sealing codec
|
|
│ ├── api/
|
|
│ │ ├── general.zig # C_Initialize / Finalize / GetInfo / WaitForSlotEvent
|
|
│ │ ├── slot_token.zig # slot + token + mechanism queries, InitToken / InitPIN / SetPIN
|
|
│ │ ├── session.zig # OpenSession / Login / Logout / Get+SetOperationState
|
|
│ │ ├── object.zig # CreateObject / Find / GetAttributeValue
|
|
│ │ ├── crypto_ops.zig # the digest / sign / verify / encrypt / decrypt / dual surface
|
|
│ │ ├── keymgmt.zig # GenerateKey(Pair) / WrapKey / UnwrapKey / DeriveKey
|
|
│ │ └── random.zig # GenerateRandom / SeedRandom
|
|
│ └── crypto/
|
|
│ ├── openssl.zig # hand-written extern EVP/BN/OSSL_PARAM declarations
|
|
│ ├── pin.zig # Argon2id derive / verify (constant-time)
|
|
│ ├── digest.zig # SHA-2 hasher union + serializable op-state
|
|
│ ├── mac.zig # HMAC-SHA-2 union
|
|
│ ├── cipher.zig # AES-CBC/CBC-PAD/GCM + RFC 3394 key wrap
|
|
│ ├── ecdsa.zig # P-256/384 keygen, sign, verify, ECDH, curve OID + EC point DER
|
|
│ ├── rsa.zig # the stateless libcrypto RSA bridge
|
|
│ └── keystore.zig # master-key gen, wrap/unwrap, seal/unseal envelope
|
|
├── tests/abi_test.zig # @sizeOf/@offsetOf/constant/signature cross-check vs OASIS
|
|
├── examples/smoke.zig # loads the built .so via dlopen and drives the whole lifecycle
|
|
└── vendor/pkcs11/ # unmodified OASIS v2.40 headers (build-time cross-check only)
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
Each milestone ends with a proof from a real external tool. No feature is "done" until `pkcs11-tool` or OpenSSL exercises it.
|
|
|
|
| Milestone | Scope | Proof |
|
|
|-----------|-------|-------|
|
|
| **M0** ✅ | Scaffold + hand-written ABI + loadable `.so` | `pkcs11-tool -L/-M`, `objdump -T` |
|
|
| **M1** ✅ | Sessions + login + PIN (Argon2id, lockout) | `--init-token --init-pin --login --change-pin` |
|
|
| **M2** ✅ | Objects + find, `CKA_PRIVATE` gating | `-O --read-object`, two-call attribute fetch |
|
|
| **M3** ✅ | RNG + SHA-2 + HMAC + AES-CBC/CBC-PAD/GCM | `--hash --sign --encrypt --decrypt --generate-random` |
|
|
| **M4** ✅ | ECDSA P-256/384 + keygen | `--keypairgen EC --sign`, cross-verify with OpenSSL |
|
|
| **M5** ✅ | RSA via libcrypto (v1.5 / PSS / OAEP) | sign / verify / encrypt / decrypt through the module |
|
|
| **M6** ✅ | Encrypted store at rest (AES-256-GCM under Argon2id KEK) | survives restart; wrong PIN and tamper fail closed |
|
|
| **M7** ✅ | Hardening (secret zeroization, fail-closed relock) + Docker | leak-checked build, `just docker-demo` exits 0 |
|
|
| **M9** ✅ | Key management: wrap / unwrap, ECDH derive, digest-key | RFC 3394 KAT, ECDH matches `openssl pkeyutl -derive` |
|
|
| **M10** ✅ | Crypto surface: GCM streaming, dual-function, Sign/VerifyRecover, op-state | chunked GCM equals one-shot, recover round-trips |
|
|
| **M11** ✅ | Conformance pass + `CONFORMANCE.md` | every N/A boundary asserted against the built `.so` |
|
|
| **M12** ✅ | Learn modules + mechanism reference | this `learn/` track |
|
|
|
|
## License
|
|
|
|
[AGPL 3.0](LICENSE). The vendored OASIS headers under `vendor/pkcs11/` keep their original copyright and are used only for the build-time cross-check.
|