하드웨어 보안 모듈 서명 (PKCS#11)

한눈에 보기

NextPDF Enterprise는 하드웨어 보안 모듈(HSM) 안에 보관된 키로 PDF에 서명합니다. 서명자를 PKCS#11 토큰 — 스마트카드, USB(Universal Serial Bus) 토큰, 또는 네트워크 연결 HSM —에 가리키면 서명 작업이 장치에서 실행됩니다. 개인 키는 결코 토큰 경계를 벗어나지 않습니다. 이 페이지는 동작 수준입니다. 서명자가 무엇을 하는지, 무엇을 제공하는지, 키 보관이 NextPDF의 책임에서 어디서 끝나는지 명시합니다.

HSM 서명자는 Core 서명자 계약을 통해 해석되므로, 귀하의 애플리케이션은 구체적인 Enterprise 타입이 아니라 계약에 의존합니다. Core가 사용하는 동일한 CMS(Cryptographic Message Syntax) 서명 경로를 확장하되, 암호화 작업이 토큰에 위임됩니다.

사전 요구 사항은 프런트 매터에 명시되어 있으며, 작업 중간에 놀라지 않도록 사전 요구 사항에서 반복됩니다.

가용성 및 라이선싱

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 제공되며 Enterprise 등급 라이선스 엔벨로프로 활성화됩니다. 그 자격이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 획득.

NextPDF Core는 키를 인프로세스로 보관하거나 Core 서명 전략 계약을 통해 받아들이는 소프트웨어 CMS 서명자를 제공합니다. NextPDF Pro는 원격 및 클라우드 KMS(key-management-service) 서명 전략을 추가합니다. PKCS#11을 통한 하드웨어 키 보관은 Enterprise 기능이며 Core나 Pro에서 제공되지 않습니다.

이 기능이 하는 일

PKCS#11 토큰은 암호화 객체 — 인증서와 개인 키 —를 벤더 공유 라이브러리 뒤에 노출합니다. Enterprise 서명자는 그 라이브러리를 적응시킵니다.

1. PKCS#11은 모듈이 프로세스당 정확히 한 번 초기화되어야 하므로, 토큰의 공유 라이브러리를 프로세스당 한 번 열고 모듈 핸들을 캐시합니다.
2. 구성된 슬롯에서 세션을 열고 제공된 PIN으로 로그인합니다. 로그인은 어떤 개인 키 작업 이전에 사용자를 인증합니다(PKCS#11 v3.1 §5.6.8).
3. 레이블로 토큰에서 서명 인증서를 찾고, DER(Distinguished Encoding Rules) 형태로 인증서를 읽고, 공개 키 알고리즘을 탐지합니다.
4. 서명 시점에 레이블로 개인 키를 찾고 — 일부 토큰에서는 인증서 레이블과 다를 수 있습니다 — 토큰에 서명 계산을 요청합니다. 서명할 데이터가 전달됩니다. 키는 장치에 남습니다.

서명자는 PKCS#1 v1.5 패딩을 사용하는 RSA(SHA-256, SHA-384, SHA-512), 솔트 길이가 다이제스트 길이와 같은 PSS(Probabilistic Signature Scheme) 패딩을 사용하는 RSA, 그리고 SHA-256, SHA-384, SHA-512를 사용하는 ECDSA(Elliptic Curve Digital Signature Algorithm)를 지원합니다. ECDSA 곡선과 다이제스트는 관례적으로 쌍을 이룹니다 — P-256과 SHA-256, P-384와 SHA-384, P-521과 SHA-512 — RFC 5480의 권장 쌍을 따릅니다. 토큰은 ECDSA 서명을 두 정수의 원시 연결로 반환합니다. 서명자는 이를 PDF와 OpenSSL이 기대하는 DER 인코딩 형태로 변환합니다.

서명 생성의 경우, 최소 2048비트의 RSA 키와 최소 224비트의 ECDSA 곡선 차수가 NIST SP 800-131A Rev.2 §3에 따른 허용 최소값입니다. 토큰 키를 그 크기 이상으로 프로비저닝하십시오.

엔진 기반 토큰을 위한 대체 OpenSSL 엔진 경로가 존재합니다. OpenSSL 3.x에서는 PHP OpenSSL 확장이 엔진 API(application programming interface)를 노출하지 않으므로 엔진 클래스는 더 이상 사용되지 않습니다. 지원되는 엔진 기반 경로는 OpenSSL 명령줄 바이너리를 실행합니다. 토큰에 PKCS#11 라이브러리가 있는 경우 직접 PKCS#11 경로를 선호하십시오.

이렇게 동작하는 이유

핵심적인 결정은 개인 키가 결코 토큰을 벗어나지 않는다는 것입니다. 따라서 서명자는 암호화 작업을 장치에 위임하고 PKCS#11 이음새를 가로질러 서명할 데이터만 옮깁니다. PHP 메모리에서 키 자료를 읽거나 재구성하지 않습니다. 구체적인 Enterprise 타입이 아니라 Core HsmSignerInterface 계약을 통해 해석하므로, 키가 소프트웨어, 클라우드 KMS, 또는 하드웨어 토큰 어디에 있든 서명 코드는 동일합니다. PKCS#11이 각 모듈을 프로세스당 정확히 한 번 초기화하므로 모듈 핸들을 프로세스당 한 번 캐시한 다음, 토큰의 원시 ECDSA 출력을 DER로 변환하여 검증기가 기대하는 인코딩을 보게 합니다. 형태를 결정하는 것은 편의가 아니라 보관입니다. 신뢰 경계는 장치 가장자리에 머뭅니다.

설계 배경: HSM 기반 서명.

사전 요구 사항

HSM으로 서명하기 전에 각 항목을 확인하십시오.

1. NextPDF Core와 Enterprise 패키지를 설치하십시오. composer require nextpdf/core:^3 및 composer require nextpdf/enterprise.
2. 활성 NextPDF Enterprise 라이선스를 보유하십시오. Private Packagist에서 라이선스 자격 증명으로 패키지를 해석하십시오.
3. 호스트에 토큰 벤더의 PKCS#11 공유 라이브러리(예: Linux의 .so 또는 Windows의 .dll)를 설치하고, 그 절대 경로, 슬롯 번호, 객체 레이블을 기록하십시오.
4. ext-pkcs11 PHP 확장을 로드하십시오. 표준 PHP에 번들되어 있지 않으며 별도로 설치해야 합니다. 서명자 생성자는 확장이 없을 때 타입이 지정된 작업 오류를 발생시킵니다.

구성

서명자에 다음 입력을 제공하십시오.

• 라이브러리 경로 — 벤더 PKCS#11 공유 라이브러리의 절대 경로.
• 슬롯 식별자 — 토큰 슬롯 번호, 일반적으로 0.
• PIN — 토큰 PIN. 비밀로 취급하십시오. 소스나 로그가 아니라 비밀 관리자에서 제공하십시오. 서명자는 PIN 매개변수를 민감 항목으로 표시하므로 스택 추적과 직렬화에서 제외됩니다.
• 인증서 레이블 — 토큰의 인증서 객체 레이블.
• 키 레이블 — 인증서 레이블과 다를 때, 개인 키 객체의 레이블.
• 체인 — 토큰이 보유하지 않을 때, DER 형태의 선택적 중간 인증서.

서명자를 구성하기 전에 토큰 가용성을 확인하십시오. 구성은 토큰에서 인증서를 읽으므로, 잘못 구성된 슬롯이나 레이블은 서명 시점이 아니라 타입이 지정된 오류와 함께 빠르게 실패합니다.

단계별 절차

1. 확장 가용성을 확인하여 런타임이 PKCS#11을 지원하는지 확인하십시오. 확장이 없을 때 서명자를 구성하지 마십시오.
2. 비밀 관리자에서 결코 로그에 기록되지 않는 변수로 PIN을 읽으십시오.
3. 라이브러리 경로, 슬롯, PIN, 레이블로 HSM 서명자를 구성하십시오. 구성은 로그인하고 인증서를 읽습니다.
4. HsmSignerInterface를 통해 서명자를 Core 서명 오케스트레이터에 전달하십시오. 오케스트레이터는 바이트 범위를 계산하고, CMS 서명된 속성을 빌드하고, 데이터를 토큰에 넘기고, 서명된 PDF를 조립합니다.
5. 가장 구체적인 실패를 잡고, PIN 없이 구조적 메시지를 로그에 기록하고, 다시 던지십시오.

examples/contracts/hsm-signer-availability.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

프로덕션 배선 — 정확한 생성자 인자 목록과 타입이 지정된 예외 타입 —은 HSM 심층 레퍼런스에 문서화되어 있습니다.

examples/contracts/hsm-sign-guarded.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../../vendor/autoload.php';

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

검증

검증자가 하듯이 결과를 확인하십시오.

1. 서명자에서 서명자 인증서와 체인을 DER 형태로 다시 읽고, 토큰에 프로비저닝된 인증서와 일치하는지 확인하십시오.
2. 귀하의 신뢰 앵커로 구성된 검증기에서 서명된 PDF를 열고 서명이 암호학적으로 온전한 것으로 보고되는지 확인하십시오. 생성된 서명은 검증된 서명이 아닙니다. 신뢰 결정은 생성자가 아니라 검증기와 그 신뢰 앵커의 몫입니다.
3. ECDSA 서명의 경우, 임베드된 서명이 DER 인코딩인지 확인하십시오 — 서명자가 토큰의 원시 출력을 대신 변환하므로, 원시 연결 형태를 거부하는 검증기도 임베드된 서명은 여전히 수락해야 합니다.
4. 어떤 PIN, 토큰 레이블, 또는 키 자료도 애플리케이션 로그에 나타나지 않는지 확인하십시오.

보안 및 규정 준수

• 키는 토큰에 남습니다. 서명할 데이터가 토큰에 넘겨집니다. 서명 작업은 토큰 경계 안에서 실행됩니다. 개인 키는 결코 PHP 메모리에 로드되지 않습니다.
• PIN은 비밀입니다. 민감한 생성자 매개변수이며 로그와 직렬화에서 제외됩니다. 비밀 관리자에서 제공하십시오. 반복된 재인증 실패는 토큰에서 PIN을 잠글 수 있습니다. 그 정책은 NextPDF가 아니라 토큰이 강제합니다.
• 실패-차단. 토큰 또는 HSM 오류는 타입이 지정된 예외를 발생시킵니다. 서명자는 서명되지 않거나 부분적으로 서명된 결과를 생성하지 않으며 결코 더 약한 알고리즘으로 대체하지 않습니다.
• 알고리즘 강도. 서명 생성을 위한 허용 최소값인 최소 2048비트 RSA 키와 최소 224비트 차수의 ECDSA 곡선을 프로비저닝하십시오(NIST SP 800-131A Rev.2 §3).
• 포스트 양자 서명은 실험적이며 기본적으로 꺼져 있습니다. 포스트 양자 경로가 명시적 옵트인 플래그 뒤에 존재합니다. 표준 PAdES(PDF Advanced Electronic Signatures) 장기 아카이브 프로파일은 아직 포스트 양자 스위트를 인식하지 않으며, 대부분의 뷰어는 검증 시 이를 거부합니다. 프로덕션 PAdES 서명에는 활성화하지 마십시오.

이 페이지는 암호화 서명 및 하드웨어 보안 모듈 통합에 관한 것입니다. 모든 규범적 출처는 의역되었으며, 규범 텍스트는 재현하지 않습니다. ### 키 보관 경계

NextPDF Enterprise는 PKCS#11 토큰 또는 HSM과 통합됩니다. 서명 키를 저장, 생성하거나 그 보안을 보장하지 않습니다. 키 보안은 NextPDF Enterprise 단독이 아니라 토큰 또는 HSM, 배포, 그리고 운영자에 달려 있습니다. 토큰 프로비저닝, PIN 처리, 슬롯 구성, 그리고 네트워크 연결 HSM의 네트워크 보호는 귀하의 책임입니다.

실패 처리

• 확장 없음. ext-pkcs11이 로드되지 않았을 때 PKCS#11 서명자를 구성하면 타입이 지정된 작업 예외가 발생합니다. 가용성을 먼저 확인하십시오.
• 레이블로 인증서 또는 키를 찾지 못함. 구성 또는 서명은 누락된 객체를 명명하는 타입이 지정된 예외를 발생시킵니다. 레이블과 슬롯을 확인하십시오.
• 이미 로그인됨. 여러 서명자 인스턴스가 동일한 슬롯에 대해 캐시된 모듈을 공유할 때, 서명자는 로그아웃하고 다시 로그인하여 새로운 PIN 검증을 제공합니다 — “매번 PIN” 정책을 가진 개인 신원 검증(personal-identity-verification) 토큰에 필요합니다.
• 지원되지 않는 알고리즘. 서명자가 매핑하지 않는 알고리즘을 요청하면 대체로 서명하는 대신 인자 오류가 발생합니다.
• 네트워크 HSM 도달 불가. 네트워크 또는 장치 오류는 타입이 지정된 예외를 발생시킵니다. 서명자는 결코 조용히 서명되지 않은 문서를 생성하지 않습니다.

발행 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일 이름, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• HSM signing — reference — PKCS#11 서명자를 위한 심층 레퍼런스.
• Security — NextPDF Enterprise — 통합된 Enterprise 보안 표면.
• Signature — NextPDF Enterprise — PAdES B-LT 및 B-LTA 장기 생산자.
• FIPS 140 cryptographic policy — FIPS 모드 정책 및 자가 테스트 가드.
• Cloud KMS signing — NextPDF Pro — AWS, Azure, GCP key-management-service 전략.
• Security / Signing (Core) — Core CMS 서명자 및 서명 전략 계약.
• HSM · PKCS#11 · CMS · ECDSA — 용어집 항목.