devnw/zig/hsmZig Hardware Security Module Bibliothek für PIV-, CAC- und YubiKey-Token über PC/SC. Unterstützt Zertifikate, PIN-Verwaltung, Signieren und Entschlüsselung.
Eine Hardware Security Module (HSM)-Bibliothek für Zig mit PC/SC-Zugriff auf PIV-, CAC- und YubiKey-Token.
| Aspekt | Info |
|---|---|
| API-Stabilität | Entwicklung |
| Zig-Version | 0.16.0 |
| Plattformen | Linux, macOS, Windows |
| Lizenz | MIT |
PIV-Unterstützung (NIST SP 800-73-4)
CAC-Unterstützung (Common Access Card)
YubiKey-Unterstützung
Sicherheit
anyerror)Parallele Operationen (über thread_pool)
-Denable_tp=true); deaktivieren mit -Denable_tp=falselibpcsclite-dev (Debian/Ubuntu) oder pcsc-lite-devel (Fedora)# Debian/Ubuntu
sudo apt-get install libpcsclite-dev pcscd
# Fedora/RHEL
sudo dnf install pcsc-lite-devel pcsc-lite
# PC/SC-Daemon starten
sudo systemctl start pcscd
sudo systemctl enable pcscd
# Unit-Tests bauen und ausführen
make
# Oder direkt mit Zig
zig build test
# Simulator-Integrationstests ausführen
zig build test -Dintegration_sim=true
# Beispiele bauen (PC/SC-Bibliothek muss installiert sein)
zig build examples -Dlink_pcsc=true
| Option | Standard | Beschreibung | Sicherheitsauswirkung |
|---|---|---|---|
integration_sim | false | Simulator-Integrationstests ausführen | Keine |
hsm_hil | false | Hardware-in-Loop-Tests ausführen (echter Token erforderlich) | Keine |
link_pcsc | false | PC/SC-Bibliothek für Beispiele linken | Keine |
include_simulator | Debug: trueRelease: false | PIV-Simulator mit Testschlüsseln einbinden | CWE-321: Testschlüssel in Produktion |
allow_pcsc_env_override | false | SICHERHEITSRISIKO: Umgebungsvariable HSM_PCSC_LIB_PATH erlauben | CWE-427: Laden nicht vertrauenswürdiger Bibliotheken |
fips | false | Sicherheitskryptografie über den gelinkten FIPS-140-3-Provider leiten (kein Overhead, wenn ausgeschaltet) | Keine, wenn ausgeschaltet |
openssl_path | (nicht gesetzt) | OpenSSL-Installationspräfix für nicht-standardmäßige Installationen (z. B. /usr/local/ssl) | Keine |
Mit -Dfips=true wird jede sicherheitsrelevante kryptografische Primitive
über einen gelinkten, validierten OpenSSL 3.x FIPS-Provider via der
crypto_backend-Naht geleitet, und der Simulator erhält Post-Quantum-PIV-Token-
Operationen (ML-DSA-65-Signierung, ML-KEM-768-Verkapselung/Entkapselung), die
nur im FIPS-Modus verfügbar sind. Das Flag ist standardmäßig ausgeschaltet,
ohne Overhead; die fips-Abhängigkeit wird nur unter -Dfips=true aufgelöst.
# Standard-Build — std.crypto-Backend, kein OpenSSL-Link
zig build test
# FIPS-Build — OpenSSL FIPS-Provider (zuerst `make deps` aus fips ausführen)
OPENSSL_CONF=/usr/local/ssl/ssl/openssl.cnf \
zig build test -Dfips=true -Dopenssl_path=/usr/local/ssl
# Beide Modi auf einmal
make test-dual
Siehe docs/FIPS.md für das Naht-Design, die
FIPS-Ausnahmerichtlinie und die PQC-Token-Operationen.
Sicherheitshinweis: Die Option allow_pcsc_env_override ist standardmäßig deaktiviert, um bösartige Bibliotheksinjektionsangriffe zu verhindern (CWE-427). Nur für Entwicklung/Tests aktivieren:
# Produktions-Build (sicher, Umgebungsvariable wird ignoriert)
zig build
# Entwicklungs-Build (erlaubt HSM_PCSC_LIB_PATH)
zig build -Dallow_pcsc_env_override=true
Wenn aktiviert, werden Bibliotheken vor dem Laden validiert:
const std = @import("std");
const hsm = @import("hsm");
pub fn main() !void {
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer _ = gpa.deinit();
const allocator = gpa.allocator();
// Verfügbare Token auflisten
const tokens = try hsm.listTokens(allocator, false);
defer {
for (tokens) |*t| t.deinit();
allocator.free(tokens);
}
if (tokens.len == 0) {
std.debug.print("Keine Token gefunden\n", .{});
return;
}
// Ersten Token öffnen
var token = try hsm.openToken(allocator, tokens[0].id, .{});
defer token.close();
// PIN verifizieren
try token.verifyPin("123456");
// Zertifikat lesen
const cert = try token.getCertificate(.authentication);
defer allocator.free(cert);
std.debug.print("Zertifikat: {} Bytes\n", .{cert.len});
// Digest signieren
var digest: [32]u8 = undefined;
std.crypto.hash.sha2.Sha256.hash("Hallo, PIV!", &digest, .{});
const signature = try token.sign(.authentication, .ecdsa_p256, &digest);
defer allocator.free(signature);
std.debug.print("Signatur: {} Bytes\n", .{signature.len});
}
| Typ | Beschreibung |
|---|---|
TokenKind | Token-Typ: .piv, .cac, .yubikey, .unknown |
TokenInfo | Metadaten eines erkannten Tokens |
Token | Offener Token-Handle für Operationen |
Slot | Schlüsselslot: .authentication (9A), .signature (9C), .key_management (9D), .card_auth (9E) |
Algorithm | Krypto-Algorithmus: .ecdsa_p256, .ecdsa_p384, .rsa2048_pkcs1v15, etc. |
Capabilities | Flags für Token-Fähigkeiten |
PcscScope | PC/SC-Kontextbereich: .user (Standard), .system |
| Funktion | Beschreibung |
|---|---|
listTokens(allocator, use_sim) | Verfügbare Token auflisten |
openToken(allocator, id, opts) | Token per ID öffnen |
token.reconnect() | Neu verbinden und Authentifizierungszustand zurücksetzen |
token.verifyPin(pin) | PIN verifizieren |
token.changePin(old, new) | PIN ändern |
token.unblockPin(puk, new_pin) | PIN mit PUK entsperren |
token.getCertificate(slot) | DER-kodiertes Zertifikat abrufen |
token.sign(slot, alg, digest) | Digest signieren |
token.decrypt(slot, alg, ciphertext) | Daten entschlüsseln |
token.capabilities() | Token-Fähigkeiten abrufen |
token.close() | Token-Verbindung schließen |
Alle Operationen geben Fehler von HsmError zurück:
PcscUnavailable, ReaderGone, CardRemoved, TimeoutPinIncorrect, PinLocked, PinLengthInvalidNotSupported, SlotNotFound, AlgorithmNotSupportedInvalidTlv, CertificateNotFound, InvalidDigestLengthSecurityConditionNotSatisfied, AuthenticationFailed