zhsm

مكتبة وحدة أمان عتادية (HSM) للغة Zig توفر الوصول عبر PC/SC إلى رموز PIV و CAC و YubiKey.

الحالة

الجانب	المعلومات
استقرار الواجهة البرمجية (API)	قيد التطوير
إصدار Zig	0.16.0
المنصات	لينكس، ماك أو إس، ويندوز
الترخيص	MIT

الميزات

• دعم PIV (NIST SP 800-73-4)

  • استرجاع الشهادة (الفتحات 9A, 9C, 9D, 9E)
  • التحقق من رمز PIN، تغييره، وإلغاء حظره
  • التوقيع باستخدام ECDSA P-256/P-384
  • التوقيع باستخدام RSA 2048/3072/4096
  • فك تشفير RSA

• دعم CAC (بطاقة الوصول الشائعة)

  • بطاقات CAC الحديثة المتوافقة مع PIV (العمليات الكاملة)
  • كشف تطبيق PKI الخاص بـ CAC القديم (اختيار التطبيق فقط)

• دعم YubiKey

  • عمليات تطبيق PIV
  • الكشف القائم على ATR
  • أوامر إدارية اختيارية

• الأمان

  • لا توجد أسرار في السجلات (وضع التصحيح المنقح)
  • تصفير المخازن المؤقتة الحساسة
  • تحليل TLV صارم مع حدود للعمق/الطول
  • أنواع أخطاء دقيقة (لا يوجد anyerror)
  • التحقق من رمز PIN المرتبط بالجلسة (كشف تبديل البطاقة القائم على ATR)

• العمليات المتوازية (عبر thread_pool)

  • توقيع دفعات عبر فتحات متعددة
  • فك تشفير دفعات عبر مفاتيح متعددة
  • اكتشاف الرموز بالتوازي عبر قارئات متعددة
  • استرجاع الشهادات بالتوازي عبر فتحات متعددة
  • الرجوع التلقائي إلى التنفيذ التسلسلي تحت الحد الأدنى (< عنصرين)
  • مفعلة افتراضياً (-Denable_tp=true)؛ يمكن التعطيل بـ -Denable_tp=false

المتطلبات

• Zig 0.16.0 أو متوافق
• مكتبة PC/SC:
  • لينكس: libpcsclite-dev (ديبيان/أوبونتو) أو pcsc-lite-devel (فيدورا)
  • ماك أو إس: PCSC.framework مدمج
  • ويندوز: Winscard.dll مدمج

تثبيت PC/SC على لينكس

# ديبيان/أوبونتو
sudo apt-get install libpcsclite-dev pcscd

# فيدورا/RHEL
sudo dnf install pcsc-lite-devel pcsc-lite

# تشغيل خادم PC/SC
sudo systemctl start pcscd
sudo systemctl enable pcscd

البناء

# بناء وتشغيل اختبارات الوحدة
make

# أو باستخدام zig مباشرة
zig build test

# تشغيل اختبارات تكامل المحاكي
zig build test -Dintegration_sim=true

# بناء الأمثلة (يتطلب تثبيت مكتبة PC/SC)
zig build examples -Dlink_pcsc=true

خيارات البناء

الخيار	الافتراضي	الوصف	التأثير الأمني
integration_sim	false	تشغيل اختبارات تكامل المحاكي	لا شيء
hsm_hil	false	تشغيل اختبارات الحلقة العتادية (يتطلب رمزاً حقيقياً)	لا شيء
link_pcsc	false	ربط مكتبة PC/SC للأمثلة	لا شيء
include_simulator	التصحيح: true الإصدار: false	تضمين محاكي PIV مع مفاتيح اختبار	CWE-321: مفاتيح اختبار في الإنتاج
allow_pcsc_env_override	false	خطر أمني: السماح بمتغير البيئة HSM_PCSC_LIB_PATH	CWE-427: تحميل مكتبة غير موثوقة
fips	false	توجيه التشفير الحساس عبر مزود FIPS-140-3 المرتبط (بدون عبء إضافي عند التعطيل)	لا شيء عند التعطيل
openssl_path	(غير مضبوط)	بادئة تثبيت OpenSSL للتثبيتات غير القياسية (مثل /usr/local/ssl)	لا شيء

وضع FIPS-140-3 / PQC

مع -Dfips=true، يتم توجيه كل عملية تشفير أساسية تتعلق بالأمان عبر مزود FIPS لـ OpenSSL 3.x المُثبت والمُتحقق منه عبر واجهة crypto_backend، ويكتسب المحاكي عمليات رمز PIV ما بعد الكم (توقيع ML-DSA-65، تغليف/فك تغليف ML-KEM-768) المتوفرة فقط في وضع FIPS. العلم معطل افتراضياً بدون أي عبء إضافي؛ يتم حل تبعية fips فقط تحت -Dfips=true.

# البناء الافتراضي — خلفية std.crypto، لا رابط OpenSSL
zig build test

# بناء FIPS — مزود FIPS لـ OpenSSL (قم بتشغيل `make deps` من fips أولاً)
OPENSSL_CONF=/usr/local/ssl/ssl/openssl.cnf \
  zig build test -Dfips=true -Dopenssl_path=/usr/local/ssl

# كلا الوضعين في أمر واحد
make test-dual

انظر docs/FIPS.md لتصميم الواجهة، وسياسة الإعفاء من FIPS، وعمليات رمز PQC.

ملاحظة أمنية: خيار allow_pcsc_env_override معطل افتراضياً لمنع هجمات حقن المكتبات الخبيثة (CWE-427). قم بتمكينه فقط للتطوير/الاختبار:

# بناء الإنتاج (آمن، يتم تجاهل متغير البيئة)
zig build

# بناء التطوير (يسمح بـ HSM_PCSC_LIB_PATH)
zig build -Dallow_pcsc_env_override=true

عند التمكين، يتم التحقق من المكتبات قبل التحميل:

• يجب أن تكون مسارات مطلقة
• لا يمكن أن تكون قابلة للكتابة عالمياً
• يحذر من الملفات القابلة للكتابة بواسطة المجموعة

بداية سريعة

const std = @import("std");
const hsm = @import("hsm");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // سرد الرموز المتاحة
    const tokens = try hsm.listTokens(allocator, false);
    defer {
        for (tokens) |*t| t.deinit();
        allocator.free(tokens);
    }

    if (tokens.len == 0) {
        std.debug.print("لم يتم العثور على أي رموز\n", .{});
        return;
    }

    // فتح الرمز الأول
    var token = try hsm.openToken(allocator, tokens[0].id, .{});
    defer token.close();

    // التحقق من رمز PIN
    try token.verifyPin("123456");

    // قراءة الشهادة
    const cert = try token.getCertificate(.authentication);
    defer allocator.free(cert);
    std.debug.print("الشهادة: {} بايت\n", .{cert.len});

    // توقيع ملخص
    var digest: [32]u8 = undefined;
    std.crypto.hash.sha2.Sha256.hash("Hello, PIV!", &digest, .{});

    const signature = try token.sign(.authentication, .ecdsa_p256, &digest);
    defer allocator.free(signature);
    std.debug.print("التوقيع: {} بايت\n", .{signature.len});
}

نظرة عامة على API

الأنواع

النوع	الوصف
TokenKind	نوع الرمز: .piv, .cac, .yubikey, .unknown
TokenInfo	بيانات وصفية للرمز المكتشف
Token	مقبض رمز مفتوح للعمليات
Slot	فتحة المفتاح: .authentication (9A), .signature (9C), .key_management (9D), .card_auth (9E)
Algorithm	خوارزمية التشفير: .ecdsa_p256, .ecdsa_p384, .rsa2048_pkcs1v15, إلخ.
Capabilities	أعلام قدرات الرمز
PcscScope	نطاق سياق PC/SC: .user (افتراضي), .system

الدوال

الدالة	الوصف
listTokens(allocator, use_sim)	سرد الرموز المتاحة
openToken(allocator, id, opts)	فتح رمز بواسطة المعرف
token.reconnect()	إعادة الاتصال بالرمز وإعادة تعيين حالة المصادقة
token.verifyPin(pin)	التحقق من رمز PIN
token.changePin(old, new)	تغيير رمز PIN
token.unblockPin(puk, new_pin)	إلغاء حظر رمز PIN باستخدام PUK
token.getCertificate(slot)	الحصول على الشهادة بصيغة DER
token.sign(slot, alg, digest)	توقيع ملخص
token.decrypt(slot, alg, ciphertext)	فك تشفير البيانات
token.capabilities()	الحصول على قدرات الرمز
token.close()	إغلاق اتصال الرمز

الأخطاء

جميع العمليات ترجع أخطاء من HsmError:

• PC/SC: PcscUnavailable, ReaderGone, CardRemoved, Timeout
• PIN: PinIncorrect, PinLocked, PinLengthInvalid
• القدرة: NotSupported, SlotNotFound, AlgorithmNotSupported
• البيانات: InvalidTlv, CertificateNotFound, InvalidDigestLength
• الأمان: SecurityConditionNotSatisfied, AuthenticationFailed

وحدة العمليات المتوازية

توفر وحدة parallel عمليات HSM دفعية باستخدام مكتبة thread_pool. تم بناؤها كوحدة Zig منفصلة ومتاحة عندما يكون -Denable_tp=true (الافتراضي). استخدم -Denable_tp=false لإزالة الواجهة بالكامل؛ لا تزال الدوال العامة موجودة وتتراجع إلى تطبيق تسلسلي.

الدالة	الوصف	الحد الأدنى
parallelSign(allocator, inputs, results)	توقيع دفعات عبر فتحات متعددة	عنصران أو أكثر
parallelDecrypt(allocator, inputs, results)	فك تشفير دفعات عبر مفاتيح متعددة	عنصران أو أكثر
parallelTokenDiscover(readers, results)	اكتشاف الرموز عبر قارئات متعددة	قارئان أو أكثر
parallelCertRetrieve(allocator, requests, results)	استرجاع الشهادات عبر فتحات متعددة	طلبان أو أكثر