# FreeHSM C --- Common Criteria EAL4+ Target of Evaluation

**TOE name:** FreeHSM Cryptographic Module
**TOE version:** 1.0.0-FIPS
**Target EAL:** EAL4 augmented with ALC_FLR.2 (Flaw remediation) and AVA_VAN.5 (Advanced vulnerability analysis)
**Protection Profile claim:** *eIDAS QSCD* (EN 419211-2) or *cPP for Cryptographic Modules* (NIAP, when published)

---

## 1. TOE description (ASE_INT.1)

### 1.1 TOE type

The TOE is a software cryptographic module ("Soft HSM") providing PKCS#11 v3.2 services to applications. It is delivered as a single shared object `libfreehsm.so` plus the configuration file `freehsm.conf`. It depends on the OpenSSL 3.x FIPS provider, which is treated as a separately-evaluated module within the same Operational Environment.

### 1.2 Major security features

- Multi-role authentication (CO + USER) with PBKDF2-derived key wrapping
- Exponential PIN throttling + permanent lockout
- AES-GCM token store encryption with DEK rotation on CO PIN change
- Append-only audit log with HMAC-chained tamper detection
- OpenSSL secure heap for all SSP material (mlock + zeroize)
- Pre-operational self-test (KAT) before any service is exposed
- Optional sealing of the DEK to TPM 2.0, AWS KMS, GCP KMS, HashiCorp Vault, or a quorum (Shamir 3-of-5)

### 1.3 Non-TOE hardware / firmware / software

- Linux kernel ≥ 5.4 (for `getrandom`, `memfd_secret`, `prctl`)
- glibc / musl
- OpenSSL 3.x FIPS provider (separately evaluated, NIST CMVP cert ref. to be filled in)
- Optional TPM 2.0 hardware (the TPM itself is outside the TOE; only its API is used)

## 2. Conformance claims (ASE_CCL.1)

- CC version: 3.1 release 5 (April 2017) — Parts 2 conformant + Part 3 conformant
- Augmentation: ALC_FLR.2, AVA_VAN.5
- Strict conformance with PP cPP-CMOD-v2.0 (when published)

## 3. Security objectives (ASE_OBJ.2)

### 3.1 Security objectives for the TOE

| Identifier | Statement                                                              |
|------------|------------------------------------------------------------------------|
| O.CRYPTO   | The TOE shall provide cryptographic services using only FIPS-validated primitives loaded from the OpenSSL FIPS provider. |
| O.AUTH     | The TOE shall authenticate operators (CO, USER) before granting access to private key material. |
| O.AUDIT    | The TOE shall record security-relevant events in an append-only log resistant to insertion, deletion, and modification by an attacker without the audit-MAC key. |
| O.SSP      | The TOE shall protect Sensitive Security Parameters (DEKs, private keys, PINs) from unauthorized disclosure during operation and on termination (zeroize). |
| O.SELFTEST | The TOE shall perform power-on and conditional self-tests; on failure, the TOE shall enter an unrecoverable ERROR state. |
| O.ROLE_SEP | The TOE shall enforce separation between CO and USER roles: only CO can re-initialize the token or unlock a USER PIN; only the role owner can change its own PIN. |

### 3.2 Security objectives for the operational environment

| Identifier | Statement                                                              |
|------------|------------------------------------------------------------------------|
| OE.OS      | The operational OS shall provide process isolation (no `ptrace` from a different UID) and `mlock` capability. |
| OE.STORAGE | The filesystem storing token files shall provide atomic file replacement (rename + fsync). |
| OE.OPENSSL | The OpenSSL FIPS provider shall be installed, validated, and in approved mode. |
| OE.OP      | Operators shall protect their authentication credentials (PIN) and shall not log in over an untrusted channel. |
| OE.PHYS    | The host shall be physically protected against unauthorized access (server room or equivalent). |

## 4. Security requirements (ASE_REQ.2)

### 4.1 Class FAU --- Audit

- **FAU_GEN.1** (Audit data generation) --- the TOE generates audit records for the events listed in `fhsm_audit_event_t` (see `include/fhsm_audit.h`).
- **FAU_GEN.2** (User identity association) --- every audit record contains the slot, session, and authenticated role.
- **FAU_SAA.1** (Potential violation analysis) --- the TOE detects 5 consecutive failed authentication attempts → lockout event.
- **FAU_STG.1** (Protected audit trail storage) --- the log is HMAC-chained; the audit-MAC key is derived from the DEK and never leaves the TOE.

### 4.2 Class FCS --- Cryptographic support

- **FCS_CKM.1** (Cryptographic key generation) --- all keys are generated by the FIPS provider's DRBG; key generation services emit `FHSM_EV_GENERATE_KEY` / `_KEYPAIR`.
- **FCS_CKM.4** (Cryptographic key destruction) --- all SSPs are stored in the secure heap and zeroized by `OPENSSL_secure_clear_free` upon `C_DestroyObject`, `C_Logout`, `C_Finalize`, or token lock.
- **FCS_COP.1** (Cryptographic operation) --- operations restricted to the algorithms listed in `docs/FIPS_140_3.md` §4.
- **FCS_RBG_EXT.1** (Random bit generation) --- CTR_DRBG-AES-256 from the OpenSSL FIPS provider with a SP 800-90B entropy source.

### 4.3 Class FDP --- User Data Protection

- **FDP_ACC.1** (Subset access control) --- the SFP "Object access" restricts SO/USER privileges per §3 of `docs/FIPS_140_3.md`.
- **FDP_ACF.1** (Security attribute based access control) --- decisions based on `CKA_PRIVATE`, `CKA_SENSITIVE`, `CKA_EXTRACTABLE` and the authenticated role.
- **FDP_ITC.2** (Import with security attributes) --- `C_UnwrapKey` sets `CKA_LOCAL = false`; imports go through the same access check.
- **FDP_RIP.1** (Residual information protection) --- secure-heap zeroize on free; objects destroyed on `C_DestroyObject` are unrecoverable.

### 4.4 Class FIA --- Identification and Authentication

- **FIA_UAU.2** (User authentication before any action) --- `C_GetTokenInfo` is the only public service callable before `C_Login`.
- **FIA_AFL.1** (Authentication failure handling) --- 5 consecutive failures → lock; counter persisted to the token file.
- **FIA_UID.2** (User identification before any action) --- the role (CO/USER) is identified at `C_Login` via the `CKU_*` flag.
- **FIA_SOS.1** (Verification of secrets) --- PIN length ≥ 8 octets; passed to PBKDF2 with ≥ 200_000 iterations.

### 4.5 Class FMT --- Security Management

- **FMT_MOF.1** (Management of security functions behavior) --- only CO can call `C_InitToken` and `C_SetPIN` on the USER PIN.
- **FMT_MTD.1** (Management of TSF data) --- attribute modification limited per the SFP.
- **FMT_SMR.1** (Security roles) --- CO and USER are the only roles.

### 4.6 Class FPT --- Protection of the TSF

- **FPT_TST.1** (TSF testing) --- pre-operational self-tests at `C_Initialize`.
- **FPT_FLS.1** (Failure with preservation of secure state) --- on self-test failure, the TOE enters the latched ERROR state.
- **FPT_RCV.1** (Manual trusted recovery) --- recovery from ERROR requires manual restart by the administrator.

### 4.7 Class FTA --- TOE access

- **FTA_SSL.4** (User-initiated termination) --- `C_Logout` and `C_CloseSession` zeroize per-session secrets.

## 5. Modular design (ADV_TDS.3)

| Subsystem        | File(s)                          | TSFI exposed                  |
|------------------|----------------------------------|-------------------------------|
| State machine    | `src/fhsm_state.c`               | (internal only)               |
| Secure memory    | `src/fhsm_memory.c`              | (internal only)               |
| Crypto primitives| `src/fhsm_crypto.c` + `kat/`     | (internal only)               |
| Token store      | `src/fhsm_token.c`               | (internal only)               |
| Session table    | `src/fhsm_session.c`             | (internal only)               |
| Audit log        | `src/fhsm_audit.c`               | (internal only)               |
| PKCS#11 façade   | `src/fhsm_pkcs11.c`              | `C_*` (full PKCS#11 v3.2)    |

The TSFI is exclusively the set of `C_*` symbols exported by `libfreehsm.so`. All other symbols are hidden by `-fvisibility=hidden` and the linker version script.

## 6. Lifecycle (ALC_*)

### 6.1 ALC_CMC.4 --- Production support, acceptance procedures, automation

- Source control: Git, signed tags only. The maintainer's public key is published on
  keys.openpgp.org with email verification and is included in the repository
  as `afchine-pubkey.asc`; a `docs/keys/dev-pubkeys.gpg` keyring was named
  here as the eventual multi-maintainer form and has not been written, there
  being one maintainer.
- Build: reproducible via `Dockerfile.build` (Debian 12 + OpenSSL 3.2 FIPS module from CMVP cert #4825).
- Acceptance: every release tag triggers the full test suite + KAT + lint + `cppcheck` + `scan-build` + `clang-tidy` clean.

### 6.2 ALC_FLR.2 --- Flaw reporting procedures

- Public security contact: `security@freehsm.example` (PGP key fingerprint TBD).
- Coordinated disclosure window: 90 days.
- Backport policy: every supported branch (current + N-1) receives every security fix within 14 days of public disclosure.

### 6.3 ALC_TAT.1 --- Well-defined development tools

- Compiler: `gcc ≥ 12.0` or `clang ≥ 15.0` with the flag set defined in `Makefile`.
- Tested under `valgrind --tool=memcheck`, `valgrind --tool=helgrind`, `ASAN`, `UBSAN`.

## 7. Vulnerability analysis (AVA_VAN.5)

The TOE is designed to resist attacks with attack potential **Beyond-High**, the AVA_VAN.5 target. Evidence:

- **Side-channel resistance**: constant-time tag/MAC comparison; secure heap mlock to defeat cold-boot exfiltration; no branch-on-secret in the AES-GCM, HMAC, or PBKDF2 paths (delegated to OpenSSL FIPS provider, separately validated).
- **Fault-injection resistance**: every self-test result is double-checked (constant-time compare); the ERROR state is latched so a single fault cannot unlock a previously-rejected operation.
- **Logical attacks**: the audit log makes after-the-fact detection trivial; the throttle + lockout makes online brute-force impractical.
- **Coverage analysis**: lcov coverage report (target ≥ 95% line, 90% branch) attached to every release.

## 8. Delivery (ALO_DEL.1)

The TOE is delivered as a signed `.tar.xz` source archive (`make dist`) and a binary RPM/DEB package built reproducibly. Both bundles are signed with the same GPG key. Customers verify the signature and the SHA-256 digest published on the project website over HTTPS.

## 9. TSF list — v1.1.0 additions

The CST-evidence work batch adds 4 transverse TSFs that complement the EAL4+ functional family coverage:

| TSF identifier | Family | Description | Source |
|---|---|---|---|
| **FCS_RBG_EXT.1** | FCS (Cryptographic Support) | Hardened DRBG with multi-source seeding (getrandom + RDRAND + /dev/urandom + TSC jitter), SHA-256 conditioner per SP 800-90C, NIST SP 800-90B health tests (RCT, APT, CRNGT), auto-reseed every 1 MiB or 1 h. | `src/fhsm_drbg.c`, `include/fhsm_drbg.h`, [`RNG.md`](RNG.md) |
| **FCS_CKM_EXT.4** | FCS | Pair-wise consistency check post `C_GenerateKeyPair` (RSA, EC, ML-KEM, ML-DSA, SLH-DSA). Failure latches ERROR + refusal to persist. Per FIPS 140-3 §7.10.2.b. | `src/fhsm_pairwise.c`, `include/fhsm_pairwise.h` |
| **FPT_TST_EXT.1** | FPT (Protection of TSF) | TPM 2.0 sealing of the per-token DEK (opt-in via `FHSM_TPM_SEALING=1`). DEK bound to PCRs 0-7 of the boot chain. Mismatch on unseal treated as wrong PIN (oracle resistance). | `src/fhsm_token_tpm.c`, `src/fhsm_tpm.c` |
| **FMT_SMR_EXT.1** | FMT (Security Management) | Runtime mode switch between **legacy** (default) and **FIPS strict** via `FHSM_MODE` env or `mode =` conf directive. Sufficient for a single binary to satisfy both the FIPS 140-3 evaluator and interop-only operators. | `src/fhsm_mode.c`, `src/dispatch/fhsm_dispatch_legacy.c` |

### 9.1 Updated ADV_FSP coverage

| External interface | TSF covered |
|---|---|
| `C_GenerateKeyPair` | FCS_CKM_EXT.4 (pair-wise check) + existing FCS_CKM.1 |
| Any `fhsm_rng_bytes` consumer | FCS_RBG_EXT.1 (RCT + APT + CRNGT) |
| `fhsm_token_init` / `fhsm_token_login` | FPT_TST_EXT.1 (optional TPM sealing) |
| Every `C_*` mechanism call | FMT_SMR_EXT.1 (mode-dependent dispatch) |
