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

Bản xem trước ký hậu lượng tử — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu ở cấp hợp đồng cho bề mặt xem trước ký hậu lượng tử (PQS) trong NextPDF Enterprise. Nó bao quát ba ký hiệu công khai: enum tập tham số Pkcs11PqsAlgorithm, cổng tiến trình PqsPreviewFeature, và bộ mô tả PqsCapabilityStatus. Nó cũng ghi lại cổng môi trường NEXTPDF_FEATURE_PREVIEW_PQS_HSM.

Bề mặt này là experimental và mặc định tắt. Nó nhận diện các định danh thuật toán, tập tham số, và độ dài chữ ký của ML-DSA (FIPS 204) và SLH-DSA (FIPS 205). Nhận diện không phải là một phán quyết xác thực. Không có đường dẫn xác minh hậu lượng tử. Không có tuyên bố AdES, xác thực FIPS, hay tuân thủ nào được đưa ra, và cờ xem trước không thể tạo ra một tuyên bố như vậy. Điểm vào ký tiêu thụ, Pkcs11Signer::signPqs(), được mô tả trên trang năng lực.

Tình trạng sẵn có & cấp phép

Năng lực này được cung cấp trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một phong bì giấy phép cấp Enterprise. Một triển khai không có quyền đó 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à nhận giấy phép.

Giấy phép kích hoạt toàn bộ bề mặt PKCS#11 của Enterprise. Đường dẫn hậu lượng tử bên trong nó vẫn là một bản xem trước bất kể cấp giấy phép. Vẫn cần hai lựa chọn chọn-tham-gia độc lập: cổng tiến trình được ghi lại ở đây và cờ hàm dựng trên từng người ký của Pkcs11Signer.

Bề mặt API công khai

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
`Pkcs11PqsAlgorithm`	enum có nền tảng string, 15 trường hợp	Đặt tên một tập tham số FIPS 204 / FIPS 205 cho mỗi trường hợp	trường hợp enum	Không có gì khi truy cập trường hợp	Giá trị trường hợp là tên tập tham số, ví dụ `ML-DSA-65`.
`Pkcs11PqsAlgorithm::isMlDsa()`	không	Kiểm tra họ	`bool`	Không ném	`true` cho `MlDsa44`, `MlDsa65`, `MlDsa87`.
`Pkcs11PqsAlgorithm::isSlhDsa()`	không	Phủ định của `isMlDsa()`	`bool`	Không ném	`true` cho mười hai trường hợp SLH-DSA.
`Pkcs11PqsAlgorithm::mechanismId()`	không	Ánh xạ họ sang mã cơ chế PQ PKCS#11 v3.1 ứng viên	`int`	PHP `Error` khi runtime thiếu các hằng số PQ `Pkcs11` tạm thời	`CKM_ML_DSA` hoặc `CKM_SLH_DSA`; cả hai mã đều tạm thời.
`Pkcs11PqsAlgorithm::parameterSetId()`	không	Ánh xạ trường hợp sang bộ phân biệt tập tham số OASIS	`int`	PHP `Error` khi runtime thiếu các hằng số PQ `Pkcs11` tạm thời	Các giá trị `CKP_*`; tạm thời.
`Pkcs11PqsAlgorithm::signatureLength()`	không	Độ dài byte chữ ký do FIPS quy định cho trường hợp	`int` (dương)	Không ném	Được đường dẫn ký tiêu thụ để từ chối một chữ ký trả về có độ dài không mong đợi.
`Pkcs11PqsAlgorithm::nistCategory()`	không	Hạng mức bảo mật NIST được tuyên bố	`int`	Không ném	Trả về 1, 2, 3, hoặc 5.
`PqsPreviewFeature`	enum có nền tảng string, 1 trường hợp	Trường hợp đơn `PREVIEW_PQS_HSM`; hằng số `ENV_PREVIEW_PQS_HSM`	trường hợp enum	Không có gì khi truy cập trường hợp	Cổng xem trước ở cấp tiến trình.
`PqsPreviewFeature::isEnabled()`	không	Đọc `getenv()` trực tiếp; so sánh nghiêm ngặt với chuỗi `1`	`bool`	Không ném	Biến vắng mặt hoặc bất kỳ giá trị nào khác, kể cả `0`, `true`, `yes`, đều là tắt.
`PqsCapabilityStatus::__construct()`	chín trường readonly có tên	Dựng một thể hiện bộ mô tả tùy ý	`PqsCapabilityStatus`	Không ném	`current()` là hàm dựng chuẩn tắc.
`PqsCapabilityStatus::current()`	không	Dựng bộ mô tả cho tiến trình bao quanh	`PqsCapabilityStatus`	Không ném	Mọi boolean tuyên bố đều cố định; chỉ `hsmRoundtripPreviewEnabled` thay đổi theo cổng.
`PqsCapabilityStatus::summary()`	không	Văn bản trạng thái một dòng	`string`	Không ném	Cách diễn đạt không mang tuyên bố sẵn có, lưu trữ, hay xác thực nào.

enum Pkcs11PqsAlgorithm: string

case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';

case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';

case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';

case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';

public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int

enum PqsPreviewFeature: string

case PREVIEW_PQS_HSM = 'preview_pqs_hsm';

public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';

public function isEnabled(): bool

final readonly class PqsCapabilityStatus

public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';

public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)

public static function current(): self
public function summary(): string

Hợp đồng hành vi

Danh mục tập tham số. NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm liệt kê ba tập ML-DSA (FIPS 204) và mười hai tập SLH-DSA (FIPS 205 §11.p12, Table 2). Mỗi trường hợp ánh xạ tới một mã cơ chế tạm thời, một bộ phân biệt tập tham số, một độ dài byte chữ ký do FIPS quy định, và một hạng NIST được tuyên bố.
Độ dài chữ ký. signatureLength() trả về 2420, 3309, và 4627 byte cho MlDsa44, MlDsa65, và MlDsa87, theo FIPS 204 §4.p15 (Table 2). Các trường hợp SLH-DSA trả về 7856, 17088, 16224, 35664, 29792, và 49856 byte theo mức và biến thể, theo FIPS 205 §11 (Table 2). Người ký tiêu thụ ném HsmOperationException khi một chữ ký trả về có độ dài khác, phản ánh kỷ luật từ chối theo độ dài của FIPS 204 §x34.
Các hạng. nistCategory() trả về 2, 3, và 5 cho các trường hợp ML-DSA, theo FIPS 204 §4.p9. Các trường hợp SLH-DSA trả về 1, 3, và 5 theo mức tham số bảo mật.
Cổng tiến trình. PqsPreviewFeature::PREVIEW_PQS_HSM mặc định tắt. isEnabled() trả về true chỉ khi biến môi trường NEXTPDF_FEATURE_PREVIEW_PQS_HSM bằng đúng chuỗi 1. Việc đọc là trực tiếp trên mỗi lần gọi; không có gì được ghi nhớ.
Cổng bổ trợ. Cổng tiến trình tách biệt với lựa chọn chọn-tham-gia hàm dựng trên từng người ký $enablePostQuantum của Pkcs11Signer. Lệnh gọi ký thất bại đóng nếu không có lựa chọn chọn-tham-gia trên từng người ký. Cổng tiến trình tồn tại như một ranh giới có thể kiểm toán duy nhất cho bất kỳ hành vi khứ hồi hay lưu trữ nào trong tương lai.
Bất biến trung thực. NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() mã hóa cứng generallyAvailable, adesCompliant, verificationAvailable, và conformanceClaimed thành false, và recognitionOnly thành true. Không có cấu hình, tùy chọn hàm dựng, hay cờ môi trường nào bật một tuyên bố lên. Chỉ hsmRoundtripPreviewEnabled phản ánh cổng.
Không có đường dẫn xác minh. NextPDF không có đường dẫn xác minh hậu lượng tử. Một định danh thuật toán được nhận diện hay một độ dài chữ ký đúng dạng không bao giờ là một phán quyết chấp nhận.

Trường hợp biên & chế độ thất bại

Đặt biến cổng thành 0, true, yes, on, hoặc một chuỗi rỗng sẽ để cổng tắt. Chỉ chuỗi chính xác 1 mới bật nó.
Các thay đổi bằng putenv() có hiệu lực ở lần gọi isEnabled() kế tiếp vì việc đọc là trực tiếp. Một cổng được chuyển đổi giữa tiến trình được quan sát ngay lập tức.
mechanismId() và parameterSetId() phân giải các hằng số từ không gian tên phần mở rộng Pkcs11. Một runtime không có các hằng số phần mở rộng hậu lượng tử tạm thời sẽ thất bại với một PHP Error (hằng số chưa định nghĩa) tại thời điểm gọi.
Các mã cơ chế và tập tham số là tạm thời. OASIS chưa hoàn thiện sổ đăng ký hậu lượng tử PKCS#11 v3.1. Một token có firmware gán các mã khác sẽ thất bại ở tầng PKCS#11; người vận hành phải xác nhận các mã firmware trước khi bật bản xem trước.
Ngữ cảnh ký được người ký tiêu thụ chấp nhận bị giới hạn ở 255 byte, khớp với hợp đồng đầu vào ký của FIPS 204 (§x43.p2). Một ngữ cảnh dài hơn sẽ ném InvalidArgumentException trước bất kỳ lệnh gọi token nào.
PqsCapabilityStatus::__construct() là công khai, nên một thể hiện được dựng bằng tay có thể mang các boolean tùy ý. Một thể hiện như vậy chỉ là một đối tượng giá trị. Nó không làm thay đổi bất kỳ hành vi ký nào. current() là hàm dựng chuẩn tắc, được mã hóa cứng.
Lựa chọn ngẫu-nhiên-so-với-tất-định trên người ký tiêu thụ tuân theo ngữ nghĩa FIPS 205 §x65.p7: ký hedged là mặc định. Cờ bị bỏ qua đối với ML-DSA, vốn luôn ngẫu nhiên hóa qua nonce riêng của nó.

Hành vi chế độ FIPS

ML-DSA và SLH-DSA là các thuật toán FIPS 204 và FIPS 205, nhưng bản xem trước này không mang tuyên bố xác thực FIPS 140-3 nào. Không có khứ hồi HSM hậu lượng tử được xác thực FIPS nào được thiết lập cho đường dẫn này. Hồ sơ chính sách mật mã chế độ FIPS của Enterprise, được ghi lại trên Tham chiếu chuyên sâu Security, khống chế các thuật toán ký cổ điển; nó không đưa bề mặt PQS vào một tập đã được xác thực. Bật chế độ FIPS không làm cho ký hậu lượng tử được xác thực FIPS. Đừng triển khai bản xem trước ở nơi cần một chữ ký được xác thực FIPS.

Tuân thủ

Claim	Standard	Clause
ML-DSA-44/65/87 mang các hạng NIST được tuyên bố 2, 3, 5.	FIPS 204	§4.p9
Kích thước chữ ký ML-DSA là 2420, 3309, 4627 byte.	FIPS 204	§4.p15 (Table 2)
Chuỗi byte ngữ cảnh ký bị giới hạn ở 255 byte.	FIPS 204	§x43.p2
Một chữ ký hoặc khóa sai độ dài phải bị từ chối.	FIPS 204	§x34
Mười hai tập tham số SLH-DSA được phê duyệt.	FIPS 205	§11.p12 (Table 2)
Kích thước chữ ký SLH-DSA tuân theo Table 2 (7856 byte cho 128s).	FIPS 205	§11.p6
Ký hedged là mặc định; tồn tại một biến thể tất định.	FIPS 205	§x65.p7
Danh mục các bộ CAdES/PAdES chỉ hồ sơ RSA và EC-DSA.	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
Các mã cơ chế PQ PKCS#11 là tạm thời.	OASIS PKCS#11 v3.1	product-source grounded

Tất cả các điều khoản đều được diễn giải. NextPDF không tái tạo văn bản quy phạm. NextPDF không nắm giữ chứng nhận nào và không cấp chứng nhận nào. Các phát biểu ở trên là các phát biểu về căn chỉnh cấu trúc đối với các định danh, độ dài, và giới hạn. Chúng không phải là kết quả kiểm thử tuân thủ, không phải chứng thực của bên thứ ba, và không phải một tuyên bố tuân thủ FIPS, OASIS, hay ETSI. PqsCapabilityStatus mã hóa tư thế này trong mã: conformanceClaimed là false, adesCompliant là false, và verificationAvailable là false, trong mọi cấu hình. Một chữ ký được tạo bởi bản xem trước này không tuân thủ AdES cho lưu trữ dài hạn, và hầu hết trình xem PDF từ chối nó tại thời điểm xác thực.

Ghi chú phát triển

Sổ đăng ký cơ chế hậu lượng tử OASIS PKCS#11 chưa được hoàn thiện; các mã CKM_ML_DSA / CKM_SLH_DSA và các hằng số tập tham số dùng ở đây là tạm thời và được nền tảng hóa từ mã nguồn sản phẩm, không phải một trích dẫn spec.
Mốc hiện tại là mức sẵn sàng đã được kiểm thử mô phỏng. Chưa có khứ hồi HSM firmware hậu lượng tử thực nào được xác thực.
Giữ cả hai cổng tắt trong môi trường sản xuất. Bản xem trước không thêm năng lực sản xuất nào mà đường dẫn PKCS#11 RSA/ECDSA cổ điển thiếu.
Trước bất kỳ đánh giá nào với phần cứng thực, hãy xác nhận các mã cơ chế và tập tham số của firmware token so với các giá trị tạm thời. Một sự không khớp sẽ thất bại ở tầng PKCS#11, không phải bên trong NextPDF.
Hãy coi PqsCapabilityStatus::current() là nguồn sự thật duy nhất khi hiển thị trạng thái PQS trong công cụ hay UI. Đừng phát biểu lại các boolean của nó bằng tay.
Đầu ra summary() an toàn cho log và các điểm cuối trạng thái; nó được diễn đạt để không mang tuyên bố sẵn có hay xác thực nào.

Xem thêm

Ranh giới công bố

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