Sorun giderme: imza ve zaman damgası hataları

Kapsam

Bu kayıtlar, NextPDF\Exception\SignatureException ve NextPDF\Security\Signature\Exception\SignatureLevelUnreachableException üzerinden bildirilen imza hatalarını kapsar. Her kayıt, tam fabrika yöntemini veya sınıfı belirtir; böylece nedeni çıkarımla tahmin etmek yerine iletiden ve getContext() çıktısından doğrulayabilirsiniz.

Terim kullanımı notu: motor, bir imzanın geçerli olduğunu veya bir belgenin korunduğunu onaylamaz. Yalnızca algıladığı hatayı bildirir. Her çözümü, bildirilen nedeni ortadan kaldırmaya yönelik bir adım olarak değerlendirin.

Kayıt: PAdES seviyesi “B-LT” veya “B-LTA” üretilemiyor

• Belirti. SignatureException; ileti sonu nextpdf/enterprise package is required for B-LT/B-LTA signatures.
• Olası neden. Uzun vadeli doğrulama yeteneği sağlayıcısı eksik. B-LT ve B-LTA, iptal materyalini ve bir arşiv zaman damgasını gömer; bu sağlayıcı ise nextpdf/enterprise ile dağıtılır.
• Kanıt / tanılama. SignatureException::ltvCapabilityMissing() fabrikası tam olarak bu iletiyi üretir. getContext(), denediğiniz seviyeye ayarlanmış signature_level döndürür.
• Çözüm.
  1. Sağlayıcıyı kurmak için composer require nextpdf/enterprise komutunu çalıştırın.
  2. İmzalama çağrısını yeniden çalıştırın.
  3. Sağlayıcıyı kuramıyorsanız, bunun yerine core paketinin üretebildiği B-B veya B-T isteyin.
• İlgili. İstisna başvurusu.

Kayıt: imza seviyesine erişilemiyor ve çağrı reddediliyor

• Belirti. SignatureLevelUnreachableException; iletisi şu biçimdedir: PAdES level "<x>" is unreachable (highest achievable: "<y>").
• Olası neden. İstenen uyumluluk seviyesi, imzalama anında mevcut olmayan bir altyapı gerektirir; bu çoğunlukla B-T ve üzeri için bir zaman damgası yetkilisidir. Motor güvenli biçimde başarısız olur: sessizce daha düşük bir seviyeye geçip ardından daha yüksek seviyeyi bildirmez.
• Kanıt / tanılama. getContext(), requestedLevel, highestAchievableLevel ve reason döndürür. reason alanı altyapı eksikliğini tanımlar. Bu, karşılayamadığı bir seviyeyi öne süren bir belgeyi önlemek için getirilen, güvenli biçimde başarısız olan varsayılan davranıştır.
• Çözüm.
  1. Eksik altyapıyı tanımlamak için reason alanını okuyun.
  2. Eksik bileşeni sağlayın. Örneğin bir zaman damgası yetkilisi yapılandırın ve çağrıyı yeniden çalıştırın.
  3. Daha düşük bir seviyeyi bilerek kabul etmek için allowDegradation: true değerini PadesOrchestrator bileşenine geçirin. Çağrı bu durumda highestAchievableLevel üretir ve ürettiği seviyeyi bildirir.
• İlgili. Şifreleme ve izinler.

Kayıt: zaman damgası yetkilisi istemcisi gerekli ancak eksik

• Belirti. SignatureException; ileti sonu TSA client is required for level <x> but none was provided.
• Olası neden. Bir B-T, B-LT veya B-LTA isteği bir zaman damgası yetkilisi istemcisi gerektirir, ancak düzenleyicide böyle bir istemci yoktur.
• Kanıt / tanılama. SignatureException::tsaRequired() fabrikası bu iletiyi üretir; getContext(), denenen signature_level değerini taşır.
• Çözüm.
  1. Bir zaman damgası yetkilisi istemcisi yapılandırın ve düzenleyiciye geçirin.
  2. Çağrıyı yeniden çalıştırın.
  3. Zaman damgası gerektirmeyen bir seviye üretmek için B-B isteyin.
• İlgili. İstisna başvurusu.

Kayıt: zaman damgası yetkilisi uç nokta URL’si boş

• Belirti. SignatureException; ileti sonu TSA endpoint URL is empty.
• Olası neden. Zaman damgası yetkilisi istemcisi boş bir uç nokta URL’siyle oluşturuldu.
• Kanıt / tanılama. SignatureException::tsaUrlEmpty() fabrikası bu iletiyi üretir. Bu, bir ağ hatası değil, bir yapılandırma kusurudur.
• Çözüm.
  1. Zaman damgası yetkilisi istemcisine, örneğin https://timestamp.example.com/tsa gibi boş olmayan bir uç nokta URL’si ayarlayın.
  2. İstenen seviye zaman damgalama gerektirmiyorsa, bunun yerine zaman damgası yetkilisi istemcisinin bağlantısını kaldırın.
  3. Çağrıyı yeniden çalıştırın.
• İlgili. İstisna başvurusu.

Kayıt: imza yer tutucusu arabellekte eksik

• Belirti. SignatureException; ileti sonu no /Contents <…> field found in PDF buffer (signature placeholder missing).
• Olası neden. İmzalama aşaması, ayrılmış imza kapsayıcısı bulunmayan bir arabellek aldı; bu nedenle imzayı yazabileceği bir yer yok.
• Kanıt / tanılama. SignatureException::signatureContentsNotFound() fabrikası bu iletiyi üretir.
• Çözüm.
  1. İmza alanının ve yer tutucusunun, imzalama aşaması çalışmadan önce yazıldığından emin olun.
  2. İmzalama başladığında yer tutucu var olacak şekilde işlem hattını yeniden çalıştırın.
• İlgili. İstisna başvurusu.

Kayıt: iptal durumu bilinmiyor (OCSP yanıtlayıcısı reddetti)

• Belirti. SignatureException; ileti sonu OCSP responder returned non-successful OCSPResponseStatus "<status>".
• Olası neden. Çevrimiçi Sertifika Durumu Protokolü (OCSP) yanıtlayıcısı successful durumu döndürmedi; bu nedenle herhangi bir iptal beyanı üretmedi. Motor, kaynakta alıntıladığı RFC 6960 §4.2.1 kuralını izler: dolu bir yanıt gövdesine yalnızca successful (0) durumu için izin verilir. Motor, reddedilen bir yanıtı güven açısından olumlu bir sonuç olarak ele almayı reddeder.
• Kanıt / tanılama. SignatureException::nonSuccessfulOcspResponseStatus() fabrikası bu iletiyi üretir ve bildirilen durumu, örneğin tryLater veya internalError değerini adlandırır. Ayrılmış veya bilinmeyen bir durum baytı söz konusuysa bunun yerine SignatureException::reservedOcspResponseStatus() üretir.
• Çözüm.
  1. İletideki durumu tanımlayın. tryLater gibi geçici bir durum için iptal getirme işlemini daha sonra yeniden deneyin.
  2. Şu durumlar için — unauthorized veya malformedRequest — OCSP istek URL’sini ve yanıtlayıcının beklediği sertifikayı doğrulayın.
  3. Bir B-LT veya B-LTA yapıtı elde etme hatasını bastırmayın; iptal beyanı o seviyenin bir parçasıdır.
• İlgili. İstisna başvurusu.

Kayıt: sertifika zinciri girişi çözülemiyor

• Belirti. SignatureException; ileti sonu failed to base64-decode PEM body — input is not valid PEM.
• Olası neden. Bir sertifika zinciri girişi geçerli Privacy-Enhanced Mail (PEM) değildir; bu genellikle kısaltma, başıboş bir karakter veya PEM beklenen yerde sağlanan ikili bir Distinguished Encoding Rules (DER) blobu nedeniyle olur.
• Kanıt / tanılama. SignatureException::pemDecodingFailed() fabrikası bu iletiyi zincir oluşturma sırasında üretir.
• Çözüm.
  1. Her zincir sertifikasını başıboş karakterler veya kısalma açısından inceleyin.
  2. Etkilenen sertifikayı PEM biçiminde yeniden dışa aktarın.
  3. İmzalama çağrısını yeniden çalıştırın.
• İlgili. Şifreleme ve izinler.

Kayıt: özel anahtar türü algoritmayla eşleşmiyor

• Belirti. SignatureException; ileti sonu expected private key of type "<x>" for the configured algorithm but got "<y>".
• Olası neden. Yüklenen özel anahtar, yapılandırılmış imza algoritmasıyla eşleşmiyor; örneğin Elliptic Curve Digital Signature Algorithm (ECDSA) seçiliyken bir Rivest-Shamir-Adleman (RSA) anahtarı kullanılmış olabilir.
• Kanıt / tanılama. SignatureException::unexpectedKeyType() fabrikası bu iletiyi üretir ve hem beklenen hem de gerçek anahtar sınıfını adlandırır.
• Çözüm.
  1. Sertifikanın ve anahtar çiftinin seçtiğiniz algoritmayla eşleştiğini doğrulayın.
  2. Algoritma seçimini anahtarla eşleşecek şekilde değiştirin veya algoritmayla eşleşen anahtarı yükleyin.
  3. İmzalama çağrısını yeniden çalıştırın.
• İlgili. İstisna başvurusu.

Kayıt: Ed25519 anahtarı veya imza materyali bozuk

• Belirti. Bir Ed25519 uzunluk uyuşmazlığını adlandıran bir ileti sonuyla SignatureException — örneğin Ed25519 signature length <n> ≠ expected 64 bytes ya da Ed25519 round-trip self-verify failed.
• Olası neden. Çalışma zamanı kriptografi yapısı yanlış uzunlukta anahtar veya imza materyali döndürdü ya da yeni üretilen bir imza kendi açık anahtarına göre doğrulanamadı. Motor, kaynakta RFC 8032 §3.4 kuralını alıntılar; bu kural, ayrık bir Ed25519 imzasını 64 baytta sabitler. Motor, kendi kendine doğrulayamadığı materyali yaymak yerine işlemi iptal eder.
• Kanıt / tanılama. İlgili fabrikalar şunlardır: SignatureException::ed25519SignatureMalformed(), ::ed25519RoundTripVerifyFailed(), ::ed25519KeyParseFailed(), ::ed25519SeedInvalid(), ::ed25519SecretKeyMalformed() ve ::ed25519PublicKeyInvalid(). Her biri gözlemlenen uzunluğu adlandırır.
• Çözüm.
  1. libsodium PHP uzantısını yeniden kurun; soyulmuş veya bozuk bir yapı, yanlış uzunluktaki materyalin belgelenen nedenidir.
  2. Anahtarın bir Ed25519 anahtarı olduğunu ve OpenSSL’in 1.1.1 veya daha yeni olduğunu doğrulayın.
  3. İmzalama çağrısını yeniden çalıştırın.
• İlgili. İstisna başvurusu.

Kayıt: arşiv zaman damgası sözlüğü yayılmadı

• Belirti. SignatureException; ileti sonu no /Type /DocTimeStamp dictionary was emitted into the PDF buffer.
• Olası neden. B-LTA arşivleme döngüsü çalıştı, ancak belge zaman damgası sözlüğü arabelleğe hiç ulaşmadı. Yapıt yarım yazılmış bir B-LTA olacağından, motor onu döndürmeyi reddeder.
• Kanıt / tanılama. SignatureException::documentTimestampNotEmitted() fabrikası bu iletiyi üretir. Bu son koşul hatası, sonlandırma anında bildirilir.
• Çözüm.
  1. Çıktıyı atılmış olarak değerlendirin; kısmi yapıtı dağıtmayın.
  2. Erişilebilir bir zaman damgası yetkilisiyle B-LTA işlem hattını yeniden çalıştırın.
  3. Hata yinelenirse, bir kusur raporu için getContext() çıktısını ve zincirlenmiş önceki istisnayı yakalayın.
• İlgili. İstisna başvurusu.

Uç durumlar ve dikkat edilmesi gerekenler

• Bu fabrikalar, cert_info değerini yalnızca bir konu veya parmak izi mevcut olduğunda ayarlar; yetenek ve yapılandırma hataları için boş bir cert_info beklenir.
• Yapılandırılmış bir Hypertext Transfer Protocol (HTTP) istemcisi olmadan yapılan bir B-LT veya B-LTA isteği SignatureException::httpClientMissing() bildirir; iptal getirme işlemi, düzenleyiciye geçirilen bir PHP Standards Recommendation (PSR)-18 istemcisi gerektirir.
• İmzalayıcı uygulaması olmayan, donanım güvenlik modülü (HSM) tarafından desteklenen bir sertifika SignatureException::hsmSignerMissing() bildirir; imzalamadan önce imzalayıcıyı sertifikaya bağlayın.

Ayrıca bkz.

• İstisna başvurusu
• Şifreleme ve izinler
• Bilgi tabanı dizini

Sözlük: PAdES seviyesi · iptal beyanı