SRO PKCS11 – SSH Agent CNG

توحيد سيادي PKCS#11 + SSH-agent + Pageant + CNG/Smartcard

ملف تنفيذي واحد لنظام Windows يوحّد أربع وظائف كانت منفصلة تقليديًا:

• وحدة PKCS#11 كاملة (Firefox, OpenSC, ssh -I)
• وكيل SSH متوافق مع OpenSSH/Git/VS/WSL
• خادم Pageant متوافق مع PuTTY/plink/pscp
• منسق CNG/KSP آمن للبطاقات الذكية

---

جدول المحتويات

1. الفلسفة
2. الهندسة
3. أنماط التشغيل
4. التثبيت
5. الإعداد
6. البروتوكولات المدعومة
7. إدارة رمز PIN
8. الخلفية CNG
9. الأمان
10. التوافق
11. تصدير المفاتيح العامة
12. أيقونة الدرج
13. دعم WSL2
14. كشف التعارضات
15. التبعيات
16. القيود المعروفة
17. خريطة الطريق

---

الفلسفة

سيادي. لا اعتماد على CRT. جميع عمليات الذاكرة تمر عبر RtlCopyMemory, RtlZeroMemory, RtlEqualMemory (FreeCRT.h). يونيكود في كل مكان (Win32 أصلي). لا malloc, memcpy, strlen, printf.

آمن. لا يتم تصدير المفاتيح الخاصة أبدًا. لا يمر أي رمز PIN. CNG/KSP تدير واجهة PIN الأصلية لنظام Windows. عزل صارم بين الخدمة ومساحة المستخدم عبر أنابيب (pipes) آمنة.

بسيط. ملف ثنائي واحد. لا مكتبات DLL خارجية. لا تضخم في السجل. تثبيت بسيط (regsvr32 أو -install).

متعدد الاستخدامات. دعم متزامن لـ PKCS#11 و SSH-agent و Pageant و WSL2 في نفس العملية.

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

---

## أوضاع التنفيذ

### 1. وضع PKCS#11 (تلقائي)

يتم التحميل بواسطة:
- `ssh -I ssh-agent.exe user@host`
- Firefox (Security Devices → Load PKCS#11 Module)
- `pkcs11-tool --module ssh-agent.exe --list-objects`

يعرض النواتج القياسية لـ PKCS#11:
- `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`

**الآليات المدعومة (14 إجمالاً):**
- `CKM_RSA_PKCS` (raw مع padding)
- `CKM_RSA_X_509` (raw بدون padding)
- `CKM_SHA1_RSA_PKCS` (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` (قديم)
- `CKM_ECDSA_SHA256` (ecdsa-sha2-nistp256/384/521)
- `CKM_ECDSA_SHA384`
- `CKM_ECDSA_SHA512`

### 2. وضع الوكيل في مساحة المستخدم (مستقل)```bash
ssh-agent.exe

• إنشاء الأنبوب \\.\pipe\openssh-ssh-agent في جلسة المستخدم
• تنفيذ بروتوكول SSH-agent
• دعم متعدد العملاء (حد أقصى 16 اتصالًا متزامنًا)
• تشغيل خادم Pageant تلقائيًا
• تشغيل مستمع WSL2 تلقائيًا (127.0.0.1:10022)
• استخدام CNG/KSP مباشرة (بدون خدمة)
• واجهة PIN في الجلسة الحالية
• تخزين PIN مؤقت اختياري (قابل للتكوين)
• أيقونة شريط المهام مع إحصائيات في الوقت الفعلي

متوافق مع :

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

3. وضع الخدمة الفرعية (stub)```bash

ssh-agent.exe -install net start SROSSHAgentCNG

- يعمل في جلسة 0 (SYSTEM)
- يقبل الاتصالات على أنبوب عمومي (pipe global)
- يُنشئ أنبوبًا داخليًا لكل عميل (مؤمن بواسطة SID)
- يُطلق مساعدًا في وضع المستخدم باستخدام `CreateProcessAsUserW`
- يُمرر الرسائل دون لمس الأسرار
- تجمّع مساعدين مع مهلة 4 ساعات (إعادة استخدام تلقائية)
- إزالة LRU إذا امتلأ التجمّع

**المزايا:**
- إدخال PIN للواجهة في جلسة المستخدم (وليس في الجلسة 0)
- متوافق مع البيئات المُشدّدة
- عزل صارم بين الخدمة والتشفير
- تعدد الإرسال متعدد المستخدمين

### 4. وضع المساعد المشفر في وضع المستخدم (userland)```bash
ssh-agent.exe -useragent -pipe \\.\pipe\ssh-ksp-helper-{GUID}

لانشأ تلقائيًا بواسطة الخدمة:

• يتصل بالقناة الداخلية
• يعالج طلبات SSH-agent/Pageant
• يستدعي NCryptSignHash (واجهة PIN أصلية)
• يعيد التوقيع إلى الخدمة
• يشغل Pageant (نافذة مخفية)
• يشغل مستمع WSL2 (127.0.0.1:10022)
• يعرض أيقونة الدرج (وضع SERVICE)
• ينتهي بعد انتهاء المهلة أو قطع الاتصال

---

تثبيت

التسجيل كوحدة PKCS#11```bash

regsvr32 ssh-agent.exe

أنشئ المفاتيح:
- `HKLM\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\San@sro Inc\PKCS11-SSH-Agent`
- `HKCU\SOFTWARE\Mozilla\Firefox\PKCS11Modules\SROSSHAgent`

### تثبيت خدمة Windows```bash
ssh-agent.exe -install
net start SROSSHAgentCNG

تكوين WSL2

أضف إلى ~/.bashrc أو ~/.zshrc :```bash

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

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