Mali Mühür Merkezi [KAMU-SM // VUK-MÜHÜR-TERMİNALİ]

Headless Linux (Ubuntu Server) üzerinde Docker konteynerında libakisp11.so ile e-Fatura imzalarken "sun.security.pkcs11.ConfigurationException: Library libakisp11.so does not exist" hatası nasıl giderilir?

Bulut tabanlı mikroservis mimarimizde e-arşiv ve e-fatura imzalama servisini Ubuntu Server 22.04 LTS üzerinde koşan bir Docker konteynerı içerisine taşıdık. Fiziksel sunucuya takılı Kamu SM mali mühür akıllı kartını Docker'a /dev/bus/usb üzerinden bağlayıp Java ortamında Akis PKCS#11 sürücüsü (libakisp11.so) ile imza atmak istediğimizde, kütüphane dosyası dizinde mevcut olmasına rağmen 'ConfigurationException / UnsatisfiedLinkError' hatası alıyoruz. Grafik arayüzü (GUI) bulunmayan Linux sistemlerde Akis modülü ve pcscd servis entegrasyonu nasıl doğru yapılandırılır?
Durum: Çözüldü Kategori: Soru-Cevap

3 Cevap Nasıl Uygulanır?

Headless Linux ortamlarında (Ubuntu Server, Debian, RHEL) ve özellikle Docker konteynerlarında Kamu SM akıllı kartlarını libakisp11.so kütüphanesiyle çalıştırmak isterken karşılaşılan ConfigurationException: Library libakisp11.so does not exist veya UnsatisfiedLinkError hatası, kütüphanenin kendisinin bulunamamasından ziyade dinamik bağlantı (shared library) bağımlılıklarının Linux işletim sisteminde eksik olmasından kaynaklanır.

Sorunu çözmek ve kesintisiz imzalama sağlamak için aşağıdaki adımları sırasıyla uygulayınız:

  1. Dinamik Kütüphane Bağımlılıklarını Tespit Edin ve Kurun: libakisp11.so derlenirken arka planda PC/SC akıllı kart katmanına ve OpenSSL kripto kütüphanelerine bağlanır. Terminalde ldd /usr/lib/libakisp11.so (veya kütüphanenin bulunduğu dizin) komutunu çalıştırın. Çıktıda muhtemelen libpcsclite.so.1 => not found satırını göreceksiniz. Bunu gidermek için ana makinede ve Dockerfile içerisinde şu paketleri kurun:
    apt-get update && apt-get install -y pcscd libpcsclite1 libpcsclite-dev libccid pcsc-tools
  2. Docker Konteynerine PCSC Soketini Bağlayın: Docker içerisinde ayrı bir pcscd servisi çalıştırmak donanım kilitlenmelerine yol açar. Doğru yöntem, pcscd servisini ana makinede (host) çalıştırmak ve Unix domain soketini konteyner içine mount etmektir:
    docker run -d --device=/dev/bus/usb -v /var/run/pcscd/pcscd.comm:/var/run/pcscd/pcscd.comm ...
  3. PKCS#11 Konfigürasyon Dosyasını Düzenleyin: Java uygulamanıza sunulan pkcs11.cfg dosyasını şu şekilde yapılandırın:
    name = Akis
    library = /usr/lib/libakisp11.so
    slotListIndex = 0
  4. JVM İzinlerini Ekleyin: Java 11, 17 veya 21 sürümlerinde modül kısıtlamalarını aşmak için JVM başlatma parametrelerine mutlaka --add-exports java.base/sun.security.pkcs11=ALL-UNNAMED ve --add-opens java.base/sun.security.pkcs11=ALL-UNNAMED bayraklarını ekleyin.

Bu adımların ardından pcsc_scan komutu ile kartın başarıyla okunduğunu teyit edip e-fatura ve e-defter imzalama servisinizi sorunsuz çalıştırabilirsiniz.

Kabul Edilen Yanıt 15 faydalı
Tolga R.
Yakın zamanda

Bu hatanın sebebi kütüphanenin yokluğu değil, Linux'ta libpcsclite1 ve pcscd bağımlılıklarının kurulu olmamasıdır. apt-get install pcscd libpcsclite1 komutlarıyla gerekli paketleri yükleyin ve Docker konteynerını başlatırken /var/run/pcscd/pcscd.comm soketini içeriye volume olarak bağlayın. Kartı terminalde pcsc_scan ile görebiliyorsanız imzalama da başlayacaktır.

Topluluk Katkısı 15 faydalı
Emre Ç.
Yakın zamanda

Docker konteynerlarında libakisp11.so kütüphanesini çalıştırırken konteynerın ana makinedeki USB donanımına erişebilmesi için docker run --privileged -v /dev/bus/usb:/dev/bus/usb bayrakları verilmelidir. Ayrıca Alpine Linux gibi musl-libc tabanlı imajlar yerine glibc içeren Debian/Ubuntu tabanlı base imaj kullanılması gerekmektedir.

Topluluk Katkısı 15 faydalı
DevOps Mühendisi Erdem Ç.
Konteyner Mimarisi Uzmanı
Yakın zamanda