zhsm

Zig를 위한 하드웨어 보안 모듈(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

# 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	Debug: true Release: 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 제공자로 라우팅되며, 시뮬레이터는 FIPS 모드에서만 사용 가능한 양자 후 PIV 토큰 작업(ML-DSA-65 서명, ML-KEM-768 캡슐화/역캡슐화)을 얻습니다. 이 플래그는 기본적으로 꺼져 있으며 오버헤드가 없습니다. fips 종속성은 -Dfips=true에서만 해결됩니다.

# 기본 빌드 — std.crypto 백엔드, OpenSSL 링크 없음
zig build test

# FIPS 빌드 — OpenSSL FIPS 제공자 (먼저 fips에서 `make deps` 실행)
OPENSSL_CONF=/usr/local/ssl/ssl/openssl.cnf \
  zig build test -Dfips=true -Dopenssl_path=/usr/local/ssl

# 두 모드를 한 번에
make test-dual

시점 설계, FIPS 면제 정책 및 PQC 토큰 작업에 대해서는 docs/FIPS.md를 참조하십시오.

보안 참고: 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();

    // 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로 설정하면 시점을 완전히 컴파일에서 제외합니다. 공개 함수는 여전히 존재하며 순차 구현으로 폴백합니다.

함수	설명	임계값
parallelSign(allocator, inputs, results)	슬롯 간 배치 서명	2개 이상 항목
parallelDecrypt(allocator, inputs, results)	키 간 배치 복호화	2개 이상 항목
parallelTokenDiscover(readers, results)	리더기 간 토큰 검색	2개 이상 리더기
parallelCertRetrieve(allocator, requests, results)	슬롯 간 인증서 검색	2개 이상 요청

임계값 미만에서는 스레드 풀 오버헤드 없이 순차적으로 작업이 실행됩니다. 기본 PKCS#11 호출은 스캐폴딩입니다. src/parallel.zig에서 signData, decryptData, discoverToken, retrieveCert 함수를 구현하여 PKCS#11 백엔드를 통합하십시오.

테스트

단위 테스트

# 모든 단위 테스트 실행
zig build test

시뮬레이터 통합 테스트

라이브러리에는 하드웨어 없이 테스트할 수 있는 PIV 카드 시뮬레이터가 포함되어 있습니다:

# 시뮬레이터 테스트 실행
zig build test -Dintegration_sim=true

시뮬레이터는 내장된 테스트 키를 사용합니다 (src/sim/key_material.zig 참조). 외부 키 파일이나 환경 변수가 필요하지 않습니다.

하드웨어-인-루프(HIL) 테스트

실제 하드웨어로 테스트하려면:

# 읽기 전용 테스트 (인증서 읽기)
HSM_HIL=1 zig build test -Dhsm_hil=true

# PIN이 필요한 테스트
HSM_HIL=1 HSM_PIN=123456 zig build test -Dhsm_hil=true

# 위험한 테스트 (쓰기 작업) - 주의해서 사용
HSM_HIL=1 HSM_PIN=123456 HSM_DANGEROUS=1 zig build test -Dhsm_hil=true

퍼즈 테스트

# 지속적인 퍼징 (수동으로 중지)
zig build test --fuzz -- --test-filter fuzz

예제

# 예제 빌드 (PC/SC 라이브러리 설치 필요)
zig build examples -Dlink_pcsc=true

# 토큰 나열
./zig-out/bin/list_tokens
./zig-out/bin/list_tokens --sim  # 시뮬레이터 사용

# PIV로 서명 (PIN은 대화형 TTY 프롬프트로 입력)
./zig-out/bin/piv_sign
./zig-out/bin/piv_sign --sim

# 또는 환경 변수로 PIN 제공 (덜 안전함)
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를 통해 명시적 재정의가 가능합니다 (절대 경로여야 함).

관찰 가능성