zhsm

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

स्थिति

विशेषताएँ

• 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

निर्माण विकल्प

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 अवलोकन

प्रकार

फ़ंक्शन

त्रुटियाँ

सभी संचालन HsmError से त्रुटियाँ लौटाते हैं:

• PC/SC: PcscUnavailable, ReaderGone, CardRemoved, Timeout
• PIN: PinIncorrect, PinLocked, PinLengthInvalid
• क्षमता: NotSupported, SlotNotFound, AlgorithmNotSupported
• डेटा: InvalidTlv, CertificateNotFound, InvalidDigestLength
• सुरक्षा: SecurityConditionNotSatisfied,

समांतर संचालन मॉड्यूल

parallel मॉड्यूल thread_pool लाइब्रेरी का उपयोग करके बैच HSM संचालन प्रदान करता है। यह एक अलग Zig मॉड्यूल के रूप में बनाया गया है और -Denable_tp=true (डिफ़ॉल्ट) होने पर उपलब्ध है। सीम को पूरी तरह से संकलन से बाहर करने के लिए -Denable_tp=false सेट करें; सार्वजनिक फ़ंक्शन अभी भी मौजूद हैं और अनुक्रमिक कार्यान्वयन पर वापस आते हैं।

थ्रेशोल्ड के नीचे, संचालन थ्रेड पूल ओवरहेड के बिना अनुक्रमिक रूप से निष्पादित होते हैं। अंतर्निहित PKCS#11 कॉल स्कैफोल्डिंग हैं; src/parallel.zig में signData, decryptData, discoverToken, और retrieveCert फ़ंक्शन लागू करके अपना PKCS#11 बैकएंड एकीकृत करें।

परीक्षण

यूनिट परीक्षण

# Run all unit tests
zig build test

सिम्युलेटर एकीकरण परीक्षण

लाइब्रेरी में हार्डवेयर के बिना परीक्षण के लिए एक PIV कार्ड सिम्युलेटर शामिल है:

# Run simulator tests
zig build test -Dintegration_sim=true

सिम्युलेटर एम्बेडेड परीक्षण कुंजियों का उपयोग करता है (src/sim/key_material.zig देखें)। किसी बाहरी कुंजी फ़ाइल या पर्यावरण चर की आवश्यकता नहीं है।

हार्डवेयर-इन-लूप (HIL) परीक्षण

वास्तविक हार्डवेयर के साथ परीक्षण के लिए:

# Read-only tests (certificate reading)
HSM_HIL=1 zig build test -Dhsm_hil=true

# Tests requiring PIN
HSM_HIL=1 HSM_PIN=123456 zig build test -Dhsm_hil=true

# Dangerous tests (write operations) - USE WITH CAUTION
HSM_HIL=1 HSM_PIN=123456 HSM_DANGEROUS=1 zig build test -Dhsm_hil=true

फ़ज़ परीक्षण

# Continuous fuzzing (stop manually)
zig build test --fuzz -- --test-filter fuzz

उदाहरण

# Build examples (requires PC/SC library installed)
zig build examples -Dlink_pcsc=true

# List tokens
./zig-out/bin/list_tokens
./zig-out/bin/list_tokens --sim  # Use simulator

# Sign with PIV (PIN entered via interactive TTY prompt)
./zig-out/bin/piv_sign
./zig-out/bin/piv_sign --sim

# Or supply PIN via environment variable (less secure)
HSM_PIN=123456 ./zig-out/bin/piv_sign --sim

सुरक्षा नोट्स

1. PIN प्रबंधन: PIN को कभी भी टोकन संरचनाओं में संग्रहीत नहीं किया जाता है और उपयोग के बाद शून्य कर दिया जाता है।

2. TLV पार्सिंग: सभी TLV पार्सिंग में संसाधन थकावट को रोकने के लिए गहराई (10) और लंबाई (64KB) की सीमाएँ होती हैं।

3. त्रुटि प्रबंधन: अज्ञात स्थिति शब्दों के परिणामस्वरूप स्पष्ट त्रुटियाँ होती हैं, मौन विफलताएँ नहीं।

4. लॉगिंग: डीबग लॉगिंग में कभी भी संवेदनशील डेटा (PIN, कुंजियाँ, आदि) शामिल नहीं होता।

5. मेमोरी: संवेदनशील बफ़र को hsm.zeroize() का उपयोग करके शून्य किया जाता है जो कंपाइलर ऑप्टिमाइज़ेशन को रोकता है।

6. PC/SC लाइब्रेरी लोडिंग: लाइब्रेरी PC/SC को विश्वसनीय पूर्ण पथों से लोड करती है। HSM_PCSC_LIB_PATH के माध्यम से एक स्पष्ट ओवरराइड उपलब्ध है (पूर्ण पथ होना चाहिए)।

अवलोकनीयता

hsm HSM संचालनों के स्पैन ट्रेसिंग के लिए एक ऑप्ट-इन OpenTelemetry सीम शिप करता है। सीम डिफ़ॉल्ट रूप से बंद है और बंद होने पर शून्य ओवरहेड उत्पन्न करता है — बिल्ड कभी भी otel निर्भरता को हल नहीं करता, हर हेल्पर एक comptime-ज्ञात नो-ऑप में संकलित होता है, और उत्पादित आर्टिफैक्ट में कोई otel या observability लिंक किए गए प्रतीक नहीं होते।

सक्षम करना

zig build test                  # default: -Dwith_otel=false (no-op)
zig build test -Dwith_otel=true # opt in: spans emitted

जब सक्षम हो, तो हर सार्वजनिक Token.sign / Token.decrypt कॉल दो विशेषताओं के साथ एक hsm.{operation} स्पैन (जैसे hsm.sign, hsm.decrypt) उत्सर्जित करता है:

• crypto.algorithm — एल्गोरिदम टैग (जैसे ecdsa_p256, rsa2048_pkcs1v15)।
• crypto.key.id — स्लॉट पहचानकर्ता (जैसे authentication, signature, key_management, card_auth)।

सुरक्षा अनुबंध

सीम एक नियम के आसपास इंजीनियर किया गया है: क्रिप्टोग्राफ़िक सामग्री कभी निर्यात न करें। स्पैन विशेषताएँ ऑफ-होस्ट निर्यात की जाती हैं (आमतौर पर OTLP कलेक्टर को) और ट्रेस/लॉग में समाप्त होती हैं जिनमें HSM संचालन की तुलना में कमज़ोर एक्सेस नियंत्रण हो सकते हैं।

• निजी कुंजी बाइट्स, प्लेनटेक्स्ट, सिफरटेक्स्ट, हस्ताक्षर, डाइजेस्ट और PIN कभी भी इस लाइब्रेरी द्वारा स्पैन से जुड़े नहीं होते।
• केवल संचालन प्रकार, स्लॉट पहचानकर्ता और एल्गोरिदम नाम टेलीमेट्री के माध्यम से प्रक्रिया छोड़ते हैं।
• यदि आपके एप्लिकेशन के स्लॉट पहचानकर्ता स्वयं संवेदनशील हैं (जैसे उपयोगकर्ता पहचान से सहसंबद्ध), तो hsm.observability.startHsmOperationSpan में पास करने से पहले उन्हें रिडैक्ट या हैश करें।

प्रक्रिया बूटस्ट्रैप

const hsm = @import("hsm");

pub fn main() !void {
    // Park the Otel value on a stable address — either a `var` in
    // main()'s stack frame for the process lifetime, or a heap
    // allocation. The init helper is only present when
    // `-Dwith_otel=true`; under the disabled build,
    // hsm.observability_init resolves to an empty struct and this
    // block compiles to a no-op.
    if (comptime hsm.observability.enabled) {
        var otel = try hsm.observability_init.Otel.init(allocator, "my-service");
        defer otel.deinit();
        otel.installGlobals();
    }
    // ... rest of main, including any hsm.Token.sign calls — each one
    // now emits an `hsm.sign` span attached to your service.
}

सीम OpenTelemetry पर्यावरण-चर विनिर्देश के अनुसार OTEL_* पर्यावरण चर (सैंपलर, एक्सपोर्टर एंडपॉइंट, service.name, आदि) पढ़ता है। डिफ़ॉल्ट: 5% पर parentbased_traceidratio सैंपलर, http://localhost:4318 पर OTLP/HTTP-protobuf एक्सपोर्टर।

रेसिपी + सत्यापन

पूर्ण एकीकरण रेसिपी (बिल्ड वायरिंग, टेस्ट हार्नेस, नो-ऑप वेरिफायर) otel रोलआउट रेपो में प्रलेखित है: otel/docs/integration/RECIPE.md।

सीम को छूने वाले परिवर्तनों को मर्ज करने से पहले तीन गेट पास होने चाहिए:

zig build test                                 # default flag = false
zig build test -Dwith_otel=true                # flag on
scripts/verify-consumer-noop.sh                # symbol-leak check

verify-consumer-noop.sh गेट -Dwith_otel=false के साथ लाइब्रेरी बनाता है और nm --defined-only के साथ zig-out/ को स्कैन करता है, यदि कोई otel/observability प्रतीक आर्टिफैक्ट में बच गया तो विफल हो जाता है। यह क्रॉस-रेपो otel/scripts/verify-consumer-noop.sh (जो केवल सहोदर-रेपो लेआउट <root>/otel//<root>/hsm/ में चलता है) को मिरर करता है ताकि उस लेआउट के बिना योगदानकर्ता भी स्थानीय रूप से सीम को गेट कर सकें।

परियोजना संरचना

src/
├── hsm.zig              # Main API and types
├── root.zig             # Module entry point
├── apdu.zig             # APDU encoding/decoding
├── tlv.zig              # BER-TLV parsing
├── parallel.zig         # Parallel operations (thread_pool)
├── pcsc/
│   └── pcsc.zig         # PC/SC transport layer (Linux/macOS/Windows)
├── piv/
│   └── piv.zig          # PIV implementation
├── cac/
│   └── cac.zig          # CAC implementation
├── yubikey/
│   └── yubikey.zig      # YubiKey detection
└── sim/
    ├── sim.zig          # Simulator entry point
    ├── transport.zig    # Simulated transport
    ├── piv_card.zig     # Simulated PIV card
    └── key_material.zig # Embedded test keys

tests/
├── integration.zig      # Basic integration tests
├── sim_integration.zig  # Simulator integration tests
└── hil_tests.zig        # Hardware-in-loop tests

examples/
├── list_tokens.zig      # Token discovery example
└── piv_sign.zig         # Signing example

संदर्भ

• NIST SP 800-73-4 - PIV विनिर्देश
• FIPS 201-3 - PIV मानक
• PC/SC Workgroup - PC/SC विनिर्देश
• Yubico PIV Tool - YubiKey PIV दस्तावेज़ीकरण

योगदान

दिशानिर्देशों के लिए CONTRIBUTING.md देखें।

लाइसेंस

MIT लाइसेंस - विवरण के लिए LICENSE देखें।

Zig 0.16.0 के साथ बनाया गया | PIV | CAC | YubiKey | PC/SC