การพรีวิวการลงนามแบบ post-quantum — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยสังเขป

หน้านี้เป็นข้อมูลอ้างอิงระดับสัญญาสำหรับพื้นผิวการพรีวิวการลงนามแบบ post-quantum (PQS) ใน NextPDF Enterprise ครอบคลุมสัญลักษณ์สาธารณะสามตัว ได้แก่ enum ชุดพารามิเตอร์ Pkcs11PqsAlgorithm ตัวควบคุมระดับ process อย่าง PqsPreviewFeature และตัวบรรยาย PqsCapabilityStatus อีกทั้งยังอธิบายตัวควบคุมผ่านตัวแปรสภาพแวดล้อม NEXTPDF_FEATURE_PREVIEW_PQS_HSM

พื้นผิวนี้อยู่ในสถานะ experimental และ ปิดอยู่โดยค่าเริ่มต้น โดยรับรู้ตัวระบุอัลกอริทึม ชุดพารามิเตอร์ และความยาวลายเซ็นของ ML-DSA (FIPS 204) และ SLH-DSA (FIPS 205) การรับรู้ไม่ใช่คำตัดสินการตรวจสอบความถูกต้อง ไม่มีเส้นทางการตรวจสอบแบบ post-quantum ไม่มีการอ้างความสอดคล้อง AdES การรับรอง FIPS หรือความสอดคล้องใด และธงพรีวิวก็ไม่อาจสร้างคำอ้างเหล่านั้นขึ้นมาได้ จุดเข้าใช้งานการลงนามที่บริโภคพื้นผิวนี้คือ Pkcs11Signer::signPqs() ซึ่งอธิบายไว้ในหน้าความสามารถ

ความพร้อมใช้งานและการให้สิทธิ์ใช้งาน

ความสามารถนี้มาพร้อมกับ NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Enterprise การติดตั้งที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอรับใบอนุญาต

ใบอนุญาตจะเปิดใช้งานพื้นผิว PKCS#11 ของ Enterprise ทั้งชุด แต่เส้นทาง post-quantum ภายในยังคงเป็นการพรีวิวไม่ว่าระดับใบอนุญาตจะเป็นอย่างไร ยังคงต้องมีการเลือกเข้าร่วมสองอย่างที่เป็นอิสระต่อกัน ได้แก่ ตัวควบคุมระดับ process ที่อธิบายไว้ที่นี่ และธงตัวสร้างต่อผู้ลงนามบน Pkcs11Signer

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนข้อผิดพลาดหรือล้มเหลวด้วย	หมายเหตุ
Pkcs11PqsAlgorithm	enum ที่หนุนด้วย string, 15 กรณี	ตั้งชื่อชุดพารามิเตอร์ FIPS 204 / FIPS 205 หนึ่งชุดต่อกรณี	enum case	ไม่มีอะไรเมื่อเข้าถึงกรณี	ค่าของกรณีคือชื่อชุดพารามิเตอร์ เช่น ML-DSA-65
Pkcs11PqsAlgorithm::isMlDsa()	ไม่มี	การทดสอบตระกูล	bool	ไม่โยนข้อผิดพลาด	true สำหรับ MlDsa44, MlDsa65, MlDsa87
Pkcs11PqsAlgorithm::isSlhDsa()	ไม่มี	การปฏิเสธของ isMlDsa()	bool	ไม่โยนข้อผิดพลาด	true สำหรับกรณี SLH-DSA ทั้งสิบสอง
Pkcs11PqsAlgorithm::mechanismId()	ไม่มี	จับคู่ตระกูลกับ id กลไก PQ ของ PKCS#11 v3.1 ที่เป็นตัวเลือก	int	PHP Error เมื่อ runtime ขาดค่าคงที่ PQ Pkcs11 แบบชั่วคราว	CKM_ML_DSA หรือ CKM_SLH_DSA ทั้งสอง id เป็นแบบชั่วคราว
Pkcs11PqsAlgorithm::parameterSetId()	ไม่มี	จับคู่กรณีกับตัวจำแนกชุดพารามิเตอร์ของ OASIS	int	PHP Error เมื่อ runtime ขาดค่าคงที่ PQ Pkcs11 แบบชั่วคราว	ค่า CKP_* แบบชั่วคราว
Pkcs11PqsAlgorithm::signatureLength()	ไม่มี	ความยาวไบต์ลายเซ็นตามที่ FIPS กำหนดสำหรับกรณีนั้น	int (บวก)	ไม่โยนข้อผิดพลาด	ถูกบริโภคโดยเส้นทางการลงนามเพื่อปฏิเสธลายเซ็นที่คืนค่ามาด้วยความยาวไม่คาดคิด
Pkcs11PqsAlgorithm::nistCategory()	ไม่มี	หมวดระดับความแข็งแรงความปลอดภัยของ NIST ที่อ้าง	int	ไม่โยนข้อผิดพลาด	คืนค่า 1, 2, 3 หรือ 5
PqsPreviewFeature	enum ที่หนุนด้วย string, 1 กรณี	กรณีเดียว PREVIEW_PQS_HSM ค่าคงที่ ENV_PREVIEW_PQS_HSM	enum case	ไม่มีอะไรเมื่อเข้าถึงกรณี	ตัวควบคุมพรีวิวระดับ process
PqsPreviewFeature::isEnabled()	ไม่มี	อ่าน getenv() แบบสด เทียบแบบเข้มกับ string 1	bool	ไม่โยนข้อผิดพลาด	ตัวแปรที่ไม่มีอยู่หรือค่าอื่นใด รวมถึง 0, true, yes ถือว่าปิด
PqsCapabilityStatus::__construct()	ฟิลด์ readonly ที่ระบุชื่อเก้าฟิลด์	สร้างอินสแตนซ์ตัวบรรยายตามอำเภอใจ	PqsCapabilityStatus	ไม่โยนข้อผิดพลาด	current() คือตัวสร้างมาตรฐาน
PqsCapabilityStatus::current()	ไม่มี	สร้างตัวบรรยายสำหรับ process ที่แวดล้อมอยู่	PqsCapabilityStatus	ไม่โยนข้อผิดพลาด	บูลีนของทุกคำอ้างถูกตรึงไว้ มีเพียง hsmRoundtripPreviewEnabled ที่เปลี่ยนไปตามตัวควบคุม
PqsCapabilityStatus::summary()	ไม่มี	ข้อความสถานะบรรทัดเดียว	string	ไม่โยนข้อผิดพลาด	ถ้อยคำไม่แบกคำอ้างเรื่องความพร้อมใช้งาน การเก็บถาวร หรือการตรวจสอบความถูกต้อง

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

สัญญาพฤติกรรม

• แคตาล็อกชุดพารามิเตอร์ NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm แจกแจงชุด ML-DSA สามชุด (FIPS 204) และชุด SLH-DSA สิบสองชุด (FIPS 205 §11.p12, Table 2) แต่ละกรณีจับคู่กับ id กลไกแบบชั่วคราว ตัวจำแนกชุดพารามิเตอร์ ความยาวไบต์ลายเซ็นตามที่ FIPS กำหนด และหมวด NIST ที่อ้าง
• ความยาวลายเซ็น signatureLength() คืนค่า 2420, 3309 และ 4627 ไบต์สำหรับ MlDsa44, MlDsa65 และ MlDsa87 ตาม FIPS 204 §4.p15 (Table 2) กรณี SLH-DSA คืนค่า 7856, 17088, 16224, 35664, 29792 และ 49856 ไบต์ตามระดับและตัวแปร ตาม FIPS 205 §11 (Table 2) ผู้ลงนามที่บริโภคจะโยน HsmOperationException เมื่อลายเซ็นที่คืนค่ามามีความยาวต่างออกไป ซึ่งสะท้อนวินัยการปฏิเสธความยาวตาม FIPS 204 §x34
• หมวด nistCategory() คืนค่า 2, 3 และ 5 สำหรับกรณี ML-DSA ตาม FIPS 204 §4.p9 กรณี SLH-DSA คืนค่า 1, 3 และ 5 ตามระดับพารามิเตอร์ความปลอดภัย
• ตัวควบคุมระดับ process PqsPreviewFeature::PREVIEW_PQS_HSM ปิดอยู่โดยค่าเริ่มต้น isEnabled() คืนค่า true เฉพาะเมื่อตัวแปรสภาพแวดล้อม NEXTPDF_FEATURE_PREVIEW_PQS_HSM เท่ากับ string 1 พอดีเท่านั้น การอ่านเป็นแบบสดในทุกครั้งที่เรียก ไม่มีการจำค่าไว้
• การควบคุมเสริม ตัวควบคุมระดับ process แยกจากการเลือกเข้าร่วมผ่านตัวสร้างต่อผู้ลงนาม $enablePostQuantum บน Pkcs11Signer การเรียกลงนามจะล้มเหลวแบบปิดหากไม่มีการเลือกเข้าร่วมต่อผู้ลงนาม ตัวควบคุมระดับ process มีอยู่เพื่อเป็นขอบเขตที่ตรวจสอบได้เพียงจุดเดียวสำหรับพฤติกรรม round-trip หรือการเก็บถาวรใดในอนาคต
• ค่าคงตัวความซื่อตรง NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() ฝังค่า generallyAvailable, adesCompliant, verificationAvailable และ conformanceClaimed เป็น false ตายตัว และ recognitionOnly เป็น true ไม่มีการตั้งค่า ตัวเลือกตัวสร้าง หรือธงสภาพแวดล้อมใดที่พลิกคำอ้างให้เป็นจริงได้ มีเพียง hsmRoundtripPreviewEnabled ที่สะท้อนตัวควบคุม
• ไม่มีเส้นทางการตรวจสอบ NextPDF ไม่มีเส้นทางการตรวจสอบแบบ post-quantum ตัวระบุอัลกอริทึมที่ถูกรับรู้หรือความยาวลายเซ็นที่ถูกต้องตามรูปแบบไม่เคยเป็นคำตัดสินการยอมรับ

กรณีขอบและรูปแบบความล้มเหลว

• การตั้งค่าตัวแปรตัวควบคุมเป็น 0, true, yes, on หรือ string ว่างจะทำให้ตัวควบคุม ปิด อยู่ มีเพียง string 1 พอดีเท่านั้นที่เปิดใช้งาน
• การเปลี่ยนแปลงด้วย putenv() จะมีผลในการเรียก isEnabled() ครั้งถัดไปเพราะการอ่านเป็นแบบสด ตัวควบคุมที่สลับกลางกระบวนการจะถูกสังเกตทันที
• mechanismId() และ parameterSetId() แปลค่าคงที่จากเนมสเปซของส่วนขยาย Pkcs11 runtime ที่ไม่มีค่าคงที่ส่วนขยาย post-quantum แบบชั่วคราวจะล้มเหลวด้วย PHP Error (ค่าคงที่ที่ไม่ได้นิยาม) ณ เวลาที่เรียก
• id กลไกและชุดพารามิเตอร์เป็นแบบ ชั่วคราว OASIS ยังไม่ได้สรุปทะเบียน post-quantum ของ PKCS#11 v3.1 โทเคนที่เฟิร์มแวร์กำหนด id ต่างออกไปจะล้มเหลวที่ชั้น PKCS#11 ผู้ปฏิบัติงานต้องยืนยัน id ของเฟิร์มแวร์ก่อนเปิดใช้งานการพรีวิว
• บริบทการลงนามที่ผู้ลงนามผู้บริโภครับได้ถูกจำกัดไว้ที่ 255 ไบต์ ตรงกับสัญญาอินพุตการลงนามของ FIPS 204 (§x43.p2) บริบทที่ยาวกว่าจะโยน InvalidArgumentException ก่อนการเรียกโทเคนใด
• PqsCapabilityStatus::__construct() เป็นแบบสาธารณะ ดังนั้นอินสแตนซ์ที่สร้างขึ้นเองสามารถแบกบูลีนตามอำเภอใจได้ อินสแตนซ์เช่นนั้นเป็นเพียง value object เท่านั้น มันไม่เปลี่ยนแปลงพฤติกรรมการลงนามใด current() คือตัวสร้างมาตรฐานที่ฝังค่าตายตัว
• ตัวเลือกระหว่างแบบสุ่มกับแบบกำหนดตายตัวบนผู้ลงนามผู้บริโภคเป็นไปตามความหมายของ FIPS 205 §x65.p7 การลงนามแบบ hedged เป็นค่าเริ่มต้น ธงนี้ถูกละเว้นสำหรับ ML-DSA ซึ่งสุ่มด้วย nonce ของตัวเองเสมอ

พฤติกรรมในโหมด FIPS

ML-DSA และ SLH-DSA เป็นอัลกอริทึม FIPS 204 และ FIPS 205 แต่การพรีวิวนี้ ไม่แบกคำอ้างการรับรอง FIPS 140-3 ใด ยังไม่มีการสร้าง round-trip HSM แบบ post-quantum ที่ผ่านการรับรอง FIPS สำหรับเส้นทางนี้ โปรไฟล์นโยบายการเข้ารหัสโหมด FIPS ของ Enterprise ซึ่งอธิบายไว้ในข้อมูลอ้างอิงเชิงลึกด้านความปลอดภัย ควบคุมอัลกอริทึมการลงนามแบบดั้งเดิม แต่ไม่รับพื้นผิว PQS เข้าสู่ชุดที่ผ่านการรับรอง การเปิดโหมด FIPS ไม่ทำให้การลงนามแบบ post-quantum ผ่านการรับรอง FIPS อย่านำการพรีวิวไปใช้งานในที่ที่ต้องการลายเซ็นที่ผ่านการรับรอง FIPS

ความสอดคล้อง

คำอ้าง	มาตรฐาน	ข้อ
ML-DSA-44/65/87 แบกหมวด NIST ที่อ้างคือ 2, 3, 5	FIPS 204	§4.p9
ขนาดลายเซ็น ML-DSA คือ 2420, 3309, 4627 ไบต์	FIPS 204	§4.p15 (Table 2)
string ไบต์ของบริบทการลงนามถูกจำกัดไว้ที่ 255 ไบต์	FIPS 204	§x43.p2
ลายเซ็นหรือกุญแจที่ความยาวผิดต้องถูกปฏิเสธ	FIPS 204	§x34
ชุดพารามิเตอร์ SLH-DSA สิบสองชุดได้รับการอนุมัติ	FIPS 205	§11.p12 (Table 2)
ขนาดลายเซ็น SLH-DSA เป็นไปตาม Table 2 (7856 ไบต์สำหรับ 128s)	FIPS 205	§11.p6
การลงนามแบบ hedged เป็นค่าเริ่มต้น และมีตัวแปรแบบกำหนดตายตัวอยู่	FIPS 205	§x65.p7
แคตาล็อกชุด CAdES/PAdES กำหนดโปรไฟล์เฉพาะ RSA และ EC-DSA เท่านั้น	ETSI TS 119 312 V1.5.1	§7.x7.p10 (Table A.1)
id กลไก PQ ของ PKCS#11 เป็นแบบชั่วคราว	OASIS PKCS#11 v3.1	อ้างอิงจากแหล่งที่มาของผลิตภัณฑ์

ข้อทั้งหมดเป็นการถอดความ NextPDF ไม่ทำซ้ำข้อความเชิงบรรทัดฐาน NextPDF ไม่ถือครองการรับรองใดและไม่มอบการรับรองใด ข้อความข้างต้นเป็นข้อความเรื่องการจัดวางเชิงโครงสร้างเกี่ยวกับตัวระบุ ความยาว และขอบเขต ไม่ใช่ผลการทดสอบความสอดคล้อง ไม่ใช่การรับรองจากบุคคลที่สาม และไม่ใช่คำอ้างความสอดคล้อง FIPS, OASIS หรือ ETSI PqsCapabilityStatus เข้ารหัสท่าทีนี้ไว้ในโค้ด: conformanceClaimed เป็น false, adesCompliant เป็น false และ verificationAvailable เป็น false ในทุกการตั้งค่า ลายเซ็นที่ผลิตโดยการพรีวิวนี้ไม่สอดคล้อง AdES สำหรับการเก็บถาวรระยะยาว และโปรแกรมดู PDF ส่วนใหญ่จะปฏิเสธมันในเวลาตรวจสอบ

บันทึกการพัฒนา

• ทะเบียนกลไก post-quantum ของ OASIS PKCS#11 ยังไม่ได้สรุป id CKM_ML_DSA / CKM_SLH_DSA และค่าคงที่ชุดพารามิเตอร์ที่ใช้ที่นี่เป็นแบบชั่วคราวและอ้างอิงจากแหล่งที่มาของผลิตภัณฑ์ ไม่ใช่การอ้างอิงข้อกำหนด

• หมุดหมายในปัจจุบันคือความพร้อมที่ทดสอบด้วย mock ยังไม่มีการตรวจสอบ round-trip HSM ด้วยเฟิร์มแวร์ post-quantum จริง

• ให้ตัวควบคุมทั้งสองปิดอยู่ในการใช้งานจริง การพรีวิวไม่เพิ่มความสามารถในการใช้งานจริงใดที่เส้นทาง PKCS#11 แบบ RSA/ECDSA ดั้งเดิมยังขาดอยู่

• ก่อนการประเมินใดด้วยฮาร์ดแวร์จริง ให้ยืนยัน id กลไกและชุดพารามิเตอร์ของเฟิร์มแวร์โทเคนกับค่าชั่วคราว ความไม่ตรงกันจะล้มเหลวที่ชั้น PKCS#11 ไม่ใช่ภายใน NextPDF

• ให้ถือ PqsCapabilityStatus::current() เป็นแหล่งความจริงเพียงหนึ่งเดียวเมื่อแสดงสถานะ PQS ในเครื่องมือหรือ UI อย่าเขียนบูลีนของมันซ้ำด้วยมือ

• ผลลัพธ์ของ summary() ปลอดภัยสำหรับ log และปลายทางสถานะ มันถูกเรียบเรียงให้ไม่แบกคำอ้างเรื่องความพร้อมใช้งานหรือการตรวจสอบใด

ดูเพิ่มเติม

• การพรีวิวการลงนาม HSM แบบ post-quantum (PQS) — หน้าความสามารถ
• ความปลอดภัย — ข้อมูลอ้างอิงเชิงลึก (HSM, PKCS#11, โหมด FIPS)
• ลายเซ็น — ข้อมูลอ้างอิงเชิงลึก
• การตั้งค่าการลงนามด้วย HSM
• ความปลอดภัย / การลงนาม (Core)

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทางเนมสเปซภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต