Docker Linux container (Debian/Alpine) üzerinde pcscd ve PKCS#11 ile e-imza token erişiminde 'SCARD_E_NO_SERVICE' ve USB passthrough hatası
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 üzerindesudo systemctl enable --now pcscd.socketkomutuyla soket tabanlı aktivasyonu etkinleştirin. - 2. Unix Domain Socket'i Konteynere Bağlayın (Volume Mount): Konteyner içinde tekrar bir
pcscdservisi başlatmayın. Yalnızca istemci kütüphanesi olanlibpcsclite1paketini 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'takipcscdgrubuna 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
--privilegedbayrağı ve/dev/bus/usbbağlaması ile başlatmalı, konteyner entrypoint scriptindepcscd --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.
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.
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.