Khắc phục sự cố: lỗi chữ ký và dấu thời gian

Phạm vi

Các mục này đề cập đến các lỗi chữ ký phát sinh qua NextPDF\Exception\SignatureException và NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException. Mỗi mục nêu rõ phương thức factory hoặc lớp tương ứng, để bạn có thể xác nhận nguyên nhân từ thông báo và getContext() thay vì suy đoán.

Lưu ý về cách diễn đạt: engine không chứng thực rằng một chữ ký hợp lệ hay một tài liệu được bảo vệ. Nó chỉ báo cáo lỗi phát hiện được. Hãy xem mỗi cách khắc phục là một bước để loại bỏ nguyên nhân đã được báo cáo.

Mục: không thể tạo cấp độ PAdES “B-LT” hoặc “B-LTA”

• Triệu chứng. SignatureException với phần đuôi thông báo nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Nguyên nhân có thể. Thiếu nhà cung cấp năng lực xác thực dài hạn. B-LT và B-LTA nhúng tài liệu thu hồi cùng một dấu thời gian lưu trữ; nhà cung cấp này nằm trong nextpdf/enterprise.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::ltvCapabilityMissing() tạo ra đúng thông báo này. getContext() trả về signature_level, được đặt thành cấp độ bạn đã thử.
• Cách khắc phục.
  1. Cài đặt nhà cung cấp bằng cách chạy composer require nextpdf/enterprise.
  2. Chạy lại lệnh ký.
  3. Nếu không thể cài đặt nhà cung cấp, hãy yêu cầu B-B hoặc B-T thay thế; đây là các cấp độ mà gói core có thể tạo.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: cấp độ chữ ký không thể đạt được và lệnh gọi bị từ chối

• Triệu chứng. SignatureLevelUnreachableException với thông báo theo dạng PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Nguyên nhân có thể. Cấp độ tuân thủ được yêu cầu cần hạ tầng không có sẵn tại thời điểm ký, thường gặp nhất là cơ quan cấp dấu thời gian cho B-T trở lên. Engine thất bại theo hướng đóng: nó không âm thầm hạ cấp rồi quảng bá cấp độ cao hơn.
• Bằng chứng / chẩn đoán. getContext() trả về requestedLevel, highestAchievableLevel, và reason. Trường reason xác định phần hạ tầng còn thiếu. Đây là mặc định thất bại theo hướng đóng, nhằm ngăn tài liệu tuyên bố một cấp độ mà nó không đáp ứng.
• Cách khắc phục.
  1. Đọc trường reason để xác định hạ tầng còn thiếu.
  2. Cung cấp thành phần còn thiếu. Ví dụ, cấu hình một cơ quan cấp dấu thời gian, rồi chạy lại lệnh gọi.
  3. Để chủ động chấp nhận một cấp độ thấp hơn, hãy truyền allowDegradation: true vào PadesOrchestrator. Khi đó, lệnh gọi tạo ra highestAchievableLevel và báo cáo cấp độ đã tạo.
• Liên quan. Mã hóa và quyền.

Mục: cần ứng dụng khách cơ quan cấp dấu thời gian nhưng không có

• Triệu chứng. SignatureException với phần đuôi TSA client is required for level <x> but none was provided.
• Nguyên nhân có thể. Một yêu cầu B-T, B-LT hoặc B-LTA cần ứng dụng khách cơ quan cấp dấu thời gian, nhưng bộ điều phối không có ứng dụng khách nào.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::tsaRequired() tạo ra thông báo này; getContext() mang theo signature_level đã thử.
• Cách khắc phục.
  1. Cấu hình một ứng dụng khách cơ quan cấp dấu thời gian và truyền vào bộ điều phối.
  2. Chạy lại lệnh gọi.
  3. Để tạo một cấp độ không cần dấu thời gian, hãy yêu cầu B-B.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: URL điểm cuối của cơ quan cấp dấu thời gian bị rỗng

• Triệu chứng. SignatureException với phần đuôi TSA endpoint URL is empty.
• Nguyên nhân có thể. Ứng dụng khách cơ quan cấp dấu thời gian được tạo với URL điểm cuối rỗng.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::tsaUrlEmpty() tạo ra thông báo này. Đây là một lỗi cấu hình, không phải lỗi mạng.
• Cách khắc phục.
  1. Đặt một URL điểm cuối không rỗng cho ứng dụng khách cơ quan cấp dấu thời gian, chẳng hạn https://timestamp.example.com/tsa.
  2. Nếu cấp độ được yêu cầu không cần đóng dấu thời gian, hãy gỡ phần đấu nối ứng dụng khách cơ quan cấp dấu thời gian.
  3. Chạy lại lệnh gọi.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: thiếu chỗ giữ chỗ chữ ký trong vùng đệm

• Triệu chứng. SignatureException với phần đuôi no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Nguyên nhân có thể. Giai đoạn ký nhận được vùng đệm không có hộp chứa chữ ký dành riêng, nên không có vị trí để ghi chữ ký.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::signatureContentsNotFound() tạo ra thông báo này.
• Cách khắc phục.
  1. Đảm bảo trường chữ ký và chỗ giữ chỗ của nó được ghi trước khi giai đoạn ký chạy.
  2. Chạy lại pipeline để chỗ giữ chỗ đã tồn tại khi quá trình ký bắt đầu.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: trạng thái thu hồi không xác định (trình phản hồi OCSP từ chối)

• Triệu chứng. SignatureException với phần đuôi OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Nguyên nhân có thể. Trình phản hồi Giao thức trạng thái chứng thư trực tuyến (OCSP) không trả về trạng thái successful, nên không tạo ra khẳng định thu hồi nào. Engine tuân theo RFC 6960 §4.2.1, như được trích dẫn trong mã nguồn: thân phản hồi có nội dung chỉ được phép với trạng thái successful (0). Engine từ chối xem một phản hồi bị từ chối là kết quả tin cậy tích cực.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::nonSuccessfulOcspResponseStatus() tạo ra thông báo này và nêu tên trạng thái được báo cáo, chẳng hạn tryLater hoặc internalError. Thay vào đó, một byte trạng thái dành riêng hoặc không xác định sẽ tạo ra SignatureException::reservedOcspResponseStatus().
• Cách khắc phục.
  1. Xác định trạng thái trong thông báo. Với trạng thái tạm thời như tryLater, hãy thử lấy lại thông tin thu hồi sau.
  2. Đối với unauthorized hoặc malformedRequest, hãy xác minh URL yêu cầu OCSP và chứng thư mà trình phản hồi mong đợi.
  3. Đừng chặn lỗi để cố thu được một artifact B-LT hoặc B-LTA; khẳng định thu hồi là một phần của cấp độ đó.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: một mục trong chuỗi chứng thư không giải mã được

• Triệu chứng. SignatureException với phần đuôi failed to base64-decode PEM body — input is not valid PEM.
• Nguyên nhân có thể. Một mục trong chuỗi chứng thư không phải là Privacy-Enhanced Mail (PEM) hợp lệ, thường do bị cắt cụt, có ký tự lạc lõng, hoặc do một blob Distinguished Encoding Rules (DER) nhị phân được cung cấp ở nơi mong đợi PEM.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::pemDecodingFailed() tạo ra thông báo này trong quá trình lắp ráp chuỗi.
• Cách khắc phục.
  1. Kiểm tra từng chứng thư trong chuỗi để phát hiện ký tự lạc lõng hoặc phần bị cắt cụt.
  2. Xuất lại chứng thư bị ảnh hưởng ở dạng PEM.
  3. Chạy lại lệnh ký.
• Liên quan. Mã hóa và quyền.

Mục: loại khóa riêng không khớp với thuật toán

• Triệu chứng. SignatureException với phần đuôi expected private key of type "<x>" for the configured algorithm but got "<y>".
• Nguyên nhân có thể. Khóa riêng được nạp không khớp với thuật toán chữ ký đã cấu hình, chẳng hạn dùng khóa Rivest-Shamir-Adleman (RSA) với lựa chọn Elliptic Curve Digital Signature Algorithm (ECDSA).
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::unexpectedKeyType() tạo ra thông báo này và nêu tên cả lớp khóa mong đợi lẫn lớp khóa thực tế.
• Cách khắc phục.
  1. Xác minh rằng cặp chứng thư và khóa khớp với thuật toán bạn đã chọn.
  2. Thay đổi lựa chọn thuật toán để khớp với khóa, hoặc nạp khóa khớp với thuật toán.
  3. Chạy lại lệnh ký.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: vật liệu khóa hoặc chữ ký Ed25519 bị hỏng định dạng

• Triệu chứng. SignatureException với phần đuôi nêu một sai lệch độ dài Ed25519 — ví dụ Ed25519 signature length <n> ≠ expected 64 bytes, hoặc Ed25519 round-trip self-verify failed.
• Nguyên nhân có thể. Bản dựng mật mã của môi trường chạy đã trả về vật liệu khóa hoặc chữ ký sai độ dài, hoặc một chữ ký vừa được tạo không vượt qua bước xác minh bằng chính khóa công khai của nó. Engine trích dẫn RFC 8032 §3.4 trong mã nguồn; điều này ấn định chữ ký Ed25519 tách rời ở mức 64 byte. Engine hủy bỏ thay vì phát ra vật liệu mà nó không thể tự xác minh.
• Bằng chứng / chẩn đoán. Các phương thức factory liên quan là SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed(), và ::ed25519PublicKeyInvalid(). Mỗi phương thức nêu tên độ dài quan sát được.
• Cách khắc phục.
  1. Cài đặt lại tiện ích mở rộng PHP libsodium; bản dựng bị lược bỏ hoặc bị hỏng là nguyên nhân đã được ghi nhận của vật liệu sai độ dài.
  2. Xác nhận khóa là một khóa Ed25519 và OpenSSL ở phiên bản 1.1.1 trở lên.
  3. Chạy lại lệnh ký.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Mục: không ghi ra từ điển dấu thời gian lưu trữ

• Triệu chứng. SignatureException với phần đuôi no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Nguyên nhân có thể. Vòng lặp lưu trữ B-LTA đã chạy, nhưng từ điển dấu thời gian tài liệu chưa bao giờ được ghi vào vùng đệm. Artifact sẽ là một B-LTA bị ghi dở dang, nên engine từ chối trả về nó.
• Bằng chứng / chẩn đoán. Phương thức factory SignatureException::documentTimestampNotEmitted() tạo ra thông báo này. Lỗi hậu điều kiện này được nêu tại thời điểm hoàn tất.
• Cách khắc phục.
  1. Hãy coi đầu ra là đã bị loại bỏ; đừng phân phối artifact dở dang.
  2. Chạy lại pipeline B-LTA với cơ quan cấp dấu thời gian có thể truy cập được.
  3. Nếu lỗi lặp lại, hãy ghi lại getContext() và ngoại lệ trước đó trong chuỗi để lập báo cáo lỗi.
• Liên quan. Tài liệu tham khảo ngoại lệ.

Các trường hợp đặc biệt & lưu ý

• Các phương thức factory này đặt cert_info thành một chủ thể hoặc dấu vân tay chỉ khi có sẵn; cert_info rỗng là điều dự kiến đối với lỗi về năng lực và cấu hình.
• Một yêu cầu B-LT hoặc B-LTA mà không có ứng dụng khách Hypertext Transfer Protocol (HTTP) được cấu hình sẽ nêu ra SignatureException::httpClientMissing(); việc lấy thông tin thu hồi cần một ứng dụng khách PHP Standards Recommendation (PSR)-18 được truyền vào bộ điều phối.
• Một chứng thư được hỗ trợ bởi mô-đun bảo mật phần cứng (HSM) nhưng không có bản hiện thực bộ ký sẽ nêu ra SignatureException::hsmSignerMissing(); hãy đấu nối bộ ký vào chứng thư trước khi ký.

Xem thêm

• Tài liệu tham khảo ngoại lệ
• Mã hóa và quyền
• Mục lục cơ sở tri thức

Bảng thuật ngữ: cấp độ PAdES · khẳng định thu hồi