SRO PKCS11 – SSH Agent CNG

Sovereign unification PKCS#11 + SSH-agent + Pageant + CNG/Smartcard

A single Windows executable that unifies four traditionally separate functions:

• Full PKCS#11 module (Firefox, OpenSC, ssh -I)
• SSH agent compatible with OpenSSH/Git/VS/WSL
• Pageant server compatible with PuTTY/plink/pscp
• Secure CNG/KSP orchestrator for smartcards

---

Table of Contents

1. Philosophy
2. Architecture
3. Execution Modes
4. Installation
5. Configuration
6. Supported Protocols
7. PIN Management
8. CNG Backend
9. Security
10. Compatibility
11. Public Key Export
12. Tray Icon
13. WSL2 Support
14. Conflict Detection
15. Dependencies
16. Known Limitations
17. Roadmap

---

Philosophy

Sovereign. No CRT dependency. All memory operations use RtlCopyMemory, RtlZeroMemory, RtlEqualMemory (FreeCRT.h). Unicode everywhere (native Win32). No malloc, memcpy, strlen, printf.

Secure. Private keys are never exported. No PIN transits. CNG/KSP handles native Windows PIN UI. Strict service ↔ userland isolation via secure pipes.

Minimalist. Single binary. No external DLLs. No registry bloat. Simple installation (regsvr32 or -install).

Versatile. Simultaneous support for PKCS#11, SSH-agent, Pageant, and WSL2 in the same process.

---

Architecture```

┌──────────────────────────────────────────────────────────────┐ │ Clients (Git, VS, WSL, OpenSSH, PuTTY, Firefox) │ └────────────────────────┬─────────────────────────────────────┘ │ ┌───────────────┼───────────────┬─────────────────┐ │ │ │ │ SSH-agent Pageant (WM_COPYDATA) PKCS#11 WSL2 (TCP) │ │ │ │ v v v v ┌──────────────────────────────────────────────────────────────┐ │ Service Stub (session 0, SYSTEM) │ │ - Accepte connexions sur \.\pipe\openssh-ssh-agent │ │ - Crée pipe interne par client (GUID unique) │ │ - Lance helper userland avec token interactif │ │ - Forwarde messages sans manipuler de secrets │ └────────────────────────┬─────────────────────────────────────┘ │ lancé par le service v ┌──────────────────────────────────────────────────────────────┐ │ Helper Userland (session interactive) │ │ - Connecte au pipe interne │ │ - Décode protocole SSH-agent/Pageant │ │ - Invoque CNG/KSP pour signature │ │ - UI PIN native Windows (pas de relay) │ │ - Renvoie signature au service │ │ - Fenêtre Pageant cachée pour WM_COPYDATA │ │ - Listener TCP 127.0.0.1:10022 pour WSL2 │ │ - Tray icon avec menu contextuel │ └────────────────────────┬─────────────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────┐ │ CNG/KSP Backend │ │ - NCryptSignHash avec PKCS#1/PSS padding │ │ - Enumération certificats Windows Store │ │ - Filtrage SmartCardOnly / AllowedKSP │ │ - Support RSA + ECDSA (P-256, P-384, P-521) │ │ - Support EdDSA (Ed25519, Ed448) │ │ - Support Brainpool (P256r1, P384r1, P512r1) │ │ - Cache clés + providers (4h timeout) │ └──────────────────────────────────────────────────────────────┘

---

## Execution Modes

### 1. PKCS#11 Mode (automatic)

Loaded by:
- `ssh -I ssh-agent.exe user@host`
- Firefox (Security Devices → Load PKCS#11 Module)
- `pkcs11-tool --module ssh-agent.exe --list-objects`

Exposes standard PKCS#11 exports:
- `C_Initialize`, `C_Finalize`, `C_GetInfo`
- `C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`
- `C_GetMechanismList`, `C_GetMechanismInfo`
- `C_OpenSession`, `C_CloseSession`, `C_Login`, `C_Logout`
- `C_FindObjectsInit`, `C_FindObjects`, `C_FindObjectsFinal`
- `C_GetAttributeValue`
- `C_SignInit`, `C_Sign`
- `C_VerifyInit`, `C_Verify`
- `C_DecryptInit`, `C_Decrypt`
- `C_GenerateRandom`, `C_SeedRandom`

**Supported mechanisms (14 total):**
- `CKM_RSA_PKCS` (raw with padding)
- `CKM_RSA_X_509` (raw without padding)
- `CKM_SHA1_RSA_PKCS` (legacy ssh-rsa)
- `CKM_SHA256_RSA_PKCS` (rsa-sha2-256)
- `CKM_SHA384_RSA_PKCS` (rsa-sha2-384)
- `CKM_SHA512_RSA_PKCS` (rsa-sha2-512)
- `CKM_SHA256_RSA_PKCS_PSS` (RSA-PSS SHA-256)
- `CKM_SHA384_RSA_PKCS_PSS` (RSA-PSS SHA-384)
- `CKM_SHA512_RSA_PKCS_PSS` (RSA-PSS SHA-512)
- `CKM_ECDSA` (raw)
- `CKM_ECDSA_SHA1` (legacy)
- `CKM_ECDSA_SHA256` (ecdsa-sha2-nistp256/384/521)
- `CKM_ECDSA_SHA384`
- `CKM_ECDSA_SHA512`

### 2. Userland Agent Mode (standalone)```bash
ssh-agent.exe

• Creates the pipe \\.\pipe\openssh-ssh-agent in user session
• Implements the SSH-agent protocol
• Multi-client support (max 16 simultaneous connections)
• Automatically launches the Pageant server
• Automatically launches the WSL2 listener (127.0.0.1:10022)
• Uses CNG/KSP directly (no service)
• PIN UI in the current session
• Optional PIN cache (configurable)
• Tray icon with real-time statistics

Compatible with:

• Git for Windows (set SSH_AUTH_SOCK=\\.\pipe\openssh-ssh-agent)
• Visual Studio
• WSL (via npiperelay or socat)
• WSL2 (via TCP 127.0.0.1:10022)
• OpenSSH for Windows
• PuTTY, plink, pscp, psftp (via Pageant)

3. Service stub mode```bash

ssh-agent.exe -install net start SROSSHAgentCNG

- Runs in session 0 (SYSTEM)
- Accepts connections on global pipe
- Creates an internal pipe per client (secured by SID)
- Launches a userland helper with `CreateProcessAsUserW`
- Forwards messages without touching secrets
- Helper pool with 4h timeout (automatic reuse)
- LRU eviction if pool full

**Advantages:**
- UI PIN in user session (not in session 0)
- Compatible with hardened environments
- Strict isolation service ↔ crypto
- Multi-user multiplexing

### 4. Userland crypto helper mode```bash
ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

Launched automatically by the service:

• Connects to internal pipe
• Processes SSH-agent/Pageant requests
• Invokes NCryptSignHash (native PIN UI)
• Returns the signature to the service
• Launches Pageant (hidden window)
• Launches WSL2 listener (127.0.0.1:10022)
• Shows tray icon (SERVICE mode)
• Terminates after timeout or disconnection

---

Installation

Register as PKCS#11 module```bash

regsvr32 ssh-agent.exe

Create the keys:
- `HKLM\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\Mozilla\Firefox\PKCS11Modules\SROSSHAgent`

### Install the Windows service```bash
ssh-agent.exe -install
net start SROSSHAgentCNG

Configure WSL2

Add to ~/.bashrc or ~/.zshrc :```bash

--- Pont SSH Agent Windows (TCP -> Unix Socket) ---

export SSH_AUTH_SOCK="$HOME/.ssh/agent.sock"