보안 및 서명 오류

한눈에 보기

이 페이지는 NextPDF\Security 네임스페이스 트리의 보안 영역 예외를 다룹니다. 각 항목은 클래스를 명시하고, 언제 발생하는지 기술하며, getContext()가 반환하는 필드를 나열하고, 복구 단계를 제공합니다.

이 클래스들 대부분은 SecurityException을 확장하며, 이는 NextPdfException을 확장하고 ContextAwareExceptionInterface를 구현합니다. 즉, getContext(): array는 로깅 또는 application performance monitoring(APM) 파이프라인으로 보낼 수 있는 구조화되고 비밀이 없는 진단을 반환합니다. 모든 보안 영역 실패를 한 블록에서 잡으려면 SecurityException을 잡고, 타입이 지정된 페이로드가 필요할 때는 특정 서브클래스를 잡으십시오.

이 트리의 몇몇 클래스는 SecurityException 대신 RuntimeException을 직접 확장합니다. 아래에 표시되어 있습니다. 이들은 getContext()를 노출하지 않으며, 대부분은 애플리케이션 코드에서 잡을 것으로 기대하지 않는 내부 제어 흐름 신호로 문서화됩니다.

컨텍스트 필드 규약

측면	동작
기반 계약	`NextPdfException::getContext()`는 `[]`를 반환하고, 서브클래스가 이를 재정의합니다.
비밀 위생	메시지와 컨텍스트는 원시 키 자료, 평문, PIN, 초기화 벡터(IV) 바이트를 생략합니다. 키는 지문 접두사로만 표면화됩니다.
`SecurityException`	추상 기반. 자체 필드를 담지 않습니다. 서브클래스가 페이로드를 정의합니다.

기반 타입

`SecurityException`

발생 시점. 직접 발생하지 않습니다. 보안 영역의 추상 기반입니다. 단일 catch (SecurityException $e) 블록이 인증 암호화 무결성 실패, 논스 재사용 방어, PDF/A 대 암호화 바인딩, 키 관리 결함, PKI 실패를 잡을 수 있도록 존재합니다.
컨텍스트 필드. 자체 필드 없음. NextPdfException에서 비어 있는 기본값을 상속합니다. 서브클래스가 페이로드를 채웁니다.
복구. 실행 가능한 처리를 위해 구체 서브클래스를 잡거나, 대략적인 보안 사고 라우팅을 위해 SecurityException을 잡으십시오.

암호화 및 인증 암호화 오류

이들은 AES-GCM(Galois/Counter Mode) 암호화기와 PDF/A 가드가 발생시킵니다. 증상 우선 안내는 암호화 및 권한을 참조하십시오.

`DecryptionFailedException`

발생 시점. 연관 데이터를 가진 인증 암호화(AEAD) 복호화가 변조가 아닌 이유로 실패할 때입니다. 잘린 암호문, 누락된 IV, 또는 무결성 검사를 실제로 실행할 자료가 충분하지 않은 API 경계에서 공급된 잘못된 키입니다. 이는 보안 사고가 아니라 구성 또는 전송 오류입니다.
컨텍스트 필드. algorithm(예: AES-256-GCM), reason(예: ciphertext shorter than IV+tag)입니다.
복구. 암호문, IV, 키가 완전하고 올바르게 구성되었는지 확인하십시오. 이를 변조로 취급하지 마십시오. TamperedDataException과 대조하십시오.

`TamperedDataException`

발생 시점. AEAD 인증 태그가 검증에 실패할 때입니다. 태그는 암호문과 연관 인증 데이터(AAD)를 포괄합니다. 둘 중 하나가 암호화 후 수정되었다면 기저의 openssl_decrypt()가 false를 반환합니다. 이 구별된 서브타입은 프레이밍 오류 대신 보안 사고 등급의 경보를 표면화할 수 있게 합니다.
컨텍스트 필드. algorithm, ciphertext_length(거부된 암호문의 길이, IV와 태그 제외)입니다.
복구. 변조 또는 잘못된 키/IV로 취급하십시오. 맹목적으로 재시도하지 말고, 암호문의 출처를 조사하십시오. ISO/TS 32003:2023 §5.2와 NIST SP 800-38D §6.5에 따르면, 태그 검사 실패는 데이터가 진정하지 않음을 의미합니다.

`NonceReuseException`

발생 시점. AES-GCM에 같은 키와 IV 쌍으로 두 번 암호화하라고 요청할 때입니다. 암호화기는 인스턴스별 단조 카운터로 방어하며, 심층 방어로서 방출된 모든 (키 지문, IV) 쌍의 런타임 해시 집합을 둡니다. 카운터가 구조적으로 충돌을 배제하므로, 이 발생은 프로덕션에서 결코 일어나서는 안 되는 치명적 우선순위 버그 지표입니다. 키/IV 쌍을 재사용하면 전체 키스트림이 손상됩니다(ISO/TS 32003:2023 §5.2 NOTE 2; NIST SP 800-38D §8.3).
컨텍스트 필드. key_fingerprint_prefix(SHA-256(key)의 처음 8개 16진 문자), iv_length(ISO/TS 32003에서는 항상 12), reason(hashset-collision 또는 counter-rollover로, 카운터를 무력화하는 리팩터 버그와 2^63 카운터 트립 와이어를 구분), iv_fixed_field_hex(IV 고정 필드, 공급된 경우에만 존재하며, 자체 키 아래 보고되고 절대 키 지문으로 잘못 표시되지 않음)입니다.
복구. 즉시 중단하고 키를 교체하십시오. 결함 보고를 제출하십시오. 이는 잘못된 호출자 입력이 아니라 암호화기의 버그를 나타냅니다.

`GcmInvocationLimitExceededException`

발생 시점. 주어진 AES-GCM 키에 대해 선택적(opt-in) NIST SP 800-38D §8.3 사용 안전성 호출 횟수에 도달할 때입니다. 이는 암호화기 내부의 아키텍처 한도보다 일찍 사양 권장 경계(키당 약 2^32회 호출)를 강제하려는 호출자를 위한 심층 방어 텔레메트리 훅입니다. 기본적으로 발생하지 않습니다. assertWithinSafetyBound() 헬퍼만 이를 발생시킵니다.
컨텍스트 필드. key_fingerprint_prefix, invocation_count(현재 encrypt() 횟수, 한도 이상), invocation_limit(선택적 경계)입니다.
복구. 누적 충돌 및 위조 확률이 더 이상 무시할 수 없게 되기 전에 문서 키를 교체하거나(새 키 자료로 새 암호화기를 구성), 계속된 서비스를 거부하도록 호출자 정책을 확장하십시오.

`IncompatiblePdfAModeException`

발생 시점. PDF/A로 태깅된 문서에 암호화 작업을 시도할 때입니다. PDF/A 계열(PDF/A-2, PDF/A-3, PDF/A-4)은 일률적으로 암호화를 금지합니다. ISO 19005 §6.1.3에 따라 Encrypt 키는 트레일러에 존재해서는 안 되며, ISO 19005-4:2020 부속서 A와 B가 이를 수정 없이 상속합니다. PDF/A와 암호화의 허용되는 조합은 없습니다.
컨텍스트 필드. pdfa_mode(예: pdfa4, pdfa3), encryption_operation(거부된 호출, 예: useAesGcm)입니다.
복구. 암호화된 문서를 생성하려면 enablePdfA() 호출을 생략하고, 보관용 문서를 생성하려면 암호화 호출을 생략하십시오. PDF/A 및 PDF/UA 검증을 참조하십시오.

암호 정책 강제

`CryptoPolicyViolationException`

발생 시점. 구성된 암호 정책이 core 서명, 암호화 또는 해싱 작업이 선택한 알고리즘, 키 강도, 또는 암호를 거부할 때입니다. 이는 적합성 강제(예: FIPS 140-2/3, eIDAS, 또는 맞춤 엔터프라이즈 정책)를 위한 fail-closed 경계이며, 어떤 서명이나 암호문이 생성되기 전에 CryptoPolicyEnforcer가 발생시키므로, 정책을 위반하는 작업은 절대 승인되지 않은 아티팩트를 방출할 수 없습니다. 좁은 OpenSSL 작업 실패나 서명 프리미티브 실패와 구별됩니다. 이는 그 외에는 유효한 요청에 대한 정책 거부입니다. NIST SP 800-131A Rev. 2와 ISO/IEC 19790:2025 §7에 부합합니다.
컨텍스트 필드. policy(정책 이름, 예: FIPS 140-3 Strict), category(hash, signature, encryption, 또는 key-strength), item(거부된 항목, 예: object identifier(OID), 암호 이름, 또는 rsa/1024), reason입니다.
복구. 명명된 정책이 승인하는 알고리즘, 키 길이, 또는 암호를 선택하거나, 정책을 소유한다면 정책을 조정하십시오. 구조화된 컨텍스트를 문서화된 적합성 런북으로 라우팅하십시오.

키 관리

이름이 같은 두 클래스가 존재합니다. 둘은 SecurityException 루트를 공유하므로 하나의 catch (SecurityException $e) 블록이 둘 다 잡지만, 서로 다른 페이로드를 담습니다. 특정 형태가 필요할 때는 정규화된 이름으로 임포트하십시오.

`KeyManagementException` (수명 주기: `NextPDF\Security\Exception`)

발생 시점. 키 관리 작업이 키가 서명 또는 암호화 프리미티브에 소비되기 전에 실패할 때입니다. Privacy-Enhanced Mail(PEM), PKCS#12, 또는 PKCS#11 키 파싱 실패, 키 파생(HKDF, PBKDF2, scrypt) 실패, 잘못된 키 암호화 키에 대한 AES Key Wrap(RFC 3394) 거부, malformed Distinguished Encoding Rules(DER)를 반환하는 hardware security module(HSM), 또는 Ed25519 시드 길이 불일치입니다.
컨텍스트 필드. operation(예: load_pem, kek_derive, key_wrap), key_type(예: RSA, EC-P256, Ed25519, AES-256), reason입니다. 원시 키 자료는 절대 포함되지 않습니다.
복구. 명명된 작업과 키 타입을 검사하고, 소스 키 자료나 파생 입력을 수정한 뒤 재시도하십시오.

`KeyManagementException` (서명 경로: `NextPDF\Security\Signature\Exception`)

발생 시점. 서명자 제공자가 키 관리 결함에 부딪칠 때입니다. 요청된 키 버전이 알 수 없거나, 비활성화되었거나, 파기 예정이거나, 서명 권한이 없거나, 그 외에 사용할 수 없습니다. 이는 RsaPssSigner와 LocalKeySignerProvider가 라이브 키 실패에 대해 발생시키는 것입니다. 이름 있는 생성자: unknownKeyVersion()과 keyVersionDisabled()입니다.
컨텍스트 필드. providerId, keyVersion, reason입니다. 접근자: providerId(), keyVersion(), reason()입니다.
복구. 키를 교체하거나 다시 권한을 부여하거나, 사용 가능한 키 버전을 선택한 뒤 재시도하십시오. 서명 프리미티브 자체가 실패했음을 나타내는 SignatureFailedException과 구별됩니다.

서명

도달할 수 없는 레벨과 누락된 기능에 대한 증상 우선 안내는 서명 및 타임스탬프 실패를 참조하십시오.

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

발생 시점. 암호 서명 작업이 실패할 때입니다. RSA, ECDSA, 또는 Ed25519 서명 프리미티브가 false 또는 잘못된 길이의 출력을 반환하거나, HSM 또는 PKCS#11 토큰이 비성공 상태로 응답하거나, Cryptographic Message Syntax(CMS) SignedData 조립이 잘못된 형식의 인증서나 체인에서 실패하거나, Ed25519 왕복 자체 검증이 실패합니다. 새 코드는 레거시 PAdES 결합 서명 예외보다 이 R4-13 서브타입을 선호해야 합니다.
컨텍스트 필드. operation(예: sign, verify, build_cms), algorithm(예: rsa-pkcs1v15-sha256, ed25519), reason입니다. 접근자: getOperation(), getAlgorithm(), getReason()입니다.
복구. 작업과 알고리즘을 읽고, 입력(키, 인증서 체인, 또는 백엔드 가용성)을 바로잡은 뒤 재시도하십시오. ETSI EN 319 142-1의 fail-closed 키 처리 자세에 부합합니다.

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

발생 시점. SignerProviderInterface 구현이 키 관리로 분류되지 않은 어떤 이유로든 서명 작업을 완료할 수 없을 때입니다. 백엔드 드라이버 오류, 잘못된 형식의 키 자료, 또는 복구 불가능한 HSM I/O입니다. 이는 fail-closed 서명 계약의 포괄(catch-all)로, 모든 프리미티브가 null, false, 또는 빈 문자열을 반환하는 대신 실패 시 발생시킵니다. 이름 있는 생성자: forProvider()입니다.
컨텍스트 필드. providerId, reason입니다. 접근자: providerId(), reason()입니다.
복구. 제공자 id와 reason을 검사하고, 제공자 백엔드나 키 자료를 수정한 뒤 재시도하십시오. “키가 잘못됨”과 “프리미티브가 실패함”을 구분하려면 KeyManagementException과 이 타입으로 분기하십시오.

`SignatureLevelUnreachableException`

발생 시점. 요청된 PAdES 적합성 레벨을 현재 런타임 인프라에서 충족할 수 없고(대개 B-T 이상에 필요한 타임스탬프 기관 누락) 호출자가 저하를 허용하지 않은 경우입니다. 기본은 fail-closed입니다. 엔진은 더 낮은 레벨을 조용히 생성하면서 더 높은 레벨을 표방하는 대신 거부합니다. 그것은 eIDAS 등급의 회귀일 것입니다. ETSI EN 319 142-1 §6에 부합합니다. 이 클래스는 (SecurityException이 아니라) NextPdfException을 직접 확장합니다.
컨텍스트 필드. requestedLevel, highestAchievableLevel, reason입니다. 접근자: requestedLevel(), highestAchievableLevel(), reason()입니다.
복구. reason을 읽어 누락된 인프라를 식별하고 이를 공급하거나(예: 타임스탬프 기관 구성), 도달 가능한 최고 레벨을 의도적으로 받아들이려면 allowDegradation: true를 PadesOrchestrator에 전달하십시오.

`SignerProviderNotFoundException`

발생 시점. SignerProviderRegistry::get()에 등록되지 않은 제공자 id를 요청할 때입니다. PSR-11 NotFoundExceptionInterface를 구현하므로 레지스트리가 PSR-11 컨테이너 계약을 준수합니다. 이름 있는 생성자: forId()입니다. 이 클래스는 RuntimeException을 확장하며 getContext()를 노출하지 않습니다.
컨텍스트 필드. 없음. 등록되지 않은 id가 메시지에 나타납니다.
복구. 요청하기 전에 예상한 id로 제공자를 등록하거나, 레지스트리에 전달하는 id를 바로잡으십시오.

해싱 (SHAKE256)

이들은 RuntimeException을 확장하며 getContext()를 노출하지 않습니다. SHAKE256은 일부 ISO/TS 32001 경로에서 요구하는 SHA-3 확장 가능 출력 함수입니다.

`Shake256NotAvailableException`

발생 시점. 다이제스트 시점에, 선택된 제공자가 요청을 충족할 수 없을 때입니다. 이름 있는 생성자: noBackend()(시도된 모든 등급에 걸쳐 이 호스트에 작동하는 SHAKE256 백엔드가 없음)와 ffiCallFailed()(FFI로 바인딩된 OpenSSL EVP 호출이 비성공 상태를 반환함, 예를 들어 축소된 libcrypto 빌드에서)입니다.
컨텍스트 필드. 없음. 메시지가 시도된 등급 또는 실패한 심볼을 명시합니다.
복구. OpenSSL 3.x가 있는 ext-ffi를 설치하거나, hash_algos()에 shake256을 노출하는 PHP 빌드로 업그레이드하십시오. 유저랜드 Keccak 폴백은 의도적으로 출하되지 않습니다.

`Shake256ProviderNotAvailableException`

발생 시점. SHAKE256 제공자 생성자에서, 기능 탐침이 실패하여 제공자를 인스턴스화할 수 없을 때입니다. 이는 제어 흐름 신호입니다. 제공자 레지스트리가 이를 잡아 등급 레이블을 기록하고 다음 등급을 시도합니다. 애플리케이션 코드로 절대 새어 나가서는 안 됩니다. 이름 있는 생성자: forTier()입니다.
컨텍스트 필드. 없음. 메시지가 등급과 이유를 명시합니다.
복구. 호출자가 직접 조치할 수 없습니다. 전체 등급 체인이 소진되면, 레지스트리가 대신 운영자 대상 수정책을 담은 Shake256NotAvailableException::noBackend()를 표면화합니다.

문서 MAC 무결성 (ISO/TS 32004)

이들은 /AuthCode 아래 저장되는 ISO/TS 32004 문서 수준 메시지 인증 코드(MAC)를 다룹니다. 둘 다 NextPdfException을 확장하고 getContext()를 재정의합니다.

`DocumentMacTokenException`

발생 시점. MAC 토큰 리더가 fail-closed로, CMS AuthenticatedData MAC 토큰이 구조적으로 잘못된 형식이거나 합의된 ISO/TS 32004 집합을 벗어난 알고리즘을 선언할 때입니다. 이름 있는 생성자: malformed()와 algorithmMismatch()입니다. @internal로 표시됩니다.
컨텍스트 필드. status(DocumentMacVerificationStatus 값, MalformedToken 또는 AlgorithmMismatch 중 하나)입니다. public readonly 속성: $status입니다.
복구. 문서를 검증되지 않은 것으로 취급하십시오. 잘못된 형식의 토큰이나 합의된 집합을 벗어난 알고리즘은 MAC이 신뢰를 확립할 수 없음을 의미합니다. 콘텐츠가 보호된 것처럼 진행하지 마십시오.

`DocumentMacVerificationException`

발생 시점. fail-closed로, 문서 수준 MAC 검증이 신뢰 상태에 도달할 수 없을 때입니다. 누락되었거나 잘못된 형식의 /AuthCode, 합의된 집합을 벗어난 알고리즘, 언래핑 실패, 또는 MAC 불일치(변조)입니다. 검증자의 verify()는 분기를 위해 명시적 결과를 반환합니다. 이는 assertVerified()가 발생시키는 예외 흐름 대응물로, “콘텐츠를 신뢰하라” 코드가 검증되지 않은 문서를 절대 지나칠 수 없게 합니다. 이름 있는 생성자: fromResult()입니다.
컨텍스트 필드. status(DocumentMacVerificationStatus 값)입니다. public readonly 속성: $status입니다.
복구. 문서 콘텐츠를 신뢰하지 마십시오. status를 검사하여 변조(MAC 불일치)와 구성 문제(누락되었거나 잘못된 형식의 /AuthCode, 알고리즘 불일치)를 구분하십시오.

PKI 경로 검증 (RFC 5280)

이들은 RFC 5280 인증 경로 검증을 다룹니다. 기반 타입과 그 서브클래스는 fail-closed입니다.

`PkiPathValidationException`

발생 시점. RFC 5280 경로 검증자의 strict 모드 실패입니다. 좁은 서브클래스(ChainLengthExceededException, UnsupportedExtensionException)를 위한 비-final 기반이므로, 이 타입을 잡는 핸들러는 리스코프 치환을 통해 그것들도 잡습니다. SecurityException을 확장합니다.
컨텍스트 필드. getContext()를 재정의하지 않습니다(비어 있는 기본값 상속). 구조화된 이유를 동결된 public readonly 배열 속성 $reasons(규칙 이름과 설명 문자열의 비어 있지 않은 목록)에 담습니다.
복구. $reasons를 읽어 실패한 규칙을 식별하고, 인증서 체인을 수정한 뒤 다시 검증하십시오. 모든 경로 검증 실패를 일률적으로 처리하려면 이 타입을 잡으십시오.

`ChainLengthExceededException`

발생 시점. 경로 검증자가 구성된 상한을 초과하는 길이의 체인을 따라가도록 요청받을 때입니다. 상한은 어떤 파싱이 시작되기 전에 강제되므로, 악의적인 공급자가 검증자를 2차 작업으로 몰아넣거나 임의로 깊은 체인으로 리소스를 소진시킬 수 없습니다. 기본 상한 10은 PKIX-CMP 프로파일(RFC 4210 §5.3.18)을 따릅니다. 실제 체인은 5에서 6개 항목에 들어맞습니다. PkiPathValidationException의 서브클래스입니다.
컨텍스트 필드. 비어 있는 getContext()를 상속합니다. 이유 문자열 chain_length_exceeded: supplied=<n> cap=<n>이 부모의 $reasons로 전달됩니다. public readonly 속성: $supplied, $cap입니다.
복구. 상한 내의 체인을 공급하거나, 정당하게 더 긴 체인이 예상된다면 구성된 상한을 높이십시오.

`UnsupportedExtensionException`

발생 시점. 경로 검증자가 아직 강제가 구현되지 않은 임계 X.509 확장을 만날 때입니다. RFC 5280 §4.2에 따라 인식되지 않은 임계 확장은 fail-closed여야 합니다. strict 모드와 lenient 모드 모두 여기서 fail-closed됩니다. 임계 확장을 조용히 건너뛰면 보안 회귀가 될 것이기 때문입니다. 검증자는 체인 빌드, AKI/SKI 매칭, 키 사용, 확장 키 사용, 기본 제약, 만료, 서명 검증을 다룹니다. 그 외의 임계 항목은 여기로 표면화됩니다. PkiPathValidationException의 서브클래스입니다.
컨텍스트 필드. 비어 있는 getContext()를 상속합니다. 구조화된 이유가 부모의 $reasons로 전달됩니다. public readonly 속성: $extensionOid(점으로 구분된 OID, 예: 이름 제약의 2.5.29.30), $extensionName, $clauseRef(RFC 5280 절과 연기 항목 로그 항목을 가리키는 포인터)입니다.
복구. lenient 모드에서는, 실제 경로 검증 실패를 삼키지 않으면서 더 거친 정책으로 폴백하기 위해 이 특정 서브클래스를 잡으십시오. 어떤 확장이 검증을 막고 있는지 보려면 $extensionOid와 $clauseRef를 PKI 픽스처와 대조하여 감사하십시오.

`RevocationCheckFailedException`

발생 시점. OCSP와 certificate revocation list(CRL) 엔드포인트가 모두 확정적 판정 없이 소진될 때입니다. OCSP 전송 실패 또는 잘못된 형식의 응답, CRL 전송 실패 또는 잘못된 형식의 CRL과 함께, 두 서킷 브레이커가 모두 열려 있거나 두 캐시가 모두 누락된 경우입니다. strict 모드는 이를 fail-closed로 취급하고, lenient 모드는 이를 잡아 revocation = null과 함께 PSR-3 경고를 방출합니다. SecurityException을 확장합니다.
컨텍스트 필드. getContext()를 재정의하지 않습니다(비어 있는 기본값 상속). public readonly 속성 $ocspState와 $crlState(각각 기본값 unknown)에 상태를 담습니다.
복구. 폐기 소스에 대한 접근성을 복원하거나, 서킷 브레이커가 닫히기를 기다리거나, 캐시를 워밍업한 뒤 재시도하십시오. 장기 검증 아티팩트를 얻기 위해 이를 억제하지 마십시오. 폐기 주장은 해당 레벨의 일부입니다.

OCSP 서명 검증 (RFC 6960)

`OcspSignatureInvalidException`

발생 시점. RFC 6960 §4.2.2.2 BasicOCSPResponse 서명이 응답자 인증서에 대한 암호 검증에 실패할 때입니다. 파서는 signatureAlgorithm(RSA-PSS, ECDSA, 또는 RSA-PKCS1v15)을 디코딩하고 tbsResponseData에 대한 signature를 검증합니다. 어떤 실패든 이 타입이 지정된 예외를 발생시켜, 호출자가 구조적으로 유효하지만 암호적으로 변조된 응답과 잘못된 형식의 DER 응답을 구분할 수 있게 합니다. 비-final이므로 다운스트림 패키지가 더 구체적인 서브클래스를 게시할 수 있습니다. SecurityException을 확장합니다.
컨텍스트 필드. getContext()를 재정의하지 않습니다(비어 있는 기본값 상속). public readonly 속성 $reason(예: signature_mismatch, responder_cert_not_in_bundle, unsupported_signature_algorithm)에 실패 태그를 담습니다. 자유 텍스트 detail은 메시지에 접힙니다.
복구. $reason을 검사하십시오. responder_cert_not_in_bundle의 경우, 올바른 신뢰 앵커 번들과 응답자 인증서를 공급하십시오. signature_mismatch의 경우, 응답을 신뢰할 수 없는 것으로 취급하십시오. 서명 및 타임스탬프 실패를 참조하십시오.

타임스탬프 (RFC 3161)

`TsaException`

발생 시점. RFC 3161 time-stamp authority(TSA) 통신 또는 응답 파싱의 실패입니다. TSA가 오류 상태를 반환하거나, HTTP 요청이 실패하거나, ASN.1 응답을 파싱할 수 없습니다. TSA 결함 계층의 기반이며, 검증 실패가 이를 확장할 수 있도록 비-final입니다. NextPdfException을 확장합니다.
컨텍스트 필드. getContext()를 재정의하지 않습니다(비어 있는 기본값 상속).
복구. 모든 TSA 결함 경로에 대해 TsaException을 잡으십시오. TSA 접근성과 엔드포인트가 올바른 형식의 RFC 3161 응답을 반환하는지 확인하십시오.

`TsaTokenVerificationException`

발생 시점. RFC 3161 TimeStampToken의 CMS 검증이 의무화된 검증 단계 중 하나에서 실패할 때입니다. RFC 5816 §3 ESSCertIDv2 바인딩, RFC 5652 §11 서명 속성 무결성, RFC 3161 §2.4.2 producedAt 신선도, 또는 RFC 5652 §5.4 SignerInfo 서명입니다. fail-closed이며, 감사 파이프라인이 메시지를 grep하지 않고도 재생, 시계 편차, 인증서 불일치를 구분할 수 있도록 타입이 지정된 단계 판별자를 둡니다. TsaException의 서브클래스이므로 레거시 catch (TsaException) 핸들러가 계속 발동합니다.
컨텍스트 필드. step(실패한 파이프라인 Step 값)과 message입니다. 접근자: getStep()입니다.
복구. 개발자(잘못 구성된 TSA 인증서 또는 편차 허용 오차)나 보안(MITM 또는 재생 의심)이 조치할 수 있습니다. step을 읽어 실패한 단계를 국소화하고 해당 입력이나 신뢰 구성을 수정하십시오.

`MalformedDerException`

발생 시점. DER 순회가 잘못된 형식이거나 잘린 경계에 부딪쳤다는 내부 신호로, TSA 토큰 검증자 내부의 저수준 순회기가 발생시킵니다. 항상 공개 검증 경계에서 잡혀 적절한 단계 판별자를 담은 TsaTokenVerificationException으로 다시 래핑됩니다. 호출자 코드로 절대 새어 나가지 않습니다. RuntimeException을 확장하며 @internal로 표시됩니다.
컨텍스트 필드. 없음.
복구. 호출자 대상이 아닙니다. 대신 래핑된 TsaTokenVerificationException을 처리하십시오.

인증서 확장 디코딩

이들은 RuntimeException을 확장하며 getContext()를 노출하지 않습니다. 둘 다 fail-closed 디코더입니다.

`NameConstraintsDecodeException`

발생 시점. 이름 제약 디코더가 충실하게 디코딩할 수 없는 강제 가능한 GeneralSubtree 요소를 만날 때입니다. RFC 5280 §4.2.1.10은 신뢰 당사자가 강제 가능한 이름 제약을 처리하거나 인증서를 거부할 것을 요구합니다. 이전의 조용한 누락을 이 타입이 지정된 실패로 전환하면, 허용되는 이름 집합을 조용히 넓혔을 fail-open을 방지합니다. 범위는 강제 가능한 이름 형식(directoryName, dNSName, iPAddress, rfc822Name, uniformResourceIdentifier)으로 제한됩니다. 강제 불가능한 형식은 여전히 무시 가능하며 이를 절대 발생시키지 않습니다. 이름 있는 생성자: undecodableEnforceableBase()입니다. @internal로 표시됩니다.
컨텍스트 필드. 없음. 로그 안전 세부 정보 문자열이 메시지에 담깁니다.
복구. 강제기가 fail-closed name_constraints: 이유를 표면화하고 체인이 거부됩니다. 인증서의 이름 제약 인코딩을 조사하십시오. 강제를 완화하지 마십시오.

`QcStatementsDecodeException`

발생 시점. qcStatements 확장이 구조적으로 잘못된 형식일 때입니다. 잘린 DER, 잘못된 태그, 또는 길이 오버플로입니다. 디코더는 fail-closed이며, 확장이 무엇을 말하는지 확실하게 판단할 수 없을 때 부분적이거나 휴리스틱한 결과를 반환하는 대신 발생시킵니다. @api로 표시됩니다.
컨텍스트 필드. 없음.
복구. 잘못된 형식의 인코딩을 용인할 의도일 때만 이를 명시적으로 잡으십시오. 그렇지 않으면 인증서의 적격 인증서 진술을 판단 불가능한 것으로 취급하고 인증서를 거부하거나 다시 발급하십시오.

PKCS#11 세션

`Pkcs11SessionException`

발생 시점. PKCS#11 v3.1 세션 관리 결함입니다. 모든 이름 있는 생성자가 특정 결함 클래스와 PKCS#11 CKR_* 반환 값으로 매핑되며, 타입이 지정된 $kind 판별자를 통해 노출되어 호출자가 깨지기 쉬운 메시지 매칭 대신 안정적인 열거 문자열로 분기합니다. 생성자에는 cryptokiNotInitialized(), userNotLoggedIn(), userAlreadyLoggedIn(), operationNotInitialized(), operationActive(), mechanismNotAllowed(), tokenDisconnected(), concurrentSessionLimitExceeded(), sessionAlreadyClosed(), stateTransitionInvalid(), osLockingRequired(), loginTtlExpired(), signOperationTtlExpired()이 포함됩니다. SecurityException을 확장합니다.
컨텍스트 필드. getContext()를 재정의하지 않습니다(비어 있는 기본값 상속). public readonly 속성 $kind에 타입이 지정된 종류를 담으며, 이는 KIND_* 상수 중 하나입니다(예: KIND_USER_NOT_LOGGED_IN, KIND_TOKEN_DISCONNECTED, KIND_LOGIN_TTL_EXPIRED). 슬롯 및 세션 식별자, 메커니즘, TTL 값은 메시지에 나타납니다. PIN과 인증서 바이트는 절대 포함되지 않습니다.
복구. $kind로 분기하십시오. user_not_logged_in의 경우, 서명 작업을 초기화하기 전에 사용자 PIN으로 로그인하십시오. token_disconnected의 경우, 슬롯의 모든 세션을 고아로 취급하십시오. TTL 종류의 경우, 다시 인증하거나 작업을 다시 초기화하십시오. mechanism_not_allowed의 경우, 구성된 메커니즘 허용 목록을 확장하거나 허용된 메커니즘을 선택하십시오.

보안 및 서명 오류

한눈에 보기

컨텍스트 필드 규약

기반 타입

SecurityException

암호화 및 인증 암호화 오류

DecryptionFailedException

TamperedDataException

NonceReuseException

GcmInvocationLimitExceededException

IncompatiblePdfAModeException

암호 정책 강제

CryptoPolicyViolationException

키 관리

KeyManagementException (수명 주기: NextPDF\Security\Exception)

KeyManagementException (서명 경로: NextPDF\Security\Signature\Exception)

서명

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

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

SignatureLevelUnreachableException

SignerProviderNotFoundException

해싱 (SHAKE256)

Shake256NotAvailableException

Shake256ProviderNotAvailableException