QES / NES Native Helper Uyum Beyanı

1. Yasal Çerçeve

1.1 5070 Sayılı Elektronik İmza Kanunu (Türkiye)

5070 sayılı Kanun, Türkiye'de elektronik imzaların yasal çerçevesini belirler:

• Madde 4 — Güvenli Elektronik İmza: münhasıran imza sahibine bağlı, imza sahibinin tasarrufunda bulunan güvenli imza oluşturma aracı ile oluşturulan, nitelikli elektronik sertifikaya dayanan imzadır.
• Madde 5/1 — Eşdeğerlik: "Güvenli elektronik imza, elle atılan imza ile aynı hukuki sonucu doğurur."
• Madde 5/2 — İstisnalar: Kanunların resmî şekle veya özel bir merasime tabi tuttuğu işlemler (gayrimenkul, evlenme, vasiyet, kefalet vb.) e-imza ile yapılamaz. Detay için Kullanım Koşulları.

imzala.org Native Helper akışında BTK lisanslı ESHS tarafından düzenlenmiş kullanıcı sertifikası + Türk yetkili TSA (TÜBİTAK KAMU SM Zamane) bileşimi 5070 m.4 koşullarını karşıladığı için ortaya çıkan imza Madde 5/1 anlamında elle atılan imza ile aynı hukuki sonuçu doğurmayı hedefler. Nihai hukuki nitelendirme her zaman somut olayın koşullarına ve mahkeme takdirine bağlıdır.

1.2 eIDAS Tüzüğü 910/2014 (Avrupa Birliği)

AB Tüzüğü 910/2014 elektronik imzalar için üç düzey tanımlar (SES / AES / QES):

Art.25(2): "Bir nitelikli elektronik imza (QES), el yazısı imzanın hukuki sonuçlarına eşdeğer hukuki etkiye sahiptir."

Art.25(3): "Bir AB üye devletinde düzenlenen QES, diğer tüm üye devletlerde QES olarak tanınır."

Türkiye-AB Sınır Ötesi: Türkiye AB EU Trusted List (LOTL/TSL)'de yer almamaktadır. Bu nedenle Türk ESHS sertifikası ile atılan bir imza AB üye devletlerinde otomatik olarak QES sayılmaz; karşılıklı tanıma için eIDAS Art.14 uyarınca uluslararası anlaşma gerekir. AB tarafına imza atılan sözleşmelerde karşı tarafın hukuk müşaviriyle teyit almak Kullanıcı'nın yükümlülüğündedir. Detaylı bilgi: Kullanım Koşulları § 18 (Sınır Ötesi İşlemler).

1.3 HMK m.205/2 — Türk İspat Hukuku

6100 sayılı Hukuk Muhakemeleri Kanunu m.205/2: "Güvenli elektronik imza ile oluşturulan elektronik veriler senet hükmündedir." — yani senet niteliğindeki bir delil sunmuş olursunuz.

2. Teknik Standart Uyumu

2.1 PAdES B-LTA (ETSI EN 319 142-1 v1.2.1)

Helper akışında üretilen PDF imzaları aşağıdaki PAdES (PDF Advanced Electronic Signatures) yapısal seviyelerini destekler:

• B-B (Basic) — temel CMS imzası (imzalayan sertifikası gömülü)
• B-T (Timestamp) — imza üzerine RFC 3161 zaman damgası (TÜBİTAK KAMU SM Zamane)
• B-LT (Long-Term) — DSS sözlüğü ile OCSP/CRL revocation bilgileri gömülü
• B-LTA (Long-Term with Archive) — arşiv zaman damgası, 24 saat sonra PadesLtUpgradeWorker tarafından eklenir

Bu seviyeler, sertifika geçerlilik süresi dolduktan sonra dahi (10+ yıl) imzanın kriptografik doğrulanabilirliğini korur.

2.2 BTK Profil Rehberi (2012/DK-15/299)

BTK Profil Rehberi P1/P2/P3/P4 baseline'larına config-driven destek vardır:

• 5070 Marker OID: 2.16.792.1.61.0.1.5070.3.2.1 — TR-only deployment modunda SignaturePolicyIdentifier içine gömülür
• AB deployment modunda QES_SIGNATURE_POLICY_OID boş bırakılır → eIDAS evrensel kabul
• Aynı USB token ile her iki mod kanıtlanmıştır (POC çıktısı: AYYILDIZ NES Token, 11 Mayıs 2026)

2.3 RFC 3161 Zaman Damgası

• Birincil TSA: TÜBİTAK KAMU SM Zamane (Policy OID 2.16.792.1.2.1.1.5.7.3.1), zamane-service üzerinden RFC 3161 forwarder
• Yedek konfigürasyon: EU Qualified TSA fallback için config knob'lar hazır (TSA_FALLBACK_URL + TSA_USE_FALLBACK_FOR_EU) — paralı EU QTSA kontratı EU müşteri çıkana kadar imzalanmayacaktır
• Resilience: 5 deneme synchronous retry (~31s budget) + B-T → B-B fallback; başarısız damgalar 24 saat içinde PadesLtUpgradeWorker ile tekrar denenir

2.4 Diğer Standartlar

• ETSI EN 319 102-1 v1.4.1 — AdES imza oluşturma + doğrulama prosedürü
• RFC 5280 — X.509 PKI sertifika profili
• RFC 6960 — OCSP gerçek zamanlı revocation sorgu
• PKCS#11 v2.40 — USB token cryptographic interface

3. Native Helper — imzala-qes-helper

3.1 Mimari

Helper, kullanıcının cihazında lokal çalışan bir Tauri 2.x + Rust masaüstü uygulamasıdır. Browser SDK (qes-signer.js) ile wss://127.0.0.1:8765 üzerinden TLS-self-signed WebSocket bağlantısıyla iletişim kurar. Java JRE veya .NET gerekmez; ~15 MB bundle boyutu.

• Kritik PKCS#11 çağrıları (C_Login, C_Sign) bundled bir sign-worker subprocess'inde çalışır; macOS'ta com.apple.security.smartcard entitlement'lı code-signed binary'dir
• Tüm PKCS#11 çağrıları helper içinde tek bir std::thread'de serialize edilir — Tokio multi-thread race koşulu yoktur
• Apple PCSC bug #19374107 (Yosemite 2014'ten beri açık, fix yok) process isolation + dedicated thread + entitlement + api.prevent_exit() kombinasyonuyla aşılır

3.2 PIN Güvenlik Modeli

Kullanıcının USB token PIN'i:

• Browser'a, network'e, log'a, parent helper bellek'ine ASLA dokunmaz; yalnızca sign-worker subprocess'inin stdin pipe'ında yer alır
• Subprocess imza dönüşünden hemen sonra exit eder; OS PIN'i içeren bellek sayfalarını geri alır
• Audit log: imza zamanı, sertifika thumbprint (SHA-256), başarı/başarısızlık. PIN içeriği veya özel anahtar değeri kayıt edilmez
• Rust kaynak kodda zeroize crate ile PIN buffer'ları bellekten silinir

3.3 Token / Sertifika Yaşam Döngüsü

• Sertifika edinme: Kullanıcı yetkili bir ESHS'den (TÜBİTAK KAMU SM, E-Tuğra, TürkTrust, E-Güven, KamuSM, Arkimza vb.) USB token üzerinde nitelikli elektronik sertifika satın alır. imzala.org bu işleme dahil değildir.
• PKCS#11 driver: Kullanıcı ESHS'sinin sağladığı PKCS#11 sürücüsünü kendi cihazına kurar (Adobe Acrobat ile imzalayanların zaten yapmış olduğu adım). Helper otomatik tespit yapar; eksikse indirme linkini gösterir.
• Revocation: Sertifikanın iptali ESHS tarafından yapılır. Helper imza anında OCSP/CRL sorgusu yapar; revoked sertifika ile imza reddedilir.

3.4 Vendor Destek Matrisi

Helper, PKCS#11 standardına bağlı çalışır ve aşağıdaki ESHS donanımlarını hedefler:

ESHS / Üretici	Donanım	Durum
TÜBİTAK UEKAE / AKIS	AYYILDIZ NES Token (AKIS v2.0)	✓ Smoke test geçti (12 May 2026)
E-Tuğra	USB Token + Kart	⏳ Donanım kargo bekleniyor
TÜRKTRUST	Arnica USB Token	⏳ Donanım kargo bekleniyor
E-Güven	USB Token	⏳ Donanım tedariki
Kamu SM	NES Kart + okuyucu	⏳ Donanım tedariki + kurum müşteri akışı

"Smoke test geçti" = dev ortamında uçtan uca akış (sertifika tespit + PIN dialog + PAdES B-LTA imza + DSS doğrulama) çalıştırıldı. Prod kalitesinde dağıtım için Apple Developer ID notarization + Windows code signing + Linux paketleme adımları planlanmıştır.

4. İmza Akışı (Uçtan Uca)

1. Kullanıcı dashboard üzerinden imza talebine erişir.
2. Helper çalışıyorsa browser SDK WebSocket üzerinden bağlanır (kullanıcı helper'ı bir kez kurar).
3. Helper kullanıcı cihazındaki USB token sertifikalarını listeler; kullanıcı imza için kullanılacak sertifikayı seçer.
4. Helper sertifika public bilgisini browser'a, browser bunu backend'e gönderir.
5. Backend, imzalanacak PDF için signedAttributes hash'ini hazırlar; helper'a iletilir.
6. Helper işletim sistemi PIN dialog'u açar; kullanıcı PIN'i girer.
7. sign-worker subprocess hash'i USB token'a imzalatır; imza değerini stdout'a yazar; exit eder.
8. Browser SDK imza değerini backend'e iletir; backend CMS yapısını birleştirir, RFC 3161 zaman damgası uygular, PDF'e gömer.
9. Backend S3'e PAdES B-T imzalı PDF yükler; PadesLtUpgradeWorker 24 saat sonra B-LT/B-LTA upgrade yapar.

5. Hata Senaryoları

• Helper kurulu değil: Kullanıcıya helper indirme linki gösterilir.
• Token takılı değil: Helper "Token bulunamadı" hatası döner; kullanıcı SES akışına yönlendirilebilir.
• PKCS#11 driver eksik: Helper hangi vendor için hangi sürücü gerektiğini söyler.
• PIN hatalı: Üç deneme hakkı (PKCS#11 standart davranışı), sonrasında token kilitlenir; bu yalnızca ESHS tarafından açılabilir.
• Sertifika revoked: İmza reddedilir; kullanıcı yeni sertifika alması için bilgilendirilir.
• TSA erişilemez: 5 deneme synchronous retry → B-B fallback (sadece signer cert); 24 saat içinde upgrade worker B-T / B-LT / B-LTA ekler.

6. Audit Trail

• Helper local audit log: imza zamanı + cert thumbprint + başarı/başarısızlık (PIN içeriği yok)
• Backend audit log: QesSigningEvent tablosunda (Prisma) imza akışının her aşaması (PREPARED → SIGNED → TIMESTAMPED → LT_UPGRADED → LTA_UPGRADED)
• İmzalı PDF üzerinde Adobe Reader / DSS validator ile bağımsız doğrulama yapılabilir

7. Sınırlar ve Sorumluluklar

7.1 imzala.org Sorumlulukları

• Helper + browser SDK + backend imza akışının teknik bütünlüğü
• PAdES B-T → B-LT → B-LTA upgrade chain
• RFC 3161 zaman damgası entegrasyonu (TÜBİTAK KAMU SM)
• İmzalı PDF saklama ve doğrulama (10 yıl, TTK m.82 ile uyumlu)

7.2 Kullanıcı Sorumlulukları

• Yetkili bir ESHS'den nitelikli sertifika ve USB token temin etmek
• PKCS#11 sürücüsünü cihaza kurmak (ESHS yönlendirmesi ile)
• USB token ve PIN güvenliği
• Sertifika kaybı/çalınması durumunda ESHS'ye revocation talebi iletmek
• 5070 m.5/2 istisnaları kapsamındaki işlemleri (gayrimenkul, vasiyet, kefalet vb.) e-imza ile yapmaya çalışmamak

7.3 ESHS / Donanım Sorumlulukları

• Nitelikli sertifikanın 5070 sayılı Kanun + ETSI EN 319 411-2 baseline'ına uygun üretimi
• USB token güvenli imza oluşturma aracı (SSCD/QSCD) kapasitesi
• OCSP / CRL revocation servisi
• PKCS#11 driver bakımı ve dağıtımı

8. Açık Kaynak ve Şeffaflık

Helper mimarisi Estonya Web-eID, AusweisApp ve OpenSC topluluğunun açık kaynak öğretilerinden ilham alır. Apple PCSC kısıtlamasına karşı geliştirdiğimiz katmanlı çözüm (process isolation + dedicated thread + entitlement + sign-worker exit-on-finish) prod kaliteli bir entegrasyon olarak Türk dijital imza ekosistemine katkımızdır. Helper'ın source code'unun aşamalı olarak public'leştirilmesi yol haritamızdadır.

9. Yol Haritası

• Faz B + D (test'te canlı, May 2026): Browser SDK + backend QES integration + Prisma audit modeli
• Faz C (sıradaki sprint): /imza UI'da NES toggle + qes-signer.js mount
• Donanım dağıtımı: 5+ ESHS donanımı uçtan uca doğrulama (kargolar geldikçe)
• Installer dağıtımı: Apple Developer ID notarization (macOS) + Authenticode (Windows) + .deb/.rpm (Linux)
• Mobile imza: BLE / NFC tabanlı QES (Arkimza modeli) ayrı bir sprint'tedir
• EU QTSA fallback: EU müşteri çıktığında paralı QTSA kontratı + LOTL refresh etkinleştirme

10. Kabul ve İletişim

imzala.org platformunda Native Helper akışıyla imza atan / talep eden taraflar bu beyandaki uyum çerçevesini ve sınırları kabul etmiş sayılır. Hukuki geçerlilik gerektiren işlemleriniz için somut olayın koşullarına göre bir hukuk danışmanına başvurmanızı öneririz.