Web Uygulamalarında E-İmza Entegrasyonu: JavaScript ve WebSocket Kütüphaneleri
Google Chrome, Firefox ve Safari tarayıcılarının Java Applet ve NPAPI eklenti desteğini tamamen sonlandırmasıyla birlikte web tabanlı e-imza entegrasyonu modern WebSocket mimarisine evrilmiştir.
1. Localhost Agent Mimarisi Nasıl Çalışır?
Kullanıcının bilgisayarında çalışan hafif bir arka plan servisi (Örn: C# veya Go ile yazılmış yerel ajan), ws://localhost:8443 veya yerel HTTPS portu üzerinden dinleme yapar. Web sayfası JavaScript kodu bu ajana imzalanacak verinin özetini (SHA-256 hash) iletir; ajan PKCS#11 üzerinden USB token'daki anahtarla özeti imzalayıp web sayfasına döndürür. Konuyla ilgili teknik gereksinimler ve mevzuat adımları için Çok Faktörlü Kimlik Doğrulamada SIM Swap ve Session Hijacking Saldırılarını Önleme rehberimizden de faydalanabilirsiniz.
2. WebAssembly ve WebUSB Geleceği
Geleceğin LegalTech web uygulamalarında harici ajan kurulumuna gerek kalmadan, W3C WebUSB API standartları ve WebAssembly (Wasm) kütüphaneleriyle tarayıcının doğrudan akıllı kartla konuşabilmesi hedeflenmektedir. Konuyla ilgili teknik gereksinimler ve mevzuat adımları için Kurumsal SaaS Platformlarında FIDO2 Passkey Entegrasyonu rehberimizden de faydalanabilirsiniz.
5070 Sayılı Elektronik İmza Kanunu ve W3C Modern Web Tarayıcı Güvenlik Standartları: Web tarayıcılarında Java Applet desteğinin (NPAPI) sona ermesiyle birlikte, istemci bilgisayarındaki akıllı karta erişim yerel WebSocket (127.0.0.1) köprü istemcileri aracılığıyla yasal standartlara uygun yürütülür.
Tarayıcı İstemcisi, Yerel WebSocket Köprüsü (Localhost) ve PKCS#11 DLL Çağrıları
Modern bir web uygulamasında (SaaS ERP, Hukuk Portalı, Bankacılık) kullanıcının e-İmza atabilmesi için 3 katmanlı bir mimari çalışır: 1) Sunucu Katmanı: İmzalanacak belgenin özetini (SHA-256 Hash) hesaplar ve web arayüzüne gönderir. 2) Web Arayüzü: JavaScript üzerinden yerel bilgisayarda çalışan arka plan uygulamasına `wss://127.0.0.1:port` üzerinden bağlanır. 3) Yerel Köprü (ArkSigner / Kamu SM İstemcisi): PKCS#11 kütüphanesini (`akisp11.dll`) çağırarak akıllı karttaki özel anahtarla hash'i imzalar. İmzalanan özet JavaScript üzerinden sunucuya döner ve belgeye iliştirilir; böylece megabaytlarca dosya internete yüklenmeden milisaniyeler içinde imzalanır.
Web Tabanlı e-İmza Entegrasyon Mimarileri Karşılaştırması
| Entegrasyon Modeli | İstemci Yükü | Tarayıcı Uyumluluğu | Hız ve Performans |
|---|---|---|---|
| Yerel WebSocket Köprüsü (Önerilen) | Küçük bir arka plan servisi kurulur | Tüm Modern Tarayıcılar (Chrome, Edge, Safari) | Çok Hızlı (Yalnızca hash taşınır) |
| WebCrypt / Tarayıcı Eklentisi | Özel tarayıcı eklentisi gerektirir | Yalnızca desteklenen masaüstü tarayıcılar | Hızlı ancak eklenti bakım yükü yüksek |
| Java Web Start (JNLP) | Java JRE kurulumu zorunlu | Tarayıcı dışı harici pencerede açılır | Yavaş ve kullanıcıyı sistemden koparır |
| Bulut e-İmza (Uzaktan İmza) | Kullanıcıda sıfır donanım/yazılım | Tüm Mobil ve Web Tarayıcıları | Anlık (Özel anahtar HSM'de saklanır) |
En Sık Karşılaşılan 3 Uygulama Hatası ve Çözüm Yolları
HTTPS sitelerde güvenli olmayan ws:// soketi tarayıcı tarafından 'Karma İçerik' gerekçesiyle engellenir.
Kural: Dosya asla istemciye inmez, yalnızca sunucuda hesaplanan 32 byte'lık SHA-256 hash imzalanır.
Uygulama kurulum paketinde antivirüs istisnası ve SSL kök sertifika tanımı bulunmalıdır.
Büyük bir İK yazılımı şirketi, bordro onayları için Java Applet kullanırken sürekli destek çağrısı almaktaydı. Yazılım ekibi yerel hafif bir WebSocket köprüsü geliştirmiş; web sayfası tek tıkla kullanıcının akıllı kartına bağlanarak bordro hash'ini 2 saniyede imzalatmış ve destek talepleri %95 oranında azalmıştır.
Uygulama ve Denetim Kontrol Listesi (Checklist)
- Sunucu tarafında belgenin CAdES veya PAdES formatına uygun SHA-256 hash'ini hesaplayan kütüphaneyi kurun.
- Kullanıcı tarafında çalışacak hafif yerel istemcinin (Localhost Service) Windows ve Mac kurulum paketlerini hazırlayın.
- Yerel istemciye geçerli bir 127.0.0.1 yerel SSL sertifikası tanımlayarak `wss://` bağlantısını garantiye alın.
- JavaScript API üzerinden akıllı kart takılı mı, sertifika geçerli mi kontrollerini yapın.
- İmza sonucunu sunucuya döndürerek doğrulama servisinden (CRL/OCSP) yeşil onay aldığını kontrol edin.