🔐 Sign API

Türkiye e-imza standartlarına uygun elektronik imza (XAdES, PAdES, WS-Security) servisi.

---

🙌 Katkıda Bulunanlar

Bu projeye emek veren herkese içtenlikle teşekkür ederiz. Kod katkısı yapan, önerileriyle geliştirmeye yön veren veya hataları fark edip bildiren herkes, projenin bugün olduğu noktaya gelmesinde önemli bir paya sahip.

Aynı şekilde, geliştirme sürecinde destek sunan kurumlara da ayrıca teşekkür ederiz.Birlikte hareket etmenin, bilgiyi paylaşmanın ve ortak bir değeri büyütmenin kıymetini çok iyi biliyoruz.

Açık kaynağın gücüne inanıyor ve birlikte daha iyisini üretmeye devam ediyoruz. 🚀

Bireysel Katkı Sahipleri

Katkıda Bulunan	Kurum
@hasanyildiz	İZİBİZ Bilişim Teknolojileri Anonim Şirketi
@emresimsk	IDECON DANIŞMANLIK HİZMETLERİ ANONİM ŞİRKETİ
@Burak-Attila	EDM Bilişim
@batuhanonerr	NİLVERA YAZILIM VE BİLİŞİM HİZMETLERİ TİC. LTD. ŞTİ.
@ozlemkzn	e-Platform Bulut Bilişim A.Ş.

Kurumsal Destekçiler

Kurum	Katkı Türü
İzibiz	Geliştirme desteği
İdecon	Geliştirme desteği
EDM	Geliştirme desteği
NİLVERA	Geliştirme desteği
e-Platform	Geliştirme desteği

Öne Çıkan Pull Request / Issue Katkıları

Tür	Referans	Açıklama	Katkıda Bulunan
PR	#3	TÜBİTAK XAdES için ECDSA doğrulama özelleştirmeleri	@hasanyildiz
PR	#6	PKCS#11 slot ve slotListIndex yapılandırması geliştirmesi	@hasanyildiz
PR	#8	WS-Security imzalama düzeltmesi	@batuhanonerr
PR	#10	UBLExtensions eksik element oluşturma düzeltmesi	@batuhanonerr
PR	#11	CAdES-BES imzalama desteği	@Burak-Attila
PR	#12	e-Bilet rapor tipi ve XAdES-A desteği	@ozlemkzn

---

📚 Tam Dökümantasyon

👉 Sign Platform Dökümanları 👈

Tüm detaylı dökümantasyon merkezi dökümantasyon sitesinde bulunur:

• 📖 Kurulum ve yapılandırma
• 🚀 Hızlı başlangıç kılavuzu
• 🔐 Sertifika yönetimi ve seçimi
• ⚙️ Docker ve Kubernetes deployment
• 📊 Monitoring ve performance tuning
• ⏰ Zaman damgası servisi
• 🇹🇷 TÜBİTAK entegrasyonu
• 💡 Kod örnekleri ve kullanım senaryoları
• 🔧 DSS override detayları
• 🧪 Test stratejileri
• 🔒 Güvenlik en iyi pratikleri

---

⚡ Hızlı Başlangıç

Test Sertifikası ile (5 Dakika)

Unix/Linux/macOS:

./scripts/unix/quick-start-with-test-certs.sh

Windows:

.\scripts\windows\quick-start-with-test-certs.ps1

Docker ile

cd devops/docker
docker-compose up -d

Manuel

export PFX_PATH=./resources/test-certs/testkurum01@test.com.tr_614573.pfx
export CERTIFICATE_PIN=614573
mvn spring-boot:run

API: http://localhost:8085
Docs: http://localhost:8085/ (Scalar UI)
Health: http://localhost:8085/actuator/health

---

🎯 Özellikler

• ✅ XAdES: e-Fatura, e-Arşiv, XML imzalama
• ✅ CAdES: CMS tabanlı elektronik imzalama (CAdES-BES)
• ✅ PAdES: PDF dijital imzalama
• ✅ WS-Security: SOAP imzalama
• ✅ Timestamp: RFC 3161 (TÜBİTAK ESYA desteği)
• ✅ HSM/PKCS#11: Donanım güvenlik modülü
• ✅ KamuSM Root Sertifika Desteği - Online ve Offline mod desteği
  • Online Mod: Otomatik olarak http://depo.kamusm.gov.tr/depo/SertifikaDeposu.xml adresinden yüklenir
  • Offline Mod: Yerel dosya sisteminden belirtilen path'ten yüklenir
• ✅ Production Ready: Monitoring, logging, metrics

---

📖 Örnek Kullanım

# e-Fatura imzalama
curl -X POST http://localhost:8085/v1/xadessign \
  -F "document=@efatura.xml" \
  -F "documentType=UblDocument" \
  -o signed-efatura.xml

# PDF imzalama
curl -X POST http://localhost:8085/v1/padessign \
  -F "document=@document.pdf" \
  -o signed.pdf

Daha fazla örnek: Örnekler

---

🛠️ Gereksinimler

• Java 8+
• Maven 3.6+
• PFX sertifikası veya HSM

---

📂 Proje Yapısı

sign-api/
├── src/main/java/          # Java kaynak kodları
├── devops/                 # Docker, K8s, monitoring
├── scripts/                # Yardımcı scriptler
├── resources/test-certs/   # Test sertifikaları
└── examples/               # Kullanım örnekleri

---

⚙️ Konfigürasyon

Güvenilir Kök Sertifika Resolver Kullanımı

Sistem üç farklı resolver tipini destekler. TRUSTED_ROOT_RESOLVER_TYPE parametresi ile seçim yapılır.

1. KamuSM XML Depo Online (Varsayılan)

Varsayılan olarak, KamuSM root ve ara sertifikaları otomatik olarak şu adresten yüklenir:

• http://depo.kamusm.gov.tr/depo/SertifikaDeposu.xml

Bu sayede her zaman güncel sertifikalar kullanılır. Periyodik olarak otomatik yenilenir (varsayılan: her gün saat 03:15).

export TRUSTED_ROOT_RESOLVER_TYPE=kamusm-online
export KAMUSM_ROOT_URL=http://depo.kamusm.gov.tr/depo/SertifikaDeposu.xml
export KAMUSM_ROOT_REFRESH_CRON="0 15 3 * * *"  # Her gün saat 03:15

2. KamuSM XML Depo Offline

Offline ortamlarda veya internet bağlantısı olmayan sistemlerde, KamuSM sertifika deposunu yerel dosya sisteminden yükleyebilirsiniz:

export TRUSTED_ROOT_RESOLVER_TYPE=kamusm-offline
export KAMUSM_ROOT_OFFLINE_PATH=file:/path/to/SertifikaDeposu.xml
# veya classpath'ten
export KAMUSM_ROOT_OFFLINE_PATH=classpath:certs/SertifikaDeposu.xml

Offline Mod Kullanım Senaryoları:

• Air-gapped (izole) sistemler
• İnternet bağlantısı olmayan ortamlar
• Güvenlik gereksinimleri nedeniyle dış bağlantı kısıtlamaları
• Yerel sertifika deposu kullanımı

Not: Offline modda sertifikalar sadece uygulama başlangıcında yüklenir. Otomatik yenileme yapılmaz.

3. Certificate Folder Resolver

Belirtilen klasördeki tüm .crt, .cer ve .pem dosyalarını güvenilir kök sertifika olarak yükler. Bu resolver, özel sertifika klasörlerinden sertifika yüklemek için idealdir.

export TRUSTED_ROOT_RESOLVER_TYPE=certificate-folder
export TRUSTED_ROOT_CERT_FOLDER_PATH=/path/to/certificates
# veya file: prefix ile
export TRUSTED_ROOT_CERT_FOLDER_PATH=file:/path/to/certificates

Certificate Folder Resolver Kullanım Senaryoları:

• Özel sertifika klasörlerinden yükleme
• Kurumsal CA sertifikalarının toplu yüklenmesi
• Test ortamlarında özel sertifika kullanımı
• Farklı kaynaklardan sertifika birleştirme

Not: Klasördeki tüm geçerli sertifika dosyaları otomatik olarak yüklenir. Alt klasörler taranmaz.

---

🔗 Önemli Bağlantılar

Dosya	Açıklama
dss.mersel.dev	📚 Merkezi Dökümantasyon
LICENSE	MIT Lisansı
CHANGELOG.md	Versiyon geçmişi
CONTRIBUTING.md	Katkıda bulunma rehberi
SECURITY.md	Güvenlik politikası
TEST_CERTIFICATES.md	Test sertifikaları
DSS_OVERRIDE.md	DSS özelleştirmeleri

---

🤝 Katkıda Bulunma

CONTRIBUTING.md dosyasına bakın.

---

📄 Lisans

MIT

---

💡 Hatırlatma

Detaylı dökümantasyon, API referansları, deployment rehberleri ve tüm güncellemeler için:

👉 https://dss.mersel.dev merkezi dökümantasyon sitesini ziyaret edin! 📚