QuickSign

Sorun giderme

Önce tanılama

Çoğu sorunun nedeni şu iki araçtan biriyle hemen görülür:

bash
curl http://localhost:5000/api/sign/check   # kütüphaneler, token'lar, sertifikalar
./scripts/test-sign                          # etkileşimli tanılama ve deneme imzası

Ardından logs/ klasöründeki günün log dosyasına bakın. Her istek bir ilişki numarası (correlation id) taşır; aynı isteğe ait satırları bu numarayla bulabilirsiniz.

Sık karşılaşılan hatalar

Hata mesajlarında PIN ve anahtar materyali asla yer almaz; TCKN maskelenir (123*****901).

Mesaj (özet)NedenÇözüm
PKCS#11 kütüphanesi yüklenemedi … Dosya yokSürücü kurulu değil veya yol yanlışSürücüyü kurun; Sign:Pkcs11LibraryPath'i düzeltin veya boş bırakıp otomatik bulunmasını sağlayın
Dosya var ama yüklenemedi … aynı mimaride mi32 / 64 bit uyumsuzluğu veya eksik bağımlılıkSürücüyle aynı mimarideki paketi kullanın; Linux'ta ldd <kütüphane> ile eksikleri görün
takılı token yokToken takılı değil veya pcscd çalışmıyorToken'ı takın; Linux'ta systemctl status pcscd
imza sertifikası … hiçbirinde bulunamadıYanlış token takılı veya sertifikada bu TCKN yokDoğru token'ı takın; /api/sign/check token'lardaki TCKN'leri listeler
PIN hatalı (CKR_PIN_INCORRECT)Yanlış PINDoğru PIN ile tekrar deneyin — aşağıdaki uyarıyı okuyun
PIN'i kilitli (CKR_PIN_LOCKED)Deneme hakkı bittiToken sağlayıcınızın PIN açma (PUK) aracını kullanın
PIN biçimi … (CKR_PIN_LEN_RANGE)PIN çok kısa veya uzunDoğru PIN
CKR_DEVICE_REMOVEDİşlem sırasında token çıkarıldıToken'ı takıp tekrar deneyin
Donanım … içinde yanıt vermediToken yanıt vermiyor; bağlantı sıfırlanıyor (HTTP 503)Birkaç saniye bekleyip tekrar deneyin
Yalnızca RSA anahtarları desteklenirSertifika EC anahtarlıRSA sertifikalı token kullanın
TSA sunucusuna bağlanılamadıAğ, DNS veya vekil sunucu engeliTSA adresine çıkışa izin verin
TSA … HTTP 401TSA hesap istiyorSign:Tsa:Username / Password girin
TSA yanıtı işlenemediAdres bir RFC 3161 servisi değilSağlayıcı adresini doğrulayın
Hash geçersiz / … bayt olmalıdırHash biçimi veya uzunluğu algoritmayla uyuşmuyorSHA256 için 32 bayt (64 hex karakter)

PIN ve token kilidi

Nitelikli e-imza token'ları art arda belirli sayıda yanlış PIN girildiğinde kendini kilitler ve kilit yalnızca PUK ile açılır.

QuickSign bunu önlemek için PDF uçlarında (/sign/pdf/base64, /base64pdfimzala) her TCKN için ardışık hatalı denemeleri sayar. İki ardışık hatadan sonra o TCKN'ye gelen istekler token'a hiç gönderilmeden PIN_LOCKED ile reddedilir. Sayaç bellekte tutulur: doğru PIN'den emin olduktan sonra QuickSign'ı (servisi) yeniden başlatmak engeli kaldırır.

Token kaydına PIN saklıyorsanız ve token'ın PIN'i değiştiyse kaydı güncelleyin; aksi halde her istek eski PIN'le deneme yapar:

bash
curl -X PATCH http://localhost:5000/api/sign/tokens/1 \
  -H "Content-Type: application/json" -d '{"pin":"YENI_PIN"}'

Linux'a özel

  • pcscd çalışmıyorsa token görünmez: sudo systemctl enable --now pcscd.
  • Servis kullanıcısının USB okuyucuya erişimi olmalıdır; sorun yaşıyorsanız önce uygulamayı aynı kullanıcıyla elle çalıştırıp /api/sign/check çıktısını karşılaştırın.
  • Güncel dağıtımlarda libdl adı uyumluluğu QuickSign tarafından otomatik çözülür; libc6-dev kurmanız gerekmez.

Windows'a özel

  • Servis olarak çalışırken token görünmüyor ama elle çalıştırınca görünüyorsa, sürücünün servis hesabıyla (LocalSystem) çalışmayı desteklediğinden emin olun.
  • 32 bit sürücüler yalnız win-x86 paketiyle yüklenir.

Port kullanımda

Failed to bind to address hatası 5000 portunun başka bir uygulama tarafından kullanıldığını gösterir. Başka bir port seçin:

bash
./QuickSign --Urls=http://127.0.0.1:5050

Hâlâ çözemediniz mi?

Log dosyasının ilgili bölümünü (PIN içermez) ve /api/sign/check çıktısını ekleyerek [email protected] adresine yazın.

Sorunuzun cevabını bulamadınız mı? [email protected]