Docker konteyner içinde e-imza (PKCS#11) kullanımı: USB pass-through, pcscd socket paylaşımı ve CKR_DEVICE_ERROR çözümü
3 Cevap Nasıl Uygulanır?
Linux işletim sistemi çekirdeğinde USB tabanlı akıllı kart okuyucular (CCID uyumlu dongle'lar), donanım seviyesinde yalnızca tek bir akıllı kart arka plan servisi (pcscd daemon) tarafından kilitlenebilir (exclusive lock).
Docker konteyneri içerisine --device=/dev/bus/usb bayrağıyla tüm USB veri yolunu verip hem host makinede hem de konteyner içerisinde ayrı ayrı iki adet pcscd servisi çalıştırdığınızda, kernel seviyesinde USB arayüzü paylaşım çatışması (resource contention) yaşanır. Bunun sonucunda PKCS#11 ara katmanı karta erişemez ve doğrudan CKR_DEVICE_ERROR (0x00000030) veya CKR_TOKEN_NOT_PRESENT hatası fırlatır.
Docker Ortamında PKCS#11 Entegrasyonunun Doğru ve Standart Mimarisi:
Doğru yaklaşım, USB cihazını konteyner içine doğrudan passthrough yapmak yerine, Host makinedeki PC/SC IPC Socket dosyasını konteyner içine bağlamaktır (Socket Sharing). Adım adım uygulanması gereken yöntem şöyledir:
- 1. Host Makinede Tek Bir pcscd Çalıştırmak: Host işletim sisteminde (Ubuntu)
pcscdservisinin aktif ve çalışır durumda olduğundan emin olun (sudo systemctl enable --now pcscd). Host üzerindepcsc_scankomutunu çalıştırdığınızda token'ın ve ATR değerinin sorunsuz okunduğunu teyit edin. - 2. IPC Socket Dosyasının Paylaşılması: Linux'ta PC/SC istemcileri daemon ile
/run/pcscd/pcscd.commUnix domain socket dosyası üzerinden haberleşir. Docker konteynerinizi başlatırken bu socket dosyasını volume olarak bağlayın:docker run -d \ --name eimza-service \ -v /run/pcscd/pcscd.comm:/run/pcscd/pcscd.comm \ my-eimza-app:latest - 3. Konteyner İçinde pcscd Çalıştırmamak: Docker imajınızın (Dockerfile) içine kesinlikle
pcscdservisini başlatacak bir komut (CMD/ENTRYPOINT) koymayın. Konteyner içinde yalnızca istemci kütüphaneleri olanlibpcsclite1ve ilgili akıllı kart PKCS#11 sürücüsü (örneğin AKİS içinlibakisp11.soveya SafeNet içinlibeToken.so) kurulu olmalıdır. - 4. Kullanıcı İzinleri ve GID Eşitlemesi: Konteyneriniz root olmayan bir kullanıcıyla (non-root container) çalışıyorsa, host üzerindeki
pcscd.commsocket dosyasına okuma/yazma izni olmalıdır. Host'taki socket izin grubunu kontrol edip Docker kullanıcısını aynı GID'ye sahip bir gruba dahil edin.
Bu mimari sayesinde donanım yönetimi tek bir noktadan (host kernel) güvenle yapılırken, konteyner içindeki Spring Boot uygulaması IPC socketi üzerinden token ile doğrudan PKCS#11 oturumu açabilir ve sıfır hata ile imzalama yapabilir.
Eğer uygulamanız Kubernetes (K8s) kümesinde çalışacaksa veya birden fazla pod aynı anda e-imza atmak zorundaysa, host socket bağlama yöntemi podların tek bir fiziksel sunucuya kilitlenmesine (node pinning / affinity) neden olur. Bu tarz dağıtık bulut senaryolarında donanımsal USB dongle yerine doğrudan ağ üzerinden konuşabilen Ağ Tabanlı Donanım Güvenlik Modülü (Network HSM) kullanmak kurumsal standarttır.
Bütçe nedeniyle HSM alamıyorsanız, geçici bir alternatif olarak token'ın takılı olduğu sunucuda hafif bir Python veya Go tabanlı imza mikroservisi çalıştırıp, Docker konteynerlerinizin bu servise gRPC veya mTLS korumalı REST API ile sadece belgenin hash özetini göndermesini sağlayabilirsiniz. Böylece konteyner içine hiçbir C kütüphanesi veya socket bağlamadan imzayı uzaktan alabilirsiniz.
Docker konteynerine USB cihazını doğrudan bağlamak yerine host makinede pcscd servisini çalıştırıp UNIX domain socket'ini (/run/pcscd/pcscd.comm) konteynere volume olarak bağlamak (-v /run/pcscd/pcscd.comm:/run/pcscd/pcscd.comm) en kararlı çözümdür. Ayrıca konteyner içine libpcsclite1 paketinin ve akıllı kart sürücüsünün (örneğin AKİS için libakisp11.so) kurulması gerekir. CKR_DEVICE_ERROR hatası genellikle konteyner içinde yetki kısıtlamasından kaynaklanır; docker run komutuna --device /dev/bus/usb ve --cap-add=SYS_RAWIO veya geçici test için --privileged ekleyerek donanım erişim izinlerini denetleyin.