Enterprise phiên bảnđộ ổn định: Thử nghiệm

Trạng thái năng lực xem trước ký hậu lượng tử qua HSM (PQS)

Tổng quan nhanh

Trạng thái năng lực xem trước. Opt-in, mặc định tắt, fail-closed. Đây là một bản xem trước của việc ký hậu lượng tử ủy quyền cho HSM. Nó không khả dụng rộng rãi, nó không tuân thủ AdES, nó không phải FIPS-validated, và nó không đưa ra tuyên bố chứng nhận hay tuân thủ nào. Bản xem trước tắt cho tới khi bạn opt-in; khi tắt, lệnh gọi ký fail closed với một ngoại lệ có kiểu.

NextPDF Enterprise phơi bày một bề mặt chữ ký hậu lượng tử (PQS) thử nghiệm vốn điều khiển việc ký ML-DSA (FIPS 204) và SLH-DSA (FIPS 205) qua một token phần cứng PKCS#11. Đường đi là Pkcs11Signer::signPqs(), được kiểm soát đằng sau một opt-in tường minh theo từng bộ ký ($enablePostQuantum) và, tách biệt, đằng sau một cờ env cấp tiến trình (NEXTPDF_FEATURE_PREVIEW_PQS_HSM). Cả hai đều tắt theo mặc định.

Trang này là ranh giới trung thực. Nó nêu rõ bản xem trước làm gì — nó ủy quyền một thao tác ký hậu lượng tử thật cho token — và, với sự trung thực ngang bằng, nó không phải gì: nó không phải GA, không phải AdES, không phải FIPS-validated, và không phải một tuyên bố tuân thủ đối với FIPS, OASIS, hay ETSI. Các tiêu chuẩn vốn sẽ làm cho một chữ ký PDF hậu lượng tử tương tác được cho lưu trữ dài hạn vẫn chưa ra đời (xem Ranh giới tiêu chuẩn).

Phiên bản và cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt với một phong bì giấy phép hạng Enterprise. Một triển khai không có quyền sử dụng đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Nó dựng trên bộ ký token phần cứng PKCS#11 của Enterprise — xem Ký qua HSM. Đường ký PKCS#11 cổ điển (RSA / ECDSA) là năng lực Enterprise được hỗ trợ, ổn định; đường hậu lượng tử mô tả ở đây là một bản xem trước thử nghiệm xếp chồng lên trên nó. NextPDF Enterprise bao gồm bộ tính năng Pro.

Trạng thái năng lực xem trước

Bản xem trước điều khiển một thao tác ký đích thực: khi được bật, signPqs() phân phối tới cơ chế hậu lượng tử PKCS#11 v3.1 ứng viên trên token, khóa riêng không bao giờ rời khỏi ranh giới token, và các byte trả về được kiểm tra độ dài đối chiếu với độ dài chữ ký do FIPS quy định cho tập tham số đã chọn trước khi chúng được chấp nhận.

Đồng thời, nó là một bản xem trước và không phải một năng lực sản phẩm khả dụng rộng rãi:

Các định danh cơ chế hậu lượng tử và tập tham số PKCS#11 là tạm thời — OASIS PKCS#11 v3.1 chưa hoàn thiện một registry cơ chế hậu lượng tử, nên các giá trị dùng được theo dõi như tạm thời và người vận hành HSM phải xác nhận firmware PQ của token mình khớp với chúng trước khi bật.
Không có đường xác minh hậu lượng tử nào tồn tại trong NextPDF, và không có bộ ETSI nào đăng ký một chữ ký hậu lượng tử cho lưu trữ dài hạn AdES, nên một chữ ký tạo ra ở đây chưa tương tác được và hầu hết trình xem PDF sẽ từ chối nó tại lúc xác minh.
Một mô tả đi kèm, PqsCapabilityStatus, báo cáo các sự thật này dưới một dạng máy đọc được. Mọi boolean tuyên bố tích cực — generallyAvailable, adesCompliant, verificationAvailable, conformanceClaimed — đều được hard-code thành false và vẫn false kể cả khi cờ xem trước bật, và không cấu hình nào có thể lật một cái sang bật. (Nó cũng mang một cờ recognitionOnly, hard-code true, vốn ghi rằng việc nhận diện thuật toán không bao giờ là một phán quyết tuân thủ; nó không có nghĩa bề mặt không thể ký — việc ký diễn ra qua signPqs() như mô tả ở trên.)

Vì sao nó hoạt động theo cách này

NextPDF đã có thể tính một chữ ký ML-DSA hay SLH-DSA thật qua token. Dù vậy, mọi boolean tuân thủ vẫn được hard-code thành false, đằng sau hai cổng mặc định tắt. Một chữ ký chỉ đáng giá bằng khả năng xác minh nó về sau. Với hậu lượng tử thì chưa có đường xác minh, chưa có bộ ETSI AdES được đăng ký, và chưa có vòng round-trip HSM FIPS-validated. Xuất xưởng cái này như khả dụng rộng rãi sẽ phát hành những chữ ký mà không trình xem nào xác thực được và không kho lưu trữ nào tin được. Vì thế thiết kế tách việc tạo ra các byte khỏi việc tuyên bố rằng bất kỳ ai có thể dựa vào chúng, và không cờ xem trước nào có thể làm mờ ranh giới đó.

Bối cảnh thiết kế: Xác thực dài hạn.

Các tập tham số thuật toán

signPqs() chọn thuật toán và tập tham số qua enum Pkcs11PqsAlgorithm. Mỗi case ánh xạ một tập tham số NIST tới một định danh cơ chế / tập tham số PKCS#11 tạm thời và tới độ dài byte chữ ký do FIPS quy định dùng cho lần kiểm tra độ dài phòng-thủ-theo-tầng.

ML-DSA — FIPS 204 (module-lattice). Ba tập tham số, được tuyên bố ở các hạng độ mạnh bảo mật NIST hiển thị:

Tập tham số	Hạng NIST	Độ dài chữ ký (byte)
`ML-DSA-44`	2	2420
`ML-DSA-65` (mặc định khuyến nghị)	3	3309
`ML-DSA-87`	5	4627

SLH-DSA — FIPS 205 (dựa trên băm không trạng thái). Mười hai tập tham số, hình thành dưới dạng SHA2 / SHAKE x 128 / 192 / 256 x small (s) / fast (f). Các biến thể s giảm thiểu kích thước chữ ký; các biến thể f giảm thiểu độ trễ ký:

Họ tập tham số	Hạng NIST	Độ dài chữ ký (byte)
`SLH-DSA-{SHA2,SHAKE}-128s`	1	7856
`SLH-DSA-{SHA2,SHAKE}-128f`	1	17088
`SLH-DSA-{SHA2,SHAKE}-192s`	3	16224
`SLH-DSA-{SHA2,SHAKE}-192f`	3	35664
`SLH-DSA-{SHA2,SHAKE}-256s`	5	29792
`SLH-DSA-{SHA2,SHAKE}-256f`	5	49856

Bật bản xem trước

Hai cổng độc lập cả hai đều phải mở. Cả hai mặc định tắt.

Cổng tiến trình. Đặt NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1 trước khi tiến trình boot (hoặc qua putenv() trước khi trạng thái được đọc). Bắt buộc bằng nghiêm ngặt với chuỗi 1; bất kỳ giá trị nào khác — kể cả 0, true, yes, hoặc rỗng — đều được coi là tắt.
Opt-in theo từng bộ ký. Truyền $enablePostQuantum: true vào hàm dựng Pkcs11Signer.

use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer;
use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsPreviewFeature;

// 1. Open the process-level preview gate (default-off).
putenv(PqsPreviewFeature::ENV_PREVIEW_PQS_HSM . '=1');

// 2. The capability status is honest even with the gate open:
//    generallyAvailable / adesCompliant / verificationAvailable stay false.
$status = PqsCapabilityStatus::current();

// 3. Construct the PKCS#11 signer with the per-signer opt-in.
$signer = new Pkcs11Signer(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId: 0,
    pin: '1234',
    certLabel: 'my-pqc-signing-cert',
    enablePostQuantum: true,
);

// 4. Sign with a chosen parameter set. The returned bytes are length-checked
//    against Pkcs11PqsAlgorithm::signatureLength() before being accepted.
$signature = $signer->signPqs(
    data: $tbsBytes,
    algorithm: Pkcs11PqsAlgorithm::MlDsa65,
);

isPostQuantumEnabled() báo cáo liệu opt-in theo từng bộ ký có được đặt hay không, và PqsCapabilityStatus::current() báo cáo trạng thái cấp tiến trình cùng các boolean tuyên bố trung thực.

Ranh giới fail-closed

Bề mặt là fail-closed và báo cáo các lần hỏng qua các ngoại lệ có tên, có kiểu chứ không phải lần dự phòng âm thầm:

Vắng opt-in. Nếu signPqs() được gọi khi $enablePostQuantum là false, nó ném HsmOperationException. Không có việc ký nào diễn ra.
Ngữ cảnh quá dài. Một chuỗi octet ngữ cảnh ký dài hơn 255 byte ném InvalidArgumentException (theo giới hạn ngữ cảnh FIPS 204 / FIPS 205) trước bất kỳ lệnh gọi token nào.
Vắng khóa. Nếu không có khóa riêng nào khớp với nhãn đã cấu hình trên token, signPqs() ném HsmOperationException.
Không khớp độ dài. Nếu token trả về một chữ ký mà độ dài byte không bằng độ dài do FIPS quy định cho tập tham số, signPqs() ném HsmOperationException — một chữ ký dị dạng (bị cắt cụt hoặc quá cỡ) bị từ chối trước khi nó có thể đến việc mã hóa CMS SignedData.
Lỗi token. Bất kỳ lỗi PKCS#11 nền tảng nào đều được bọc trong HsmOperationException.

Cờ env cấp tiến trình không thay đổi gì về ranh giới này: kể cả khi cờ bật, các boolean năng lực vẫn false và đường ký vẫn được kiểm tra độ dài và fail-closed.

Ranh giới trung thực

Các tuyên bố sau không được đưa ra cho bề mặt này và không được xuất hiện trong bất kỳ tài liệu, UI, hay hoạt động tiếp thị nào phái sinh từ nó:

“GA” / “generally available”.
“AdES” / “PAdES-compliant” — không có bộ ETSI nào đăng ký một chữ ký hậu lượng tử cho lưu trữ dài hạn.
“FIPS-validated” — không có vòng round-trip HSM hậu lượng tử FIPS-140-3 validated nào được thiết lập cho đường này.
“certified” hay “conformant” đối với FIPS, OASIS PKCS#11 v3.1, hay ETSI.
“production-ready”.

Bề mặt này trung thực là gì: một bản xem trước opt-in, mặc định tắt, fail-closed của việc ký hậu lượng tử ủy quyền cho HSM vốn điều khiển ML-DSA / SLH-DSA qua một token PKCS#11 và kiểm tra độ dài kết quả. Nó không phải gì: một năng lực ký khả dụng rộng rãi, tuân thủ AdES, FIPS-validated, hay được chứng nhận.

Ranh giới tiêu chuẩn

Các tiêu chuẩn liên quan do các cơ quan bên ngoài duy trì, và bản xem trước không giữ lập trường nào về việc tuân thủ bất kỳ tiêu chuẩn nào trong số đó:

Các tập tham số thuật toán và độ dài chữ ký tuân theo FIPS 204 (ML-DSA) và FIPS 205 (SLH-DSA).
Các định danh cơ chế token tuân theo OASIS PKCS#11; registry cơ chế hậu lượng tử trong PKCS#11 v3.1 chưa được hoàn thiện, nên NextPDF dùng các định danh tạm thời.
Các hồ sơ lưu-trữ-dài-hạn cho chữ ký PDF là ETSI EN 319 142-2 (các hồ sơ mở rộng PAdES, dựng trên CMS SignerInfo) và danh mục bộ-mật-mã ETSI TS 119 312, vốn hiện chỉ profile RSA và ECDSA — không có bộ hậu lượng tử nào được đăng ký cho CAdES/PAdES. Một chữ ký PDF hậu lượng tử tạo ra hôm nay do đó chưa tuân thủ AdES cho lưu trữ.

Không có văn bản tiêu chuẩn nào được tái tạo trên trang này.

Ghi chú bảo mật

Một bản xem trước không phải một biện pháp kiểm soát bảo mật. Sự hiện diện của một chữ ký hậu lượng tử tạo ra bởi đường này không thiết lập tính hợp lệ AdES, không ngụ ý một khóa tin cậy, và không thể xác minh bởi NextPDF (không có đường xác minh hậu lượng tử nào). Đừng dựa vào bản xem trước này để bảo đảm chữ ký, và đừng triển khai nó ở nơi cần một chữ ký tuân thủ AdES hay FIPS-validated. Hãy giữ cả hai cổng tắt trong sản phẩm cho tới khi các tiêu chuẩn ra đời.

Bề mặt API

Ký hiệu	Vai trò
`Pkcs11Signer::signPqs()`	Việc ký hậu lượng tử ủy quyền cho HSM opt-in, fail-closed qua PKCS#11. Ném `HsmOperationException` khi bị vô hiệu, khi vắng khóa, hoặc khi không khớp độ dài chữ ký.
`Pkcs11Signer::isPostQuantumEnabled()`	Liệu opt-in `$enablePostQuantum` theo từng bộ ký có được đặt hay không.
`Pkcs11PqsAlgorithm`	Enum các tập tham số ML-DSA (FIPS 204) và SLH-DSA (FIPS 205); ánh xạ mỗi cái tới một id cơ chế tạm thời và độ dài chữ ký do FIPS quy định.
`PqsPreviewFeature`	Cổng env cấp tiến trình, mặc định tắt (`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`).
`PqsCapabilityStatus`	Trạng thái trung thực, máy đọc được: mọi boolean tuyên bố tích cực (khả-dụng-rộng-rãi, AdES, xác minh, tuân thủ) đều được hard-code `false` bất kể cờ xem trước.
`HsmOperationException`	Ngoại lệ có kiểu được làm phát sinh trên các đường fail-closed.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt API công khai được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket đều nằm ngoài phạm vi.