# Glossary

Plain-language definitions for terms used in this lab, the slide deck, and
[Verheul’s SECDSA EUDI-wallet paper](https://wellet.nl/SECDSA-EUDI-wallet-latest.pdf).

Educational / research context only — see [USAGE.md](../USAGE.md).

---

## Roles & systems

| Term | Meaning |
|------|---------|
| **Wallet** | The user’s device app. Holds the PIN, device key material, and (after activation) the Internal Certificate. Performs Algorithm 36. |
| **WSCA** | *Wallet Secure Cryptographic Application* — the wallet **provider’s software** (e.g. a container) that talks to the HSM and issues Transaction Records. **Not trusted** in the Annex F model. |
| **WSCD** | *Wallet Secure Cryptographic Device* — the HSM (or SoftHSM stand-in) that holds non-extractable keys and performs crypto ops. |
| **HSM** | *Hardware Security Module* — tamper-resistant crypto device. In this lab: SoftHSM2 or an in-memory mock. |
| **SoftHSM** | Software HSM implementing PKCS#11 (for development). Not a certified production HSM. |
| **Monitor** | Independent service that runs Algorithms 39–40 on Transaction Records + HSM audit logs. Needs **no secrets**. |
| **Judge** | Any third party that runs Algorithm 38 on public evidence (IC + Tr). |
| **Wallet provider** | Organization that runs the WSCA and (usually) the HSM. |
| **Relying party** | Party that consumes signatures / keys produced for the user (e.g. after `SIGN`). |
| **EUDI** | *European Digital Identity* (wallet ecosystem this design targets). |

---

## Cryptographic building blocks

| Term | Meaning |
|------|---------|
| **ECDSA** | *Elliptic Curve Digital Signature Algorithm* — standard signatures from a private scalar and a curve point public key. |
| **SECDSA** | *Split-ECDSA* — ECDSA-style signing whose strength is bound to **PIN + device key**, without casually exposing the PIN-sensitive public key. Described as **patent-encumbered**. |
| **P-256** | NIST curve `secp256r1` used throughout this lab. |
| **Point / scalar** | On an elliptic curve: a **point** is a public value; a **scalar** is a secret (or random) integer modulo the group order `q`. Notation `u · G` means scalar-multiply base point `G` by `u`. |
| **G** | Standard base point of the curve. |
| **Discrete log** | Hard problem: given `U = u · G`, recover `u`. Security assumption behind ECDSA / ECDH. |
| **ECDH** | *Elliptic-Curve Diffie–Hellman* — derive a shared secret from your private scalar and someone else’s public point (here: HSM multiplies by `a_U`). |
| **ZKP** | *Zero-knowledge proof* — prove a statement (e.g. “same discrete log”) without revealing the secret. Used so the WSCA can check consistency without learning the PIN. |
| **NIZK** | *Non-interactive* ZKP (no back-and-forth); this lab’s equality-of-discrete-logs style proofs. |
| **PoP** | *Proof of possession* — prove you hold the private key for a public key. |
| **AEAD / AES-GCM** | Authenticated encryption (this lab: AES-256-GCM) for instruction ciphertext. |
| **HKDF** | Key-derivation function (HMAC-based) used in PIN-binder / challenge responses. |
| **SHA-256** | Hash function used for ECDSA message digests and transcript hashes. |

---

## SECDSA key letters (wallet math)

| Symbol | Meaning |
|--------|---------|
| **u** | Device / NCH private key (possession factor). |
| **U** | Device public key: `U = u · G`. |
| **P** | PIN-derived scalar (knowledge factor), via PIN-binder. |
| **Y** | PIN-sensitive SECDSA public key: `Y = P · U`. **Must not** leak to the provider (offline PIN guessing). |
| **t** | Random blinding factor chosen on the phone during activation; deleted afterward. |
| **Y_bl** | Blinded public key sent to the provider: `Y_bl = t · Y`. |
| **a_U** | Per-account **blinding private key** in the HSM (non-extractable). |
| **G′** | `G' = a_U · G` — HSM blinding public key. |
| **Y′** | `Y' = a_U · Y` — blinded SECDSA public key placed in the Internal Certificate (wallet recovers it by unblinding `Y_bl'`). |
| **Y_bl′** | `Y_bl' = a_U · Y_bl` — what the HSM returns during issuance. |
| **R, R′** | SECDSA signature / proof points used so the WSCA can check `a_U · R ≟ R'` style relations via HSM ECDH. |
| **G″, Y″** | Additional blinded bases used in Algorithm 36 proofs (lab notation `Gpp` / `Ypp`). |

---

## PIN & lockout

| Term | Meaning |
|------|---------|
| **PIN** | User secret entered on the device; never sent in the clear to the WSCA. |
| **PIN-binder** | Function that turns the PIN into scalar `P` (this lab: Algorithm 24 HMAC binder). |
| **PC / PC_U** | PIN failure **counter** for account `U` at the WSCA. |
| **τ / τ_U** | PIN lockout **threshold** (lab default `5`). After `τ` failures the account should block. |
| **Blinding (audit kind)** | HSM use of `a_U` for PIN verify (counts toward lockout / Alg 39). |
| **Blinding-setup** | HSM use of `a_U` during Protocol 4 issuance only — **does not** count as a PIN attempt. |
| **User (audit kind)** | HSM use of a user/attestation key (`ECHO` / `GENKEY` / `SIGN`, …). |

---

## Certificates, records & windows

| Term | Meaning |
|------|---------|
| **IC** | *Internal Certificate* — binds account id, `G'`, `Y'`, `U` (and issuer signature). Issued in Protocol 4. Does **not** contain raw `Y`. |
| **Tr** | *Transaction Record* — publicly verifiable receipt that an instruction was authorized and executed (Algorithm 37 output). |
| **S** | Provider **record-signing** public key (signs ICs and Trs in this lab). |
| **ASN** | *Augmented Sequence Number*: `SN ‖ TS_S ‖ N` (28 bytes here). |
| **SN** | Per-account sequence number of the instruction. |
| **TS_S** | Window **start** timestamp from the freshness token. |
| **TS_E** | Window **end** timestamp written into the Tr. |
| **N** | Freshness **nonce** (random), part of ASN. |
| **Execution window** | Time interval `[TS_S, TS_E]` claimed by a Tr. Same-wallet windows **do not overlap**. |
| **Ĩ / I-tilde** | Encoded instruction payload inside the signed transcript. |
| **ASD** | Extra authenticated data framing around instruction + proof material (this lab uses length-prefixed fields). |
| **Chal / Challenge** | ZKP challenge object (includes ciphertext of the instruction under AEAD). |
| **Resp / H₁** | Challenge response bytes from Algorithm 22-style ECDH at the HSM. |
| **Compact line** | Small archive row: `ASN ‖ TS_E ‖ T₁ ‖ T₂ ‖ T₃ ‖ Sig` (~200 B) for local storage; full Tr rehydrated on dispute. |
| **T₁, T₂, T₃** | Hashes of Tr parts kept in the compact log. |

---

## Protocols & algorithms (paper numbering)

| Term | Meaning |
|------|---------|
| **Protocol 4** | Wallet **activation / issuance** of the Internal Certificate (blind SECDSA). |
| **Algorithm 1–2** | Core SECDSA sign / verify primitives. |
| **Algorithm 18** | Recover full EC point when PKCS#11 ECDH returns only the x-coordinate. |
| **Algorithm 19–23** | DL-equality ZKP and Chal / Resp helpers (incl. HSM ECDH response). |
| **Algorithm 22** | ECDH-based response with `a_U` (PIN verify / issuance path). |
| **Algorithm 24** | HMAC PIN-binder (this lab). |
| **Algorithm 36** | Wallet: build signed encrypted instruction + proofs. |
| **Algorithm 37** | WSCA: verify PIN via HSM, execute instruction, emit Tr. |
| **Algorithm 38** | Third-party verify Tr given IC + record public key. |
| **Algorithm 39** | Monitor: PIN-lockout conformity (blinding uses vs windows / `τ`). |
| **Algorithm 40** | Monitor: every user-key HSM use sits in a matching window / instruction. |
| **Annex D** | Concrete HSM-wallet protocol specification (issuance + instruct + verify). |
| **Annex F** | Monitoring / compromise-detection from Tr + audit (no trust in WSCA). |

---

## Instructions (lab ops)

| Term | Meaning |
|------|---------|
| **ECHO** | Demo op: HSM returns the payload; still audited as a **user** key use. |
| **GENKEY** | Create a P-256 user signing key **inside** the HSM/token; return public key in Tr. |
| **SIGN** | ECDSA-sign `SHA-256(data)` with that token key. |

---

## PKCS#11 vocabulary

PKCS#11 is a standard **C API** for tokens/HSMs. Names below are constants from that API (and SoftHSM).

| Term | Meaning |
|------|---------|
| **PKCS#11** | API standard (“Cryptoki”) for talking to HSMs/tokens. |
| **Token** | The logical HSM slot SoftHSM (or hardware) exposes. |
| **Session** | Opened connection to a token (`C_OpenSession`), often after login. |
| **Object handle** | Integer id the token uses for a key or cert object. |
| **CKM_…** | *Mechanism* — which crypto algorithm to run. |
| **CKA_…** | *Attribute* — property of a key object (extractable, sign, …). |
| **CKU_USER** | Normal user login role (vs security officer). |
| **CKM_ECDH1_DERIVE** | ECDH key-derivation mechanism: token computes shared secret from a local EC private key + peer public point. **This is the one-call PIN-auth path** with `a_U`. |
| **CKD_NULL** | ECDH key-derivation function “null”: return raw ECDH output (often the x-coordinate) rather than further KDF inside the token. |
| **CKM_EC_KEY_PAIR_GEN** | Generate an EC key pair on the token (`GENKEY`). |
| **CKM_ECDSA** | ECDSA sign/verify mechanism on the token (`SIGN`). |
| **CKA_TOKEN** | Object persists on the token (survives session close). |
| **CKA_PRIVATE** | Object is private (needs login). |
| **CKA_SENSITIVE** | Key material must not be revealed in plaintext. |
| **CKA_EXTRACTABLE** | Whether the key can be wrapped/exported. Lab blinding/user privates use **false**. |
| **CKA_SIGN / CKA_VERIFY** | Key may be used to sign / verify. |
| **CKA_EC_PARAMS** | Curve parameters (lab: P-256 OID). |
| **CKA_EC_POINT** | Public point encoding on an EC key object. |
| **CKA_LABEL / CKA_ID** | Human / binary labels to find keys again. |
| **Non-extractable** | Informal: `CKA_EXTRACTABLE = false` (+ sensitive) so `a_U` never leaves the token. |

### How `CKM_ECDH1_DERIVE` fits this design

1. HSM holds private `a_U`.
2. WSCA supplies a public point `E` (from the wallet’s proof).
3. One `CKM_ECDH1_DERIVE` computes material for `a_U · E` (with `CKD_NULL`, often only x).
4. That authenticates the PIN path (**audit: blinding**) without exporting `a_U`.

The **instruction** itself still needs a **second** HSM use for the user key (`GENKEY` / `SIGN` / …).

---

## Monitoring & alarms

| Term | Meaning |
|------|---------|
| **HSM audit log** | Time-stamped list of key uses (`blinding` / `user` / …) — trusted more than the WSCA process. |
| **Orphan** | User-key audit mark **outside** every execution window → Algorithm 40 alarm. |
| **Excess blinding** | More than `τ−1` blinding marks between consecutive windows → Algorithm 39 alarm. |
| **NO_ALARM** | Monitor result: streams look consistent. |
| **WSCA_COMPROMISE_ALARM** | Monitor result: streams disagree → suspend / investigate in the paper’s model. |
| **Sole control** | Property that only the user can authorize key use — here made **verifiable** via Tr + optional monitoring. |
| **Transaction transparency** | Ability for third parties to check what was authorized (Alg 38). |

---

## Lab / implementation shorthand

| Term | Meaning |
|------|---------|
| **Memory WSCD** | In-process fake HSM when SoftHSM is not configured. Same protocols, weaker deployment story. |
| **OpenPreferred** | Lab helper: try PKCS#11 SoftHSM, else fall back to memory. |
| **RogueExecute / RogueBlindingBurn** | Lab-only attack buttons (skip PIN / burn `τ` blinds) to demo monitoring. |
| **NCH** | *Native Cryptographic Hardware* on the phone (TEE/Secure Element style). This lab simulates it in software. |

---

## See also

- [Slide deck](slides.html) — narrative tour using these terms  
- [USAGE.md](../USAGE.md) — what you may do with this code  
- [NOTICE](../NOTICE) — patent disclaimer  
- Paper — full normative definitions and algorithm listings