SRO PKCS11 – SSH Agent CNG

Unification souveraine PKCS#11 + SSH-agent + Pageant + CNG/Smartcard

Un exécutable Windows unique qui unifie quatre fonctions traditionnellement séparées :

• Module PKCS#11 complet (Firefox, OpenSC, ssh -I)
• Agent SSH compatible OpenSSH/Git/VS/WSL
• Serveur Pageant compatible PuTTY/plink/pscp
• Orchestrateur CNG/KSP sécurisé pour smartcards

---

Table des matières

1. Philosophie
2. Architecture
3. Modes d'exécution
4. Installation
5. Configuration
6. Protocoles supportés
7. Gestion du PIN
8. Backend CNG
9. Sécurité
10. Compatibilité
11. Export de clés publiques
12. Tray Icon
13. WSL2 Support
14. Détection de conflits
15. Dépendances
16. Limites connues
17. Roadmap

---

Philosophie

Souverain. Aucune dépendance au CRT. Toutes les opérations mémoire passent par RtlCopyMemory, RtlZeroMemory, RtlEqualMemory (FreeCRT.h). Unicode partout (Win32 natif). Aucun malloc, memcpy, strlen, printf.

Sécurisé. Les clés privées ne sont jamais exportées. Aucun PIN ne transite. CNG/KSP gère l'UI PIN native Windows. Isolation stricte service ↔ userland via pipes sécurisés.

Minimaliste. Un seul binaire. Aucune DLL externe. Pas de registry bloat. Installation simple (regsvr32 ou -install).

Polyvalent. Support simultané de PKCS#11, SSH-agent, Pageant, et WSL2 dans le même processus.

---

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)                       │
└──────────────────────────────────────────────────────────────┘

---

Modes d'exécution

1. Mode PKCS#11 (automatique)

Chargé par :

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

Expose les exports PKCS#11 standards :

• 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

Mécanismes supportés (14 au total) :

• CKM_RSA_PKCS (raw avec padding)
• CKM_RSA_X_509 (raw sans 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. Mode agent userland (standalone)

ssh-agent.exe

• Crée le pipe \\.\pipe\openssh-ssh-agent en session utilisateur
• Implémente le protocole SSH-agent
• Support multi-client (max 16 connexions simultanées)
• Lance automatiquement le serveur Pageant
• Lance automatiquement le listener WSL2 (127.0.0.1:10022)
• Utilise CNG/KSP directement (pas de service)
• UI PIN dans la session courante
• Cache PIN optionnel (configurable)
• Tray icon avec statistiques temps réel

Compatible avec :

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

3. Mode service stub

ssh-agent.exe -install
net start SROSSHAgentCNG

• Tourne en session 0 (SYSTEM)
• Accepte les connexions sur pipe global
• Crée un pipe interne par client (sécurisé par SID)
• Lance un helper userland avec CreateProcessAsUserW
• Forwarde les messages sans toucher aux secrets
• Pool de helpers avec timeout 4h (réutilisation automatique)
• Éviction LRU si pool plein

Avantages :

• UI PIN dans la session utilisateur (pas en session 0)
• Compatible environnements durcis
• Isolation stricte service ↔ crypto
• Multiplexage multi-utilisateurs

4. Mode helper crypto userland

ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

Lancé automatiquement par le service :

• Connecte au pipe interne
• Traite les requêtes SSH-agent/Pageant
• Invoque NCryptSignHash (UI PIN native)
• Renvoie la signature au service
• Lance Pageant (fenêtre cachée)
• Lance listener WSL2 (127.0.0.1:10022)
• Affiche tray icon (mode SERVICE)
• Se termine après timeout ou déconnexion

---

Installation

Enregistrer comme module PKCS#11

regsvr32 ssh-agent.exe

Crée les clés :

• HKLM\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent
• HKCU\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent
• HKCU\SOFTWARE\Mozilla\Firefox\PKCS11Modules\SROSSHAgent

Installer le service Windows

ssh-agent.exe -install
net start SROSSHAgentCNG

Configurer WSL2