การแก้ไขปัญหา: ลายเซ็นและการประทับเวลาล้มเหลว

ขอบเขต

รายการเหล่านี้ครอบคลุมความล้มเหลวของลายเซ็นที่ถูกยกผ่าน NextPDF\Exception\SignatureException และ NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException แต่ละรายการระบุชื่อ factory method หรือคลาสที่แน่นอน เพื่อให้ยืนยันสาเหตุได้จากข้อความและ getContext() แทนการคาดเดา

หมายเหตุด้านถ้อยคำ: เอนจินไม่ได้รับรองว่าลายเซ็นถูกต้องหรือเอกสารได้รับการปกป้อง เอนจินรายงานความล้มเหลวที่ตรวจพบเท่านั้น ให้ถือว่าการแก้ไขแต่ละข้อเป็นขั้นตอนเพื่อตัดสาเหตุที่ถูกรายงานออก

รายการ: ไม่สามารถสร้างระดับ PAdES “B-LT” หรือ “B-LTA” ได้

• อาการ SignatureException พร้อมส่วนท้ายของข้อความ nextpdf/enterprise package is required for B-LT/B-LTA signatures
• สาเหตุที่เป็นไปได้ ไม่มีผู้ให้บริการความสามารถสำหรับการตรวจสอบความถูกต้องระยะยาว B-LT และ B-LTA ฝังวัสดุการเพิกถอนและการประทับเวลาแบบจัดเก็บถาวร และผู้ให้บริการนี้มาพร้อมกับ nextpdf/enterprise
• หลักฐาน / การวินิจฉัย factory SignatureException::ltvCapabilityMissing() สร้างข้อความนี้โดยตรง getContext() คืนค่า signature_level ที่ตั้งเป็นระดับที่พยายามใช้
• การแก้ไข

1. ติดตั้งผู้ให้บริการโดยรัน composer require nextpdf/enterprise
2. รันการเรียกเซ็นอีกครั้ง
3. หากไม่สามารถติดตั้งผู้ให้บริการได้ ให้ร้องขอ B-B หรือ B-T แทน ซึ่งแพ็กเกจ core สามารถสร้างได้

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: ระดับลายเซ็นเข้าถึงไม่ได้และการเรียกถูกปฏิเสธ

• อาการ SignatureLevelUnreachableException พร้อมข้อความในรูปแบบ PAdES level "<x>" is unreachable (highest achievable: "<y>")
• สาเหตุที่เป็นไปได้ ระดับความสอดคล้องที่ร้องขอต้องใช้โครงสร้างพื้นฐานที่ไม่พร้อมใช้งานในเวลาเซ็น โดยส่วนใหญ่คือผู้ออกใบรับรองการประทับเวลาสำหรับ B-T ขึ้นไป เอนจินล้มเหลวแบบปิด: เอนจินไม่ลดระดับลงอย่างเงียบๆ แล้วประกาศระดับที่สูงกว่า
• หลักฐาน / การวินิจฉัย getContext() คืนค่า requestedLevel, highestAchievableLevel, และ reason ฟิลด์ reason ระบุช่องว่างของโครงสร้างพื้นฐาน นี่คือค่าเริ่มต้นแบบล้มเหลวแบบปิดที่ใช้เพื่อป้องกันไม่ให้เอกสารอ้างระดับที่ไม่เป็นไปตามเงื่อนไข
• การแก้ไข

1. อ่านฟิลด์ reason เพื่อระบุโครงสร้างพื้นฐานที่ขาดหายไป
2. จัดหาส่วนประกอบที่ขาดหายไป ตัวอย่างเช่น กำหนดค่าผู้ออกใบรับรองการประทับเวลา แล้วรันการเรียกอีกครั้ง
3. หากต้องการยอมรับระดับที่ต่ำกว่าโดยเจตนา ให้ส่ง allowDegradation: true ไปยัง PadesOrchestrator จากนั้นการเรียกจะสร้าง highestAchievableLevel และรายงานระดับที่สร้างได้

• ที่เกี่ยวข้อง การเข้ารหัสลับและสิทธิ์

รายการ: จำเป็นต้องมีไคลเอนต์ผู้ออกใบรับรองการประทับเวลาแต่ไม่มี

• อาการ SignatureException พร้อมส่วนท้าย TSA client is required for level <x> but none was provided
• สาเหตุที่เป็นไปได้ การร้องขอ B-T, B-LT หรือ B-LTA ต้องมีไคลเอนต์ผู้ออกใบรับรองการประทับเวลา แต่ orchestrator ไม่มีไคลเอนต์นี้
• หลักฐาน / การวินิจฉัย factory SignatureException::tsaRequired() สร้างข้อความนี้; getContext() มี signature_level ที่พยายามใช้
• การแก้ไข

1. กำหนดค่าไคลเอนต์ผู้ออกใบรับรองการประทับเวลาและส่งไปยัง orchestrator
2. รันการเรียกใหม่อีกครั้ง
3. หากต้องการสร้างระดับที่ไม่ต้องมีการประทับเวลา ให้ร้องขอ B-B

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: URL ของปลายทางผู้ออกใบรับรองการประทับเวลาว่างเปล่า

• อาการ SignatureException พร้อมส่วนท้าย TSA endpoint URL is empty
• สาเหตุที่เป็นไปได้ ไคลเอนต์ผู้ออกใบรับรองการประทับเวลาถูกสร้างด้วย URL ของปลายทางที่ว่างเปล่า
• หลักฐาน / การวินิจฉัย factory SignatureException::tsaUrlEmpty() สร้างข้อความนี้ กรณีนี้เป็นข้อบกพร่องในการกำหนดค่า ไม่ใช่ความล้มเหลวของเครือข่าย
• การแก้ไข

1. ตั้ง URL ของปลายทางที่ไม่ว่างเปล่าบนไคลเอนต์ผู้ออกใบรับรองการประทับเวลา เช่น https://timestamp.example.com/tsa
2. หากระดับที่ร้องขอไม่จำเป็นต้องมีการประทับเวลา ให้นำการเชื่อมต่อไคลเอนต์ผู้ออกใบรับรองการประทับเวลาออกแทน
3. รันการเรียกอีกครั้ง

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: ตัวยึดตำแหน่งลายเซ็นขาดหายไปจากบัฟเฟอร์

• อาการ SignatureException พร้อมส่วนท้าย no /Contents <…> field found in PDF buffer (signature placeholder missing)
• สาเหตุที่เป็นไปได้ ขั้นตอนการเซ็นได้รับบัฟเฟอร์ที่ไม่มีคอนเทนเนอร์ลายเซ็นที่จองไว้ จึงไม่มีที่ให้เขียนลายเซ็น
• หลักฐาน / การวินิจฉัย factory SignatureException::signatureContentsNotFound() สร้างข้อความนี้
• การแก้ไข

1. ตรวจสอบให้แน่ใจว่าฟิลด์ลายเซ็นและตัวยึดตำแหน่งถูกเขียนก่อนที่ขั้นตอนการเซ็นจะทำงาน
2. รันไปป์ไลน์อีกครั้งเพื่อให้มีตัวยึดตำแหน่งอยู่แล้วเมื่อการเซ็นเริ่มต้น

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: สถานะการเพิกถอนไม่ทราบ (ผู้ตอบ OCSP ปฏิเสธ)

• อาการ SignatureException พร้อมส่วนท้าย OCSP responder returned non-successful OCSPResponseStatus "<status>"
• สาเหตุที่เป็นไปได้ ผู้ตอบ Online Certificate Status Protocol (OCSP) ไม่ได้คืนสถานะ successful จึงไม่ได้สร้างการยืนยันการเพิกถอน เอนจินปฏิบัติตาม RFC 6960 §4.2.1 ซึ่งอ้างไว้ในซอร์ส: เนื้อหาของการตอบกลับที่มีข้อมูลได้รับอนุญาตเฉพาะสำหรับสถานะ successful (0) เท่านั้น เอนจินจึงปฏิเสธที่จะถือว่าการตอบกลับที่ถูกปฏิเสธเป็นผลลัพธ์ที่เชื่อถือได้
• หลักฐาน / การวินิจฉัย factory SignatureException::nonSuccessfulOcspResponseStatus() สร้างข้อความนี้และระบุชื่อสถานะที่รายงาน เช่น tryLater หรือ internalError ไบต์สถานะที่สงวนไว้หรือไม่รู้จักจะสร้าง SignatureException::reservedOcspResponseStatus() แทน
• การแก้ไข

1. ระบุสถานะในข้อความ สำหรับสถานะชั่วคราว เช่น tryLater ให้ลองดึงข้อมูลการเพิกถอนอีกครั้งในภายหลัง
2. สำหรับ unauthorized หรือ malformedRequest ให้ตรวจสอบ URL คำขอ OCSP และใบรับรองที่ผู้ตอบคาดหวัง
3. อย่าระงับความล้มเหลวในการได้มาซึ่งสิ่งประดิษฐ์ B-LT หรือ B-LTA; การยืนยันการเพิกถอนเป็นส่วนหนึ่งของระดับเหล่านั้น

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: รายการในห่วงโซ่ใบรับรองถอดรหัสไม่สำเร็จ

• อาการ SignatureException พร้อมส่วนท้าย failed to base64-decode PEM body — input is not valid PEM
• สาเหตุที่เป็นไปได้ รายการในห่วงโซ่ใบรับรองไม่ใช่ Privacy-Enhanced Mail (PEM) ที่ถูกต้อง โดยทั่วไปเกิดจากการตัดทอน อักขระแปลกปลอม หรือ blob ไบนารี Distinguished Encoding Rules (DER) ที่ส่งมาในตำแหน่งที่คาดว่าจะเป็น PEM
• หลักฐาน / การวินิจฉัย factory SignatureException::pemDecodingFailed() สร้างข้อความนี้ระหว่างการประกอบห่วงโซ่
• การแก้ไข

1. ตรวจสอบใบรับรองแต่ละรายการในห่วงโซ่เพื่อหาอักขระแปลกปลอมหรือการตัดทอน
2. ส่งออกใบรับรองที่ได้รับผลกระทบใหม่ในรูปแบบ PEM
3. รันการเรียกเซ็นใหม่อีกครั้ง

• ที่เกี่ยวข้อง การเข้ารหัสลับและสิทธิ์

รายการ: ชนิดของคีย์ส่วนตัวไม่ตรงกับอัลกอริทึม

• อาการ SignatureException พร้อมส่วนท้าย expected private key of type "<x>" for the configured algorithm but got "<y>"
• สาเหตุที่เป็นไปได้ คีย์ส่วนตัวที่โหลดมาไม่ตรงกับอัลกอริทึมลายเซ็นที่กำหนดค่าไว้ เช่น ใช้คีย์ Rivest-Shamir-Adleman (RSA) กับ Elliptic Curve Digital Signature Algorithm (ECDSA)
• หลักฐาน / การวินิจฉัย factory SignatureException::unexpectedKeyType() สร้างข้อความนี้และระบุชื่อทั้งคลาสของคีย์ที่คาดหวังและที่เกิดขึ้นจริง
• การแก้ไข

1. ตรวจสอบว่าใบรับรองและคู่คีย์ตรงกับอัลกอริทึมที่เลือก
2. เปลี่ยนการเลือกอัลกอริทึมให้ตรงกับคีย์ หรือโหลดคีย์ที่ตรงกับอัลกอริทึม
3. รันการเรียกเซ็นอีกครั้ง

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: คีย์ Ed25519 หรือวัสดุลายเซ็นมีรูปแบบไม่ถูกต้อง

• อาการ SignatureException พร้อมส่วนท้ายที่ระบุความยาว Ed25519 ไม่ตรงกัน — ตัวอย่างเช่น Ed25519 signature length <n> ≠ expected 64 bytes หรือ Ed25519 round-trip self-verify failed
• สาเหตุที่เป็นไปได้ บิลด์การเข้ารหัสลับขณะรันไทม์คืนวัสดุคีย์หรือลายเซ็นที่มีความยาวไม่ถูกต้อง หรือลายเซ็นที่เพิ่งสร้างขึ้นตรวจสอบกับคีย์สาธารณะของตัวเองไม่ผ่าน เอนจินอ้าง RFC 8032 §3.4 ในซอร์ส ซึ่งกำหนดลายเซ็น Ed25519 แบบแยกไว้ที่ 64 ไบต์ เอนจินจึงยกเลิกแทนที่จะปล่อยวัสดุที่ตรวจสอบตัวเองไม่ได้ออกไป
• หลักฐาน / การวินิจฉัย factory ที่เกี่ยวข้องคือ SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed(), และ ::ed25519PublicKeyInvalid() แต่ละตัวระบุชื่อความยาวที่สังเกตได้
• การแก้ไข

1. ติดตั้งส่วนขยาย libsodium PHP ใหม่; บิลด์ที่ถูกตัดทอนหรือเสียหายเป็นสาเหตุที่บันทึกไว้ของวัสดุที่มีความยาวไม่ถูกต้อง
2. ยืนยันว่าคีย์เป็นคีย์ Ed25519 และ OpenSSL เป็นเวอร์ชัน 1.1.1 หรือใหม่กว่า
3. รันการเรียกเซ็นใหม่อีกครั้ง

• ที่เกี่ยวข้อง การอ้างอิง Exception

รายการ: ดิกชันนารีการประทับเวลาแบบจัดเก็บถาวรไม่ได้ถูกปล่อยออกมา

• อาการ SignatureException พร้อมส่วนท้าย no /Type /DocTimeStamp dictionary was emitted into the PDF buffer
• สาเหตุที่เป็นไปได้ ลูปการจัดเก็บถาวร B-LTA ทำงานแล้ว แต่ดิกชันนารีการประทับเวลาเอกสารไม่เคยไปถึงบัฟเฟอร์ สิ่งประดิษฐ์จะเป็น B-LTA ที่เขียนไม่ครบ เอนจินจึงปฏิเสธที่จะคืนค่า
• หลักฐาน / การวินิจฉัย factory SignatureException::documentTimestampNotEmitted() สร้างข้อความนี้ ความล้มเหลวของเงื่อนไขภายหลังนี้ถูกยกขึ้นตอนสรุปขั้นสุดท้าย
• การแก้ไข

1. ถือว่าเอาต์พุตถูกทิ้ง; อย่าจัดส่งสิ่งประดิษฐ์บางส่วน
2. รันไปป์ไลน์ B-LTA อีกครั้งด้วยผู้ออกใบรับรองการประทับเวลาที่เข้าถึงได้
3. หากความล้มเหลวเกิดซ้ำ ให้บันทึก getContext() และ exception ก่อนหน้าที่เชื่อมโยงกันไว้สำหรับรายงานข้อบกพร่อง

• ที่เกี่ยวข้อง การอ้างอิง Exception

กรณีขอบและข้อควรระวัง

• factory เหล่านี้ตั้ง cert_info เป็นชื่อเจ้าของหรือลายนิ้วมือเฉพาะเมื่อมีข้อมูลดังกล่าว; cert_info ที่ว่างเปล่าเป็นสิ่งที่คาดหมายได้สำหรับความล้มเหลวด้านความสามารถและการกำหนดค่า
• การร้องขอ B-LT หรือ B-LTA โดยไม่มีไคลเอนต์ Hypertext Transfer Protocol (HTTP) ที่กำหนดค่าไว้จะยก SignatureException::httpClientMissing(); การดึงข้อมูลการเพิกถอนต้องมีไคลเอนต์ PHP Standards Recommendation (PSR)-18 ที่ส่งไปยัง orchestrator
• ใบรับรองที่รองรับด้วย hardware security module (HSM) แต่ไม่มีการนำ signer ไปใช้จะยก SignatureException::hsmSignerMissing(); เชื่อม signer เข้ากับใบรับรองก่อนการเซ็น

ดูเพิ่มเติม

• การอ้างอิง Exception
• การเข้ารหัสลับและสิทธิ์
• ดัชนีฐานความรู้

อภิธานศัพท์: ระดับ PAdES · การยืนยันการเพิกถอน