Lỗi bảo mật và ký

Nhìn nhanh

Trang này lập tài liệu cho các ngoại lệ thuộc lĩnh vực bảo mật trong cây không gian tên NextPDF\Security. Mỗi mục nêu tên lớp, cho biết khi nào nó được ném, liệt kê các trường mà getContext() của nó trả về, và đưa ra một bước khôi phục.

Hầu hết các lớp này mở rộng SecurityException, vốn mở rộng NextPdfException và hiện thực ContextAwareExceptionInterface. Điều đó có nghĩa getContext(): array trả về các chẩn đoán có cấu trúc, không chứa bí mật mà bạn có thể định tuyến tới các đường ghi nhật ký hoặc giám sát hiệu năng ứng dụng (APM). Bắt SecurityException để chặn mọi lỗi thuộc lĩnh vực bảo mật trong một khối; bắt một lớp con cụ thể khi bạn cần payload có kiểu của nó.

Một vài lớp trong cây này mở rộng trực tiếp RuntimeException thay vì SecurityException. Chúng được đánh dấu bên dưới; chúng không phơi bày getContext(), và hầu hết được lập tài liệu như các tín hiệu điều khiển luồng nội bộ mà bạn không nên kỳ vọng bắt được trong mã ứng dụng.

Quy ước trường context

Khía cạnh	Hành vi
Hợp đồng cơ sở	NextPdfException::getContext() trả về []; các lớp con ghi đè nó.
Vệ sinh bí mật	Thông báo và context bỏ qua vật liệu khóa thô, plaintext, mã PIN, và các byte của vector khởi tạo (IV). Khóa chỉ được phơi bày dưới dạng một tiền tố vân tay.
SecurityException	Lớp cơ sở trừu tượng; không mang trường nào của riêng nó. Các lớp con định nghĩa payload.

Kiểu cơ sở

SecurityException

• Khi nào nó được ném. Không bao giờ ném trực tiếp; nó là lớp cơ sở trừu tượng cho lĩnh vực bảo mật. Nó tồn tại để một khối catch (SecurityException $e) duy nhất có thể chặn các lỗi toàn vẹn mã hóa-xác thực, các phòng vệ tái sử dụng nonce, ràng buộc PDF/A-với-mã-hóa, lỗi quản lý khóa, và các lỗi PKI.
• Trường context. Không có trường nào của riêng nó. Kế thừa giá trị mặc định rỗng từ NextPdfException; các lớp con điền payload.
• Khôi phục. Bắt lớp con cụ thể để xử lý có thể hành động, hoặc SecurityException để định tuyến sự cố bảo mật ở mức thô.

Lỗi mã hóa và mã hóa-xác thực

Những lỗi này được nêu ra bởi bộ mã hóa AES-GCM (Galois/Counter Mode) và bộ bảo vệ PDF/A. Để biết hướng dẫn ưu tiên triệu chứng, xem Mã hóa và quyền.

DecryptionFailedException

• Khi nào nó được ném. Một lần giải mã mã hóa-xác thực-kèm-dữ-liệu-liên-kết (AEAD) thất bại vì một lý do không phải giả mạo: ciphertext bị cắt cụt, thiếu một IV, hoặc một khóa sai được cung cấp tại ranh giới API, nơi không đủ vật liệu để bước kiểm tra toàn vẹn thực sự chạy được. Đây là một lỗi cấu hình hoặc truyền tải, không phải một sự cố bảo mật.
• Trường context. algorithm (ví dụ AES-256-GCM), reason (ví dụ ciphertext shorter than IV+tag).
• Khôi phục. Kiểm tra ciphertext, IV, và khóa đã đầy đủ và được đóng khung đúng; đừng coi đây là giả mạo. So với TamperedDataException.

TamperedDataException

• Khi nào nó được ném. Tag xác thực AEAD thất bại khi xác minh. Tag bao phủ ciphertext cộng dữ liệu được xác thực liên kết (AAD); nếu một trong hai bị sửa đổi sau khi mã hóa, lệnh openssl_decrypt() nền trả về false. Lớp con riêng biệt này cho phép bạn phơi bày một cảnh báo cấp-sự-cố-bảo-mật thay vì một lỗi đóng khung.
• Trường context. algorithm, ciphertext_length (độ dài của ciphertext bị từ chối, không tính IV và tag).
• Khôi phục. Coi đây là giả mạo hoặc một khóa/IV sai. Đừng thử lại một cách mù quáng; điều tra nguồn của ciphertext. Theo ISO/TS 32003:2023 §5.2 và NIST SP 800-38D §6.5, một kiểm tra tag thất bại có nghĩa dữ liệu không xác thực.

NonceReuseException

• Khi nào nó được ném. AES-GCM được yêu cầu mã hóa hai lần với cùng một cặp khóa và IV. Bộ mã hóa phòng vệ bằng một bộ đếm đơn điệu trên-từng-thể-hiện và, như phòng thủ theo chiều sâu, một hash-set tại môi trường chạy gồm mọi cặp (vân tay khóa, IV) đã phát ra. Vì bộ đếm loại trừ va chạm theo thiết kế, lần kích hoạt này là một chỉ báo lỗi mức-ưu-tiên-cao mà không bao giờ được xảy ra trong sản xuất. Tái sử dụng một cặp khóa/IV làm tổn hại toàn bộ keystream (ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
• Trường context. key_fingerprint_prefix (8 ký tự hex đầu của SHA-256(key)), iv_length (luôn là 12 cho ISO/TS 32003), reason (hashset-collision hoặc counter-rollover, phân biệt một lỗi refactor làm hỏng bộ đếm với cái bẫy bộ đếm 2^63), và iv_fixed_field_hex (trường cố định của IV, chỉ hiện diện khi được cung cấp, được báo cáo dưới khóa riêng của nó và không bao giờ bị gán nhầm là vân tay khóa).
• Khôi phục. Hủy bỏ ngay lập tức và xoay vòng khóa. Gửi một báo cáo lỗi; điều này cho thấy một lỗi trong bộ mã hóa, không phải đầu vào tệ của caller.

GcmInvocationLimitExceededException

• Khi nào nó được ném. Đạt tới một số đếm lệnh gọi an-toàn-khi-dùng theo opt-in của NIST SP 800-38D §8.3 cho một khóa AES-GCM nhất định. Đây là một hook telemetry phòng-thủ-theo-chiều-sâu cho các caller muốn thực thi giới hạn được spec khuyến nghị (khoảng 2^32 lệnh gọi mỗi khóa) sớm hơn các giới hạn kiến trúc bên trong bộ mã hóa. Nó không kích hoạt theo mặc định; chỉ helper assertWithinSafetyBound() nêu nó ra.
• Trường context. key_fingerprint_prefix, invocation_count (số đếm encrypt() hiện tại, tại hoặc trên giới hạn), invocation_limit (giới hạn opt-in).
• Khôi phục. Xoay vòng khóa tài liệu (dựng một bộ mã hóa mới với vật liệu khóa mới) trước khi xác suất tích lũy của va chạm và giả mạo không còn không đáng kể, hoặc mở rộng chính sách của caller để từ chối tiếp tục phục vụ.

IncompatiblePdfAModeException

• Khi nào nó được ném. Một thao tác mã hóa được thử trên một tài liệu được gắn thẻ PDF/A. Họ PDF/A (PDF/A-2, PDF/A-3, PDF/A-4) đồng nhất cấm mã hóa: theo ISO 19005 §6.1.3 khóa Encrypt không được hiện diện trong trailer, và ISO 19005-4:2020 Phụ lục A và B kế thừa điều này không có thay đổi. Không có tổ hợp PDF/A và mã hóa nào được phép.
• Trường context. pdfa_mode (ví dụ pdfa4, pdfa3), encryption_operation (lệnh gọi bị từ chối, ví dụ useAesGcm).
• Khôi phục. Để tạo một tài liệu được mã hóa, bỏ lời gọi enablePdfA(); để tạo một tài liệu lưu trữ, bỏ lời gọi mã hóa. Xem Xác thực PDF/A và PDF/UA.

Thực thi chính sách mật mã

CryptoPolicyViolationException

• Khi nào nó được ném. Một chính sách mật mã được cấu hình từ chối một thuật toán, độ mạnh khóa, hoặc cipher được chọn bởi một thao tác ký, mã hóa, hoặc băm của core. Nó là ranh giới thất-bại-theo-hướng-đóng cho việc thực thi tuân thủ (ví dụ FIPS 140-2/3, eIDAS, hoặc chính sách doanh nghiệp tùy biến) và được nêu ra bởi CryptoPolicyEnforcer trước khi bất kỳ chữ ký hay ciphertext nào được tạo, nên một thao tác vi phạm chính sách không bao giờ có thể phát ra một artifact không được phê duyệt. Khác với một lỗi thao tác OpenSSL hẹp và với một lỗi primitive ký: đây là một sự từ chối theo chính sách đối với một yêu cầu vốn hợp lệ. Phù hợp với NIST SP 800-131A Rev. 2 và ISO/IEC 19790:2025 §7.
• Trường context. policy (tên chính sách, ví dụ FIPS 140-3 Strict), category (hash, signature, encryption, hoặc key-strength), item (mục bị từ chối, ví dụ một định danh đối tượng (OID), tên cipher, hoặc rsa/1024), reason.
• Khôi phục. Chọn một thuật toán, độ dài khóa, hoặc cipher mà chính sách được nêu tên phê duyệt, hoặc điều chỉnh chính sách nếu bạn sở hữu nó. Định tuyến context có cấu trúc tới runbook tuân thủ đã được lập tài liệu.

Quản lý khóa

Tồn tại hai lớp cùng tên. Chúng chia sẻ gốc SecurityException nên một khối catch (SecurityException $e) bắt được cả hai, nhưng chúng mang payload khác nhau. Hãy import theo tên đầy đủ khi bạn cần một hình dạng cụ thể.

KeyManagementException (vòng đời: NextPDF\Security\Exception)

• Khi nào nó được ném. Một thao tác quản lý khóa thất bại trước khi khóa được tiêu thụ bởi một primitive ký hoặc mã hóa: lỗi phân tích khóa Privacy-Enhanced Mail (PEM), PKCS#12, hoặc PKCS#11; lỗi dẫn xuất khóa (HKDF, PBKDF2, scrypt); từ chối AES Key Wrap (RFC 3394) trên một khóa mã hóa khóa sai; một module bảo mật phần cứng (HSM) trả về Distinguished Encoding Rules (DER) bị hỏng khuôn; hoặc một sai lệch độ dài seed Ed25519.
• Trường context. operation (ví dụ load_pem, kek_derive, key_wrap), key_type (ví dụ RSA, EC-P256, Ed25519, AES-256), reason. Vật liệu khóa thô không bao giờ được bao gồm.
• Khôi phục. Kiểm tra thao tác và kiểu khóa được nêu tên, sửa vật liệu khóa nguồn hoặc đầu vào dẫn xuất, và thử lại.

KeyManagementException (đường ký: NextPDF\Security\Signature\Exception)

• Khi nào nó được ném. Một signer provider gặp lỗi quản lý khóa: phiên bản khóa được yêu cầu không xác định, bị tắt, được lên lịch hủy, thiếu quyền ký, hoặc bằng cách khác không dùng được. Đây là cái mà RsaPssSigner và LocalKeySignerProvider ném ra khi lỗi khóa trực tiếp. Các constructor có tên: unknownKeyVersion() và keyVersionDisabled().
• Trường context. providerId, keyVersion, reason. Các accessor: providerId(), keyVersion(), reason().
• Khôi phục. Xoay vòng hoặc cấp lại quyền cho khóa, hoặc chọn một phiên bản khóa dùng được, rồi thử lại. Khác với SignatureFailedException, vốn báo hiệu rằng primitive ký tự nó thất bại.

Ký

Để biết hướng dẫn ưu tiên triệu chứng về các cấp độ không thể đạt và năng lực còn thiếu, xem Lỗi chữ ký và dấu thời gian.

SignatureFailedException (R4-13: NextPDF\Security\Exception)

• Khi nào nó được ném. Một thao tác ký mật mã thất bại: một primitive ký RSA, ECDSA, hoặc Ed25519 trả về false hoặc output sai độ dài; một HSM hoặc token PKCS#11 phản hồi với trạng thái không-thành-công; việc lắp ráp Cryptographic Message Syntax (CMS) SignedData thất bại trên một chứng thư hoặc chuỗi bị hỏng khuôn; hoặc một bước tự-xác-minh round-trip Ed25519 thất bại. Mã mới nên ưu tiên lớp con R4-13 này hơn ngoại lệ chữ ký gắn-PAdES cũ.
• Trường context. operation (ví dụ sign, verify, build_cms), algorithm (ví dụ rsa-pkcs1v15-sha256, ed25519), reason. Các accessor: getOperation(), getAlgorithm(), getReason().
• Khôi phục. Đọc thao tác và thuật toán, sửa đầu vào (khóa, chuỗi chứng thư, hoặc tính sẵn sàng của backend), và thử lại. Phù hợp với tư thế xử lý khóa thất-bại-theo-hướng-đóng của ETSI EN 319 142-1.

SignatureFailedException (SPI: NextPDF\Security\Signature\Exception)

• Khi nào nó được ném. Một bản hiện thực SignerProviderInterface không thể hoàn tất một thao tác ký vì bất kỳ lý do nào không được phân loại là quản lý khóa: lỗi driver backend, vật liệu khóa bị hỏng khuôn, hoặc I/O HSM không khôi phục được. Đây là trường hợp bắt-tất-cả cho hợp đồng ký thất-bại-theo-hướng-đóng, nơi mỗi primitive ném khi thất bại thay vì trả về null, false, hoặc một chuỗi rỗng. Constructor có tên: forProvider().
• Trường context. providerId, reason. Các accessor: providerId(), reason().
• Khôi phục. Kiểm tra provider id và reason, sửa backend của provider hoặc vật liệu khóa, và thử lại. Rẽ nhánh theo KeyManagementException so với kiểu này để tách “khóa bị tệ” với “primitive thất bại”.

SignatureLevelUnreachableException

• Khi nào nó được ném. Cấp độ tuân thủ PAdES được yêu cầu không thể được đáp ứng dưới hạ tầng môi trường chạy hiện tại (thường nhất là thiếu một cơ quan cấp dấu thời gian cho B-T trở lên) và caller chưa cấp phép suy giảm. Mặc định là thất-bại-theo-hướng-đóng: engine từ chối thay vì âm thầm tạo ra một cấp độ thấp hơn trong khi quảng bá cấp độ cao hơn, điều sẽ là một sự thoái lui cấp-eIDAS. Phù hợp với ETSI EN 319 142-1 §6. Lưu ý lớp này mở rộng NextPdfException trực tiếp (không phải SecurityException).
• Trường context. requestedLevel, highestAchievableLevel, reason. Các accessor: requestedLevel(), highestAchievableLevel(), reason().
• Khôi phục. Đọc reason để xác định hạ tầng còn thiếu và cung cấp nó (ví dụ cấu hình một cơ quan cấp dấu thời gian), hoặc truyền allowDegradation: true vào PadesOrchestrator để chủ động chấp nhận cấp độ cao nhất có thể đạt.

SignerProviderNotFoundException

• Khi nào nó được ném. SignerProviderRegistry::get() được yêu cầu một provider id không được đăng ký. Hiện thực PSR-11 NotFoundExceptionInterface, nên registry tuân theo hợp đồng container PSR-11. Constructor có tên: forId(). Lớp này mở rộng RuntimeException và không phơi bày getContext().
• Trường context. Không có. Id chưa đăng ký xuất hiện trong thông báo.
• Khôi phục. Đăng ký provider dưới id mong đợi trước khi yêu cầu nó, hoặc sửa id bạn truyền vào registry.

Băm (SHAKE256)

Những lớp này mở rộng RuntimeException và không phơi bày getContext(). SHAKE256 là hàm output-mở-rộng SHA-3 mà một số đường ISO/TS 32001 yêu cầu.

Shake256NotAvailableException

• Khi nào nó được ném. Tại lúc băm, khi provider được chọn không thể đáp ứng yêu cầu. Các constructor có tên: noBackend() (không có backend SHAKE256 hoạt động trên host này, qua mọi tier đã thử) và ffiCallFailed() (một lệnh OpenSSL EVP gắn-FFI trả về trạng thái không-thành-công, ví dụ từ một bản dựng libcrypto bị lược bỏ).
• Trường context. Không có. Thông báo nêu tên các tier đã thử hoặc symbol thất bại.
• Khôi phục. Cài đặt ext-ffi với OpenSSL 3.x hiện diện, hoặc nâng cấp lên một bản dựng PHP phơi bày shake256 trong hash_algos(). Một phương án dự phòng Keccak ở userland được cố ý không cung cấp.

Shake256ProviderNotAvailableException

• Khi nào nó được ném. Từ một constructor của provider SHAKE256 khi bước thăm dò năng lực thất bại, nên provider không thể được khởi tạo. Nó là một tín hiệu điều khiển luồng: registry provider bắt nó, ghi lại nhãn tier, và thử tier kế tiếp. Nó không bao giờ được lọt vào mã ứng dụng. Constructor có tên: forTier().
• Trường context. Không có. Thông báo nêu tên tier và lý do.
• Khôi phục. Không thể hành động trực tiếp bởi caller; nếu toàn bộ chuỗi tier bị cạn kiệt, registry phơi bày Shake256NotAvailableException::noBackend() thay thế, vốn mang cách sửa hướng tới người vận hành.

Toàn vẹn MAC tài liệu (ISO/TS 32004)

Những lớp này bao quát mã xác thực thông báo (MAC) cấp-tài-liệu ISO/TS 32004, lưu dưới /AuthCode. Cả hai đều mở rộng NextPdfException và ghi đè getContext().

DocumentMacTokenException

• Khi nào nó được ném. Thất-bại-theo-hướng-đóng, bởi trình đọc MAC token, khi một CMS AuthenticatedData MAC token bị hỏng khuôn về cấu trúc hoặc khai báo một thuật toán ngoài tập ISO/TS 32004 đã thống nhất. Các constructor có tên: malformed() và algorithmMismatch(). Đánh dấu @internal.
• Trường context. status (giá trị DocumentMacVerificationStatus, hoặc là MalformedToken hoặc AlgorithmMismatch). Thuộc tính công khai chỉ đọc: $status.
• Khôi phục. Coi tài liệu là chưa được xác minh. Một token bị hỏng khuôn hoặc một thuật toán ngoài tập đã thống nhất có nghĩa MAC không thể thiết lập sự tin cậy; đừng tiến hành như thể nội dung được bảo vệ.

DocumentMacVerificationException

• Khi nào nó được ném. Thất-bại-theo-hướng-đóng, khi một xác minh MAC cấp-tài-liệu không thể đạt một trạng thái tin cậy: một /AuthCode thiếu hoặc bị hỏng khuôn, một thuật toán ngoài tập đã thống nhất, một lỗi unwrap, hoặc một sai khớp MAC (giả mạo). Lệnh verify() của trình xác minh trả về một kết quả tường minh để rẽ nhánh; đây là đối tác theo luồng-ngoại-lệ được ném bởi assertVerified() nên mã “tin cậy nội dung” không bao giờ có thể tiến qua một tài liệu chưa được xác minh. Constructor có tên: fromResult().
• Trường context. status (giá trị DocumentMacVerificationStatus). Thuộc tính công khai chỉ đọc: $status.
• Khôi phục. Đừng tin cậy nội dung tài liệu. Kiểm tra status để phân biệt một giả mạo (sai khớp MAC) với một vấn đề cấu hình (một /AuthCode thiếu hoặc bị hỏng khuôn, một sai khớp thuật toán).

Xác thực đường dẫn PKI (RFC 5280)

Những lớp này bao quát xác thực đường dẫn chứng thực RFC 5280. Kiểu cơ sở và các lớp con của nó đều thất-bại-theo-hướng-đóng.

PkiPathValidationException

• Khi nào nó được ném. Một lỗi chế-độ-nghiêm-ngặt từ trình xác thực đường dẫn RFC 5280. Nó là lớp cơ sở không-cuối-cùng cho các lớp con hẹp hơn (ChainLengthExceededException, UnsupportedExtensionException), nên các trình xử lý bắt kiểu này cũng bắt các lớp đó qua thay thế Liskov. Mở rộng SecurityException.
• Trường context. Không ghi đè getContext() (kế thừa giá trị mặc định rỗng). Mang các lý do có cấu trúc trong thuộc tính mảng công khai chỉ đọc đã đông cứng $reasons (một danh sách không rỗng gồm các chuỗi tên-quy-tắc cộng mô tả).
• Khôi phục. Đọc $reasons để xác định quy tắc thất bại, sửa chuỗi chứng thư, và xác thực lại. Bắt kiểu này để xử lý mọi lỗi xác-thực-đường-dẫn một cách đồng nhất.

ChainLengthExceededException

• Khi nào nó được ném. Trình xác thực đường dẫn được yêu cầu duyệt một chuỗi có độ dài vượt quá trần được cấu hình. Giới hạn được thực thi trước khi bắt đầu bất kỳ phân tích nào, nên một nhà cung cấp độc hại không thể đẩy trình xác thực vào công việc bậc hai hoặc làm cạn kiệt tài nguyên với một chuỗi sâu tùy ý. Trần mặc định là 10 tuân theo profile PKIX-CMP (RFC 4210 §5.3.18); các chuỗi trong thực tế nằm gọn trong 5 đến 6 mục. Lớp con của PkiPathValidationException.
• Trường context. Kế thừa getContext() rỗng; chuỗi lý do chain_length_exceeded: supplied=<n> cap=<n> được chuyển vào $reasons của lớp cha. Các thuộc tính công khai chỉ đọc: $supplied, $cap.
• Khôi phục. Cung cấp một chuỗi nằm trong trần, hoặc nâng giới hạn được cấu hình nếu một chuỗi dài hơn một cách chính đáng được mong đợi.

UnsupportedExtensionException

• Khi nào nó được ném. Trình xác thực đường dẫn gặp một phần mở rộng X.509 quan trọng có việc thực thi chưa được hiện thực. Theo RFC 5280 §4.2, một phần mở rộng quan trọng không nhận diện được phải thất bại theo hướng đóng; cả chế độ nghiêm ngặt lẫn nới lỏng đều thất bại theo hướng đóng ở đây, vì âm thầm bỏ qua một phần mở rộng quan trọng sẽ là một sự thoái lui bảo mật. Trình xác thực bao quát dựng chuỗi, khớp AKI/SKI, key usage, extended key usage, basic constraints, hết hạn, và xác minh chữ ký; bất kỳ thứ gì khác mang tính quan trọng đều phơi bày ở đây. Lớp con của PkiPathValidationException.
• Trường context. Kế thừa getContext() rỗng; các lý do có cấu trúc được chuyển vào $reasons của lớp cha. Các thuộc tính công khai chỉ đọc: $extensionOid (OID dạng chấm, ví dụ 2.5.29.30 cho name constraints), $extensionName, $clauseRef (con trỏ tới điều khoản RFC 5280 và mục log của các hạng mục bị hoãn).
• Khôi phục. Ở chế độ nới lỏng, bắt lớp con cụ thể này để dự phòng về một chính sách thô hơn mà không nuốt các lỗi xác-thực-đường-dẫn thực sự. Đối chiếu $extensionOid và $clauseRef với các fixture PKI của bạn để xem phần mở rộng nào đang chặn xác thực.

RevocationCheckFailedException

• Khi nào nó được ném. Cả các điểm cuối OCSP và danh sách thu hồi chứng thư (CRL) đều bị cạn kiệt mà không có một phán quyết dứt khoát: lỗi truyền tải OCSP hoặc phản hồi bị hỏng khuôn, và lỗi truyền tải CRL hoặc CRL bị hỏng khuôn, với cả hai circuit breaker mở hoặc cả hai cache thiếu. Chế độ nghiêm ngặt coi đây là thất-bại-theo-hướng-đóng; chế độ nới lỏng bắt nó và phát ra một cảnh báo PSR-3 với revocation = null. Mở rộng SecurityException.
• Trường context. Không ghi đè getContext() (kế thừa giá trị mặc định rỗng). Mang trạng thái trong các thuộc tính công khai chỉ đọc $ocspState và $crlState (mỗi cái mặc định là unknown).
• Khôi phục. Khôi phục khả năng tiếp cận một nguồn thu hồi, chờ các circuit breaker đóng, hoặc làm ấm cache, rồi thử lại. Đừng nén lỗi này để thu được một artifact xác-thực-dài-hạn; khẳng định thu hồi là một phần của cấp độ đó.

Xác minh chữ ký OCSP (RFC 6960)

OcspSignatureInvalidException

• Khi nào nó được ném. Một chữ ký BasicOCSPResponse RFC 6960 §4.2.2.2 thất bại khi xác minh mật mã đối với chứng thư của responder. Parser giải mã signatureAlgorithm (RSA-PSS, ECDSA, hoặc RSA-PKCS1v15) và xác minh signature trên tbsResponseData; bất kỳ thất bại nào đều nêu ra ngoại lệ có kiểu này nên các caller có thể phân biệt một phản hồi hợp lệ về cấu trúc nhưng bị giả mạo mật mã với một phản hồi DER-hỏng-khuôn. Không-cuối-cùng, nên các gói phía dưới có thể công bố các lớp con cụ thể hơn. Mở rộng SecurityException.
• Trường context. Không ghi đè getContext() (kế thừa giá trị mặc định rỗng). Mang tag thất bại trong thuộc tính công khai chỉ đọc $reason (ví dụ signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm); detail dạng văn-bản-tự-do được gấp vào thông báo.
• Khôi phục. Kiểm tra $reason. Với responder_cert_not_in_bundle, cung cấp bundle trust anchor đúng và chứng thư responder. Với signature_mismatch, coi phản hồi là không đáng tin cậy. Xem Lỗi chữ ký và dấu thời gian.

Đóng dấu thời gian (RFC 3161)

TsaException

• Khi nào nó được ném. Một lỗi trong giao tiếp với cơ quan cấp dấu thời gian (TSA) RFC 3161 hoặc phân tích phản hồi: TSA trả về một trạng thái lỗi, yêu cầu HTTP thất bại, hoặc phản hồi ASN.1 không thể được phân tích. Nó là cơ sở của phân cấp lỗi TSA và không-cuối-cùng nên các lỗi xác minh có thể mở rộng nó. Mở rộng NextPdfException.
• Trường context. Không ghi đè getContext() (kế thừa giá trị mặc định rỗng).
• Khôi phục. Bắt TsaException cho bất kỳ đường lỗi-TSA nào. Kiểm tra khả năng tiếp cận TSA và rằng điểm cuối trả về một phản hồi RFC 3161 hợp khuôn.

TsaTokenVerificationException

• Khi nào nó được ném. Xác minh CMS của một TimeStampToken RFC 3161 thất bại tại bất kỳ bước xác minh bắt buộc nào: ràng buộc ESSCertIDv2 RFC 5816 §3, toàn vẹn signed-attributes RFC 5652 §11, độ tươi producedAt RFC 3161 §2.4.2, hoặc chữ ký SignerInfo RFC 5652 §5.4. Thất-bại-theo-hướng-đóng, với một bộ phân biệt bước có kiểu nên các đường audit có thể phân biệt replay với clock skew với cert-mismatch mà không grep các thông báo. Lớp con của TsaException, nên các trình xử lý catch (TsaException) cũ tiếp tục kích hoạt.
• Trường context. step (giá trị Step của pipeline thất bại) và message. Accessor: getStep().
• Khôi phục. Có thể hành động bởi một nhà phát triển (chứng thư TSA cấu hình sai hoặc dung sai skew) hoặc bảo mật (nghi ngờ MITM hoặc replay). Đọc step để khoanh vùng giai đoạn thất bại và sửa đầu vào hoặc cấu hình tin cậy tương ứng.

MalformedDerException

• Khi nào nó được ném. Tín hiệu nội bộ rằng một lần duyệt DER chạm một ranh giới bị hỏng khuôn hoặc cắt cụt, được nêu ra bởi các trình duyệt cấp thấp bên trong trình xác minh TSA token. Nó luôn được bắt tại ranh giới verify công khai và được bọc lại thành một TsaTokenVerificationException mang bộ phân biệt bước phù hợp; nó không bao giờ lọt vào mã caller. Mở rộng RuntimeException; đánh dấu @internal.
• Trường context. Không có.
• Khôi phục. Không hướng tới caller. Hãy xử lý TsaTokenVerificationException được bọc lại thay thế.

Giải mã phần mở rộng chứng thư

Những lớp này mở rộng RuntimeException và không phơi bày getContext(). Cả hai đều là các trình giải mã thất-bại-theo-hướng-đóng.

NameConstraintsDecodeException

• Khi nào nó được ném. Trình giải mã name-constraints gặp một phần tử GeneralSubtree có thể thực thi mà nó không thể giải mã trung thực. RFC 5280 §4.2.1.10 yêu cầu một bên dựa cậy phải xử lý một name constraint có thể thực thi hoặc từ chối chứng thư; chuyển việc âm thầm bỏ qua trước đây thành lỗi có kiểu này ngăn một thất-bại-theo-hướng-mở vốn sẽ âm thầm nới rộng tập tên được chấp nhận. Phạm vi giới hạn ở các dạng tên có thể thực thi (directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier); các dạng không-thể-thực-thi vẫn có thể bỏ qua và không bao giờ nêu nó ra. Constructor có tên: undecodableEnforceableBase(). Đánh dấu @internal.
• Trường context. Không có. Một chuỗi chi tiết an toàn-cho-nhật-ký được mang trong thông báo.
• Khôi phục. Bộ thực thi phơi bày một lý do name_constraints: thất-bại-theo-hướng-đóng và chuỗi bị từ chối. Điều tra việc mã hóa name-constraints của chứng thư; đừng nới lỏng việc thực thi.

QcStatementsDecodeException

• Khi nào nó được ném. Phần mở rộng qcStatements bị hỏng khuôn về cấu trúc: DER bị cắt cụt, một tag sai, hoặc một tràn độ dài. Trình giải mã thất-bại-theo-hướng-đóng và nêu ra thay vì trả về một kết quả một phần hoặc theo phỏng đoán khi nó không thể xác định chắc chắn phần mở rộng nói gì. Đánh dấu @api.
• Trường context. Không có.
• Khôi phục. Bắt nó một cách tường minh chỉ khi bạn có ý định dung thứ việc mã hóa hỏng khuôn; ngược lại coi các phát biểu chứng-thư-đủ-điều-kiện của chứng thư là không-xác-định-được và từ chối hoặc cấp lại chứng thư.

Các phiên PKCS#11

Pkcs11SessionException

• Khi nào nó được ném. Một lỗi quản lý phiên PKCS#11 v3.1. Mỗi constructor có tên ánh xạ tới một lớp lỗi cụ thể và tới một giá trị trả về PKCS#11 CKR_*, được phơi bày qua bộ phân biệt $kind có kiểu nên các caller rẽ nhánh theo một chuỗi-enum ổn định thay vì khớp thông báo dễ vỡ. Các constructor bao gồm: cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired(), và signOperationTtlExpired(). Mở rộng SecurityException.
• Trường context. Không ghi đè getContext() (kế thừa giá trị mặc định rỗng). Mang kind có kiểu trong thuộc tính công khai chỉ đọc $kind, một trong các hằng KIND_* (ví dụ KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). Các định danh slot và phiên, mechanism, và các giá trị TTL xuất hiện trong thông báo. Mã PIN và byte chứng thư không bao giờ được bao gồm.
• Khôi phục. Rẽ nhánh theo $kind. Với user_not_logged_in, đăng nhập với mã PIN người dùng trước khi khởi tạo một thao tác ký. Với token_disconnected, coi tất cả phiên trên slot là mồ côi. Với các kind TTL, xác thực lại hoặc khởi tạo lại thao tác. Với mechanism_not_allowed, mở rộng danh sách mechanism được phép đã cấu hình hoặc chọn một mechanism được phép.

Xem thêm

• Chỉ mục tài liệu tham khảo lỗi
• Lỗi chữ ký và dấu thời gian
• Mã hóa và quyền
• Xác thực PDF/A và PDF/UA