zhsm

ज़िग के लिए एक हार्डवेयर सुरक्षा मॉड्यूल (HSM) लाइब्रेरी जो PIV, CAC, और YubiKey टोकन तक PC/SC पहुँच प्रदान करती है।

स्थिति

पहलू	जानकारी
API स्थिरता	विकास
Zig संस्करण	0.16.0
प्लेटफ़ॉर्म	Linux, macOS, Windows
लाइसेंस	MIT

विशेषताएँ

• PIV समर्थन (NIST SP 800-73-4)

  • प्रमाणपत्र पुनर्प्राप्ति (स्लॉट 9A, 9C, 9D, 9E)
  • PIN सत्यापन, परिवर्तन और अनब्लॉक
  • ECDSA P-256/P-384 हस्ताक्षर
  • RSA 2048/3072/4096 हस्ताक्षर
  • RSA डिक्रिप्शन

• CAC समर्थन (सामान्य ऍक्सेस कार्ड)

  • आधुनिक PIV-संगत CAC (पूर्ण संचालन)
  • पुराने CAC PKI एप्लेट का पता लगाना (केवल एप्लेट चयन)

• YubiKey समर्थन

  • PIV एप्लेट संचालन
  • ATR-आधारित पहचान
  • वैकल्पिक प्रबंधन कमांड

• सुरक्षा

  • लॉग में कोई गुप्त जानकारी नहीं (रिडैक्टेड डीबग मोड)
  • संवेदनशील बफ़र का शून्यीकरण
  • गहराई/लंबाई सीमाओं के साथ कठोर TLV पार्सिंग
  • तंग त्रुटि प्रकार (कोई anyerror नहीं)
  • सत्र-बाउंड PIN सत्यापन (ATR-आधारित कार्ड स्वैप पहचान)

• समांतर संचालन (thread_pool के माध्यम से)

  • एकाधिक स्लॉट में बैच हस्ताक्षर
  • एकाधिक कुंजियों में बैच डिक्रिप्शन
  • एकाधिक रीडर में समांतर टोकन खोज
  • एकाधिक स्लॉट में समांतर प्रमाणपत्र पुनर्प्राप्ति
  • सीमा से नीचे स्वचालित अनुक्रमिक फ़ॉलबैक (< 2 आइटम)
  • डिफ़ॉल्ट रूप से सक्षम (-Denable_tp=true); -Denable_tp=false से अक्षम करें

आवश्यकताएँ

• Zig 0.16.0 या संगत
• PC/SC लाइब्रेरी:
  • Linux: libpcsclite-dev (Debian/Ubuntu) या pcsc-lite-devel (Fedora)
  • macOS: बिल्ट-इन PCSC.framework
  • Windows: बिल्ट-इन Winscard.dll

Linux पर PC/SC स्थापित करना

# Debian/Ubuntu
sudo apt-get install libpcsclite-dev pcscd

# Fedora/RHEL
sudo dnf install pcsc-lite-devel pcsc-lite

# Start the PC/SC daemon
sudo systemctl start pcscd
sudo systemctl enable pcscd

निर्माण

# Build and run unit tests
make

# Or using zig directly
zig build test

# Run simulator integration tests
zig build test -Dintegration_sim=true

# Build examples (requires PC/SC library installed)
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 के साथ, हर सुरक्षा-प्रासंगिक क्रिप्टोग्राफ़िक प्रिमिटिव crypto_backend सीम के माध्यम से एक लिंक किए गए मान्य OpenSSL 3.x FIPS प्रदाता के माध्यम से रूट होता है, और सिम्युलेटर पोस्ट-क्वांटम PIV टोकन संचालन (ML-DSA-65 हस्ताक्षर, ML-KEM-768 एनकैप/डिकैप) प्राप्त करता है जो केवल FIPS मोड में उपलब्ध हैं। फ़्लैग डिफ़ॉल्ट रूप से बंद होने पर शून्य ओवरहेड रखता है; fips निर्भरता केवल -Dfips=true के तहत हल की जाती है।

# Default build — std.crypto backend, no OpenSSL link
zig build test

# FIPS build — OpenSSL FIPS provider (run `make deps` from fips first)
OPENSSL_CONF=/usr/local/ssl/ssl/openssl.cnf \
  zig build test -Dfips=true -Dopenssl_path=/usr/local/ssl

# Both modes in one shot
make test-dual

सीम डिज़ाइन, fips-छूट नीति और PQC टोकन संचालन के लिए docs/FIPS.md देखें।

सुरक्षा नोट: दुर्भावनापूर्ण लाइब्रेरी इंजेक्शन हमलों (CWE-427) को रोकने के लिए allow_pcsc_env_override विकल्प डिफ़ॉल्ट रूप से अक्षम है। इसे केवल डेवलपमेंट/परीक्षण के लिए सक्षम करें:

# Production build (secure, env var ignored)
zig build

# Development build (allows 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();

    // List available tokens
    const tokens = try hsm.listTokens(allocator, false);
    defer {
        for (tokens) |*t| t.deinit();
        allocator.free(tokens);
    }

    if (tokens.len == 0) {
        std.debug.print("No tokens found\n", .{});
        return;
    }

    // Open the first token
    var token = try hsm.openToken(allocator, tokens[0].id, .{});
    defer token.close();

    // Verify PIN
    try token.verifyPin("123456");

    // Read certificate
    const cert = try token.getCertificate(.authentication);
    defer allocator.free(cert);
    std.debug.print("Certificate: {} bytes\n", .{cert.len});

    // Sign a digest
    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("Signature: {} bytes\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)	एक टोकन को ID द्वारा खोलें
token.reconnect()	टोकन से पुनः कनेक्ट करें और प्रमाणीकरण स्थिति रीसेट करें
token.verifyPin(pin)	PIN सत्यापित करें
token.changePin(old, new)	PIN बदलें
token.unblockPin(puk, new_pin)	PUK के साथ PIN अनब्लॉक करें
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 मॉड्यूल thread_pool लाइब्रेरी का उपयोग करके बैच HSM संचालन प्रदान करता है। यह एक अलग Zig मॉड्यूल के रूप में बनाया गया है और -Denable_tp=true (डिफ़ॉल्ट) होने पर उपलब्ध है। सीम को पूरी तरह से संकलन से बाहर करने के लिए -Denable_tp=false सेट करें; सार्वजनिक फ़ंक्शन अभी भी मौजूद हैं और अनुक्रमिक कार्यान्वयन पर वापस आते हैं।