DONANIM & SÜRÜCÜ LABORATUVARI: AKİS • SAFENET • GEMALTO • PALADIN
E-İmza Rehberi SMARTCARD // TOKEN LAB

Docker Linux container (Debian/Alpine) üzerinde pcscd ve PKCS#11 ile e-imza token erişiminde 'SCARD_E_NO_SERVICE' ve USB passthrough hatası

Mikroservis mimarisine geçiş kapsamında Linux (Debian tabanlı) Docker konteyneri içinde arka planda toplu PDF imzalayan bir e-imza mikroservisi koşturuyoruz. Fiziksel sunucudaki USB e-imza token'ını (/dev/bus/usb) konteynere bağlamamıza ve pcscd paketini kurmamıza rağmen, PKCS#11 kütüphanesi akıllı kartı okumaya çalışırken 'SCARD_E_NO_SERVICE' ve 'CKR_DEVICE_ERROR' hataları alıyoruz. Docker container içerisinde e-imza donanımına ve akıllı kart okuyucu daemon servisine kesintisiz erişim sağlamak için pcscd.comm soketi, IPC izinleri ve kütüphane bağlantısı nasıl yapılandırılmalıdır?
Durum: Çözüldü Kategori: Soru-Cevap

3 Cevap Nasıl Uygulanır?

Docker konteyneri içerisinde akıllı kart ve e-imza token'larına erişirken alınan SCARD_E_NO_SERVICE (0x8010001D) ve CKR_DEVICE_ERROR hataları, Linux PC/SC (Personal Computer/Smart Card) mimarisinin çalışma prensibinden kaynaklanan klasik bir soket ve IPC (Inter-Process Communication) iletişim problemidir.

5070 Sayılı Elektronik İmza Kanunu standartlarına uygun PKCS#11 ara katman kütüphaneleri (örneğin Akis için libakisp11.so veya SafeNet için libeTPkcs11.so), kart okuyucuyla doğrudan USB seviyesinde konuşmaz; bunun yerine sistemde arka planda çalışan pcscd (PC/SC daemon) servisi ile bir Unix Domain Socket (/run/pcscd/pcscd.comm) üzerinden haberleşir.

Hem ana makinede (host) hem de konteyner içerisinde ayrı ayrı pcscd çalıştırmaya çalışmak, Linux çekirdeğinin USB cihazı üzerinde özel kilit (exclusive lock) kurması nedeniyle çakışmaya yol açar ve konteynerdeki servis soketi açamaz. Doğru ve kararlı üretim (production) mimarisi için şu adımları uygulamalısınız:

  • 1. pcscd Servisini Ana Makinede (Host) Çalıştırın: Kart okuyucuyu ve sürücüleri (pcscd, libccid, pcsc-tools) doğrudan host işletim sisteminde çalışır durumda bırakın. Host üzerinde sudo systemctl enable --now pcscd.socket komutuyla soket tabanlı aktivasyonu etkinleştirin.
  • 2. Unix Domain Socket'i Konteynere Bağlayın (Volume Mount): Konteyner içinde tekrar bir pcscd servisi başlatmayın. Yalnızca istemci kütüphanesi olan libpcsclite1 paketini konteyner Dockerfile'ına ekleyin. Ardından host üzerindeki iletişim soketini konteynere mount edin:
    docker run -d --name eimza-service -v /run/pcscd/pcscd.comm:/run/pcscd/pcscd.comm -v /dev/bus/usb:/dev/bus/usb your-eimza-image
  • 3. Kullanıcı İzinlerini Ayarlayın: Konteyner içerisinde imzalama yapan uygulamanın çalıştığı kullanıcının (örneğin appuser), host üzerindeki soket dosyasına okuma/yazma hakkı olduğundan emin olun. Gerekirse konteyner kullanıcısını host'taki pcscd grubuna karşılık gelen GID ile eşleştirin.
  • 4. Bağımsız Konteyner (Host Desteği Olmayan) Yaklaşımı: Eğer host üzerinde pcscd kurulamıyorsa, konteyneri --privileged bayrağı ve /dev/bus/usb bağlaması ile başlatmalı, konteyner entrypoint scriptinde pcscd --foreground --auto-exit & komutunu arka planda tetikleyip soketin oluşmasını bekledikten sonra imza uygulamanızı başlatmalısınız.

Host soketini içeriye bağlama (socket forwarding) yöntemi, kaynak tüketimini minimuma indirir, USB kilitlenme sorunlarını tamamen ortadan kaldırır ve mikroservisinizin donanımsal Nitelikli Elektronik Sertifika (NES) ile kararlı biçimde çalışmasını sağlar.

Kabul Edilen Yanıt 15 faydalı
DevOps Mimarı Tolga K.
Yakın zamanda

Konteyner ortamında USB passthrough ile uğraşmak yerine, sunucu mimarilerinde fiziksel USB token'ı bir USB-over-IP (örneğin usbip veya donanımsal USB cihaz sunucusu) aracılığıyla ağ üzerinden bağlamayı düşünebilirsiniz. Ayrıca konteyner içinden pcsc_scan komutunu çalıştırarak kartın ATR (Answer to Reset) değerinin okunup okunmadığını test etmeniz hata ayıklama sürecini çok hızlandırır. Son olarak, yoğun kurumsal imzalama işlemlerinde USB token'lar eşzamanlı istekleri kaldıramayacağından, 5070 sayılı kanuna uygun bir Donanımsal Güvenlik Modülü (HSM) veya bulut tabanlı e-imza servisine geçiş yapılması uzun vadede çok daha sağlıklı olacaktır.

Topluluk Katkısı 15 faydalı
Sistem Müh. Serkan D.
Yakın zamanda

Alpine Linux üzerinde musl libc kütüphanesi kullanıldığından, Türkiye'deki ESHS'lerin (Kamu SM, AKİS vb.) sunduğu glibc tabanlı kapalı kaynak PKCS#11 .so sürücüleri doğrudan çalışmaz ve segmentation fault verir. Bu nedenle mikroservis konteynerlerinizde taban imaj olarak Alpine yerine debian:bookworm-slim veya ubuntu:22.04 kullanmanız şarttır. Ayrıca host makinede systemctl enable --now pcscd.socket yapılandırması yapılarak socket aktivasyonunun hazırda tutulması, 'SCARD_E_NO_SERVICE' hatasını kökten çözecektir.

Topluluk Katkısı 15 faydalı
Açık Kaynak Sistem Mühendisi Emre Ç.
Yakın zamanda