Ký bằng HSM

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

Tổng quan nhanh

Một mô-đun bảo mật phần cứng (HSM) đưa khóa ký ra khỏi tiến trình của bạn và đặt nó sau một thiết bị: thiết bị này ký khi được yêu cầu nhưng không bao giờ trả khóa lại. Trang này giải thích đường ghép PKCS#11 mà NextPDF dùng để ký xuyên qua, chính xác ranh giới khóa nằm ở đâu, và phần nào của kết quả thuộc trách nhiệm của engine, chứ không phải của thiết bị hay của bạn.

Vì sao điều này quan trọng

Một khóa ký nằm trong bộ nhớ tiến trình sẽ bị phơi bày trước mọi thứ có thể đọc được tiến trình đó: một bản kết xuất heap, một trình gỡ lỗi, một lỗi ghi log, hoặc một phụ thuộc có lỗ hổng. Một khi khóa riêng đã bị sao chép, mọi chữ ký mà nó từng tạo ra đều bị đặt nghi vấn, và bạn không thể làm cho nó bí mật trở lại. Điểm mấu chốt của một HSM là không có bản sao nào để lấy.

Xác định sai ranh giới sẽ gây tốn kém một cách âm thầm. Một quy trình trông như được phần cứng hậu thuẫn nhưng lại kéo khóa vào bộ nhớ để ký sẽ mang chi phí vận hành của một HSM, nhưng lại có hồ sơ rủi ro của một khóa phần mềm. Sự khác biệt không hiện ra trong tệp PDF hoàn chỉnh, nên ranh giới đó phải được thiết kế ngay từ đầu và được kiểm chứng, chứ không thể mặc định cho là có.

Phiên bản ngắn gọn

Tiêu chuẩn PKCS#11 định nghĩa một đối tượng khóa được đánh dấu là nhạy cảm và không thể trích xuất. Giá trị riêng của nó không thể được tiết lộ ở dạng văn bản thuần bên ngoài token. Spec: PKCS#11, v3.1 §10.9
NextPDF dựng cấu trúc chữ ký PDF và container CMS. Nó chuyển các byte cần ký qua đường ghép PKCS#11 và nhận lại chữ ký. Khóa không bao giờ vượt qua đường ghép đó.
Đường ghép là một giao ước ổn định. Cùng một giao ước có thể được đáp ứng bởi một token thẻ thông minh, một HSM USB, một HSM mạng, và một dịch vụ KMS đám mây. Mã engine không thay đổi giữa các lựa chọn đó.
NextPDF là phần mềm engine ký. Mức độ đảm bảo phần cứng của thiết bị, trạng thái xác nhận của thiết bị, chính sách PIN, và việc triển khai không phải là những thứ engine chứng nhận. Nó sử dụng thiết bị; nó không bảo chứng cho thiết bị.

Cách NextPDF tiếp cận vấn đề

Đường ghép, chính xác

NextPDF tách việc lắp ráp một chữ ký khỏi việc tính giá trị chữ ký. Phần lắp ráp thuộc về engine: đặt trường chữ ký, dành sẵn chỗ trong tệp, tính dải byte, và dựng SignedData CMS cùng các thuộc tính được ký của nó. Spec: ISO 32000-2, §12.8

Việc tính giá trị chữ ký thì được ủy thác. Engine định nghĩa một giao ước nhà cung cấp ký nhỏ gọn: nó nhận một chuỗi byte mờ đục (trên thực tế là các thuộc tính được ký mã hóa DER), rồi trả về các octet chữ ký thô. Giao ước đó chính là đường ghép. Kiến thức về PDF và CMS nằm ở một phía; khóa nằm ở phía bên kia. Một nhà cung cấp có thể giữ khóa đó trong tiến trình cho một khóa phần mềm cục bộ, trong một KMS đám mây, hoặc trên một token phần cứng thông qua PKCS#11. Mã engine phía trên đường ghép giống hệt nhau trong mọi trường hợp. Chỉ nhà cung cấp phía sau nó là khác.

Nơi ranh giới thực sự nằm

PKCS#11 — Giao diện token mật mã của OASIS, trước đây là “Cryptoki” — là giao diện C tiêu chuẩn cho các token phần cứng. Đường phần cứng của NextPDF giao tiếp PKCS#11 (trực tiếp, hoặc qua một cầu nối dòng lệnh OpenSSL cho các triển khai engine hay nhà cung cấp nơi binding trong tiến trình không thể nạp một token).

Đối tượng khóa trên token được tạo với hai thuộc tính xác định ranh giới. Khi khóa được đánh dấu là nhạy cảm, hoặc được đánh dấu là không thể trích xuất, một số thuộc tính riêng nhất định không thể được tiết lộ ở dạng văn bản thuần bên ngoài token. Spec: PKCS#11, v3.1 §10.9 Bản thân thao tác ký là một lời gọi token duy nhất — C_SignInit rồi C_Sign — do thiết bị thực hiện. Spec: PKCS#11, v3.1 §5.10 Văn bản thuần mà NextPDF xử lý cho thao tác ký là các byte cần ký. Thứ được trả về là chữ ký và chứng chỉ. Khóa riêng không đi qua bất kỳ đường nào. Đó là ranh giới, và token thực thi ranh giới đó, không phải thư viện.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Nơi một chữ ký PDF được phần cứng hậu thuẫn bám rễ, theo thứ tự: vật mang PDF (ISO 32000-2 §12.8), container CMS mà nó chứa, giao diện token mà NextPDF ký xuyên qua (PKCS#11), và các tiêu chuẩn đảm bảo mô-đun mô tả — nhưng tự thân không bảo đảm — thiết bị phía sau nó.

Một mã PIN, một lần tái xác thực

PKCS#11 cho phép một khóa yêu cầu tái xác thực cho từng lần dùng: khi thuộc tính CKA_ALWAYS_AUTHENTICATE được đặt, người dùng phải nhập mã PIN lại cho mỗi thao tác mật mã, chứ không phải một lần cho mỗi phiên. Spec: PKCS#11, v3.1 §10.9 Đường PKCS#11 của NextPDF được viết cho điều này. Mã PIN là một tham số nhạy cảm. Nó không được ghi log hay tuần tự hóa. Khi một phiên báo cáo có một lần đăng nhập sẵn có, NextPDF đưa nó về trạng thái sạch để chữ ký kế tiếp nhận một lần kiểm tra mã PIN mới. Điều này quan trọng đối với các token kiểu PIV có chính sách đòi một mã PIN cho mỗi chữ ký. Đó là hành vi engine tôn trọng chính sách của thiết bị; nó không nới lỏng chính sách ấy.

Bằng chứng nói gì

Evidence: Standard-backed Tính chất khóa-không-thể-trích-xuất không phải là một tuyên bố của NextPDF. Đó là mô hình PKCS#11: một đối tượng khóa mà CKA_SENSITIVE là true hoặc CKA_EXTRACTABLE là false sẽ không cho ra giá trị riêng của nó ở dạng văn bản thuần bên ngoài token. Spec: PKCS#11, v3.1 §10.9 Phần NextPDF đóng góp là không bao giờ cần đến giá trị đó: nó ký xuyên qua thao tác C_Sign của token thay vì đòi vật liệu khóa.

Evidence: Standard-backed Phía PDF được neo trong Spec: ISO 32000-2, §12.8 . Digest của dải byte được tính trên toàn tệp ngoại trừ giá trị chữ ký. Giá trị chữ ký đặt trong mục Contents là một đối tượng SignedData CMS mã hóa DER cho các chữ ký khóa công khai. HSM chỉ tạo ra những octet chữ ký trong cùng nhất. NextPDF dựng mọi thứ xung quanh chúng và viết chúng vào cấu trúc mà tiêu chuẩn định nghĩa.

Evidence: Standard-backed Mức độ đảm bảo của thiết bị được mô tả bởi Spec: FIPS 140-3 và tiêu chuẩn nền của nó là ISO/IEC 19790, vốn định nghĩa bốn cấp độ bảo mật định tính tăng dần trên mười một nhóm yêu cầu — từ đặc tả thuật toán đến bằng chứng chống giả mạo vật lý. Các tiêu chuẩn này mô tả những gì một mô-đun phải thỏa mãn để tuyên bố một cấp độ. Chúng là một tính chất của thiết bị và việc xác nhận thiết bị đó, không phải của NextPDF, và — theo lời của chính ISO/IEC 19790 — sự tuân thủ tự thân không đủ để bảo đảm một mô-đun là an toàn trong một triển khai nhất định.

Ví dụ thực tế

Hình thái dưới đây chỉ mang tính minh họa. Nó cho thấy đường ghép, không phải một bản triển khai sao-chép-và-dán. Điểm mấu chốt là engine được trao một bộ ký và không bao giờ thấy khóa: hàm sign() của bộ ký là một lời gọi vào thiết bị.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Hai ghi chú trung thực về hình thái này. Binding PKCS#11 trong tiến trình là một extension PHP riêng mà các bản dựng PHP tiêu chuẩn không bao gồm. Một triển khai phần cứng sẽ cài đặt và kiểm chứng nó (hoặc dùng cầu nối dòng lệnh OpenSSL) như một phần của nền tảng, chứ không xem đó là việc nghĩ tới sau. Và thuật toán được yêu cầu từ thiết bị phải là thuật toán mà khóa thực sự có thể thực hiện. Engine từ chối sớm khi thuật toán được cấu hình không có ánh xạ cho nhà cung cấp đã chọn, thay vì hỏng sâu trong một lời gọi token.

Hiểu lầm phổ biến

“Dùng một HSM nghĩa là việc ký được xác nhận FIPS.”

Không. Nhầm lẫn hai điều này chính là cái bẫy. Một HSM là nơi khóa cư trú và thao tác chạy. Việc xác nhận FIPS 140-3 / ISO/IEC 19790 là một tính chất mà thiết bị (hoặc một cấu hình mô-đun cụ thể) có thể có, được thiết lập bởi một chương trình xác nhận — chứ không phải thứ mà một thư viện gọi đến có thể trao cho, và cũng không phải thứ mà NextPDF khẳng định thay cho thiết bị. NextPDF tương thích với việc ký xuyên qua một thiết bị PKCS#11 và đường ký của nó đã được thử nghiệm với các token đại diện theo danh mục. Việc một triển khai nhất định có được xác nhận ở mức mô-đun FIPS hay không phụ thuộc hoàn toàn vào phần cứng, chứng chỉ của nó, và cách nó được cấu hình cũng như vận hành. Hãy dùng từ chính xác cho những gì bạn thực sự có.

Giới hạn và ranh giới

Trang này mô tả đường ghép và các tiêu chuẩn mà nó dựa trên. Nó không phải là một bảo đảm về việc triển khai, và ranh giới cần được nói thẳng:

Trách nhiệm của engine. Dựng trường chữ ký, dành sẵn chỗ, tính dải byte, lắp ráp SignedData CMS, gọi nhà cung cấp ký, và viết một chữ ký đúng về cấu trúc theo Spec: ISO 32000-2, §12.8 . Đường phần cứng của NextPDF tuân thủ giao diện ký PKCS#11 cho mục đích này.
Trách nhiệm của thiết bị và người vận hành. Khả năng chống giả mạo của phần cứng, trạng thái xác nhận FIPS 140-3 / ISO/IEC 19790 của thiết bị, việc sinh và lưu giữ khóa, chính sách PIN, cấu hình khe cắm, firmware, và bảo mật vật lý. Không điều nào trong số này là thứ engine chứng nhận.
Đã-thử-nghiệm-với không phải là đã-chứng-nhận. Việc NextPDF có một đường đã được kiểm chứng đối với các danh mục token đại diện — các hình thái thẻ thông minh, USB, mạng, và KMS đám mây tiếp cận qua cùng một giao ước PKCS#11 — là một phát biểu về tính tương thích. Đó không phải là một sự chứng nhận, một số hiệu mô-đun đã được xác nhận, hay một tuyên bố về thiết bị cụ thể của bạn. Các danh mục phần cứng dưới đây là những hình thái tích hợp thông qua một giao diện tiêu chuẩn. Hãy xem chúng là “nơi đường ghép đã được thử nghiệm”, không bao giờ là một bảo đảm cho một mẫu mà chính bạn chưa thử nghiệm.
Ký hậu lượng tử là thử nghiệm. Nơi engine phơi bày việc ký hậu lượng tử thông qua một token, năng lực đó là tùy chọn, được kiểm soát, và được kiểm chứng đối với các mock chứ không phải firmware HSM hậu lượng tử. Các danh mục bộ thuật toán mật mã PAdES và AdES chưa công nhận những bộ đó cho lưu trữ dài hạn. Đừng coi nó là đã sẵn sàng cho môi trường sản xuất.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Không có trong ấn bản này. Core cung cấp engine ký và đường ghép nhà cung cấp ký, cùng một nhà cung cấp khóa phần mềm cục bộ.
Pro	Quản lý khóa đám mây — ký xuyên qua các khóa KMS được quản lý — là một năng lực Pro, chỉ được mô tả ở mức hành vi.
Enterprise	Có sẵn. Ký bằng token phần cứng thông qua giao diện PKCS#11 (và một cầu nối dòng lệnh OpenSSL cho các triển khai engine/provider) là một năng lực Enterprise. Tính sẵn có là một phát biểu về năng lực, không phải một sự chứng nhận cho bất kỳ thiết bị hay triển khai nào.

Các hình thái tích hợp thông qua một giao diện

Đây là những hình thái mà đường ghép PKCS#11 đã được thử nghiệm với. Cột này cho biết “việc tích hợp trông như thế nào”, không phải “một danh sách thiết bị đã được xác nhận, chứng nhận hay đếm số”.

Hình thái tích hợp	Cách tiếp cận nó	Ranh giới khóa	Mức đảm bảo là tính chất của
Token thẻ thông minh / PIV	PKCS#11 ở dạng mô-đun; PIN mỗi lần dùng là phổ biến	Trên thẻ; không thể trích xuất	Thẻ và người vận hành nó
HSM USB	PKCS#11 ở dạng mô-đun	Trên thiết bị; không thể trích xuất	Thiết bị và người vận hành nó
HSM mạng / thiết bị chuyên dụng	PKCS#11 ở dạng mô-đun tới một thiết bị mạng	Trên thiết bị chuyên dụng; không thể trích xuất	Thiết bị chuyên dụng, cấu hình của nó, người vận hành
KMS đám mây	Nhà cung cấp khóa được quản lý (Pro)	Trong dịch vụ đám mây; không bao giờ được trả về	Nhà cung cấp đám mây và các chứng thực của nó
Cầu nối nhà cung cấp OpenSSL	PKCS#11 qua một cầu nối OpenSSL	Trên token; không thể trích xuất	Token và người vận hành nó

Mini-FAQ

Khóa có bao giờ đi vào tiến trình PHP không? Không. Đối với một khóa PKCS#11 không thể trích xuất, giá trị riêng không thể được tiết lộ ở dạng văn bản thuần bên ngoài token. NextPDF ký xuyên qua thao tác của token và chỉ bao giờ thấy các byte cần ký và chữ ký được trả về.

Một chữ ký được HSM hậu thuẫn có khác bên trong tệp PDF không? Không. Cấu trúc chữ ký vẫn là cùng một SignedData CMS trong cùng mục Contents trên cùng dải byte. HSM thay đổi nơi việc ký diễn ra, không thay đổi hình thái trên đĩa.

Tôi có thể tuyên bố tuân thủ FIPS vì đã dùng một HSM thông qua NextPDF không? Chỉ với sự thận trọng. NextPDF không khẳng định gì về trạng thái FIPS của một thiết bị. Bất kỳ tuyên bố nào như vậy phải đến từ việc xác nhận của chính thiết bị và cách nó được triển khai, không phải từ việc NextPDF đã gọi đến nó.

Nếu binding PKCS#11 trong tiến trình không khả dụng thì sao? Engine báo cáo rằng việc ký bằng phần cứng không khả dụng thay vì lặng lẽ quay về một khóa phần mềm. Có một đường cầu nối dòng lệnh OpenSSL cho các triển khai nơi binding trong tiến trình không thể nạp một token.

Tài liệu liên quan

Giải thích về chữ ký đủ điều kiện — khóa phần cứng cần thiết nhưng chưa đủ cho điều gì, và những vai trò mà NextPDF không đảm nhận.
Cách các chữ ký nằm trong một tệp PDF — cơ chế dải byte và từ điển chữ ký mà kết quả HSM được viết vào.
Vận hành NextPDF trong môi trường sản xuất — bề mặt vận hành mà một việc triển khai ký bằng phần cứng phải đảm nhận.

Bảng thuật ngữ

HSM (mô-đun bảo mật phần cứng) — một thiết bị được gia cố để giữ các khóa và thực hiện các thao tác mật mã sao cho vật liệu khóa không bao giờ rời khỏi nó.
PKCS#11 — tiêu chuẩn Giao diện token mật mã của OASIS (trước đây là “Cryptoki”); giao diện C mà NextPDF dùng để giao tiếp với các token phần cứng.
Khóa không thể trích xuất — một đối tượng khóa PKCS#11 mà giá trị riêng của nó không thể được tiết lộ ở dạng văn bản thuần bên ngoài token (CKA_SENSITIVE là true hoặc CKA_EXTRACTABLE là false).
Đường ghép — ranh giới nhà cung cấp ký trong NextPDF: byte mờ đục đi vào, octet chữ ký đi ra. Kiến thức về PDF và CMS ở phía trên nó; khóa ở phía sau nó.
CMS SignedData — cấu trúc Cú pháp thông điệp mật mã (RFC 5652) mang chữ ký và các chứng chỉ bên trong tệp PDF.
FIPS 140-3 / ISO/IEC 19790 — các tiêu chuẩn bảo mật mô-đun mật mã định nghĩa bốn cấp độ định tính; một tính chất của thiết bị và việc xác nhận thiết bị đó, không phải của một thư viện gọi đến.