Dijital İmza

ipucu

Bu doküman spesifik bir politikanın detaylı kullanımını anlatır. Eğer Apinizer politika yapısını ilk kez kullanıyorsanız veya politikaların genel çalışma prensiplerini öğrenmek istiyorsanız, öncelikle Politika Nedir? sayfasını okumanızı öneririz.

Genel Bakış

Amacı Nedir?

• İstek veya yanıt mesajının kritik bölümlerine dijital imza ekleyerek bütünlük ve inkâr edilemezlik sağlar.
• Gizli anahtarların merkezi yönetimi sayesinde imzalama sürecini standartlaştırıp denetlenebilir hale getirir.
• Farklı API Proxy (API Vekil Sunucusu) akışlarında yeniden kullanılabilir imza şablonları oluşturarak bakım maliyetini azaltır.
• Mesaj üzerine imza algoritması bilgisini isteğe bağlı ekleyerek doğrulama tarafının dinamik uyarlanmasına imkân tanır.

Çalışma Prensibi

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. Politika Kontrolü: Dijital İmza politikası aktif ise, sistem aşağıdaki sırayla kontrol yapar:
   • Condition (koşul) tanımlı mı? Varsa koşul sağlanıyor mu?
   • Politika aktif mi (active=true)?
   • Variable kullanılıyor mu yoksa Apinizer default mı?
3. Dijital İmza Üretimi: Tanımlı her imza kuralı için kaynak değişkendeki metin okunur, seçilen özel anahtar/sertifika ve algoritma ile imzalanır, çıktı seçilen kodlama (Base64/Hex) ile hedef değişkene yazılır; algoritma değişkeni tanımlıysa aynı anda güncellenir.
4. Karar Verme:
   • Eşleşme Var: Kaynak değişkende veri bulunursa imza üretilir ve hedef değişkene yerleştirilir.
   • Eşleşme Yok: Kaynak veri boşsa imza atlanır, hedef değişken boş değerle güncellenir ve akış devam eder.
5. Hata İşleme: Politika kuralına uymayan istekler için özelleştirilebilir HTTP durum kodu ve hata mesajı döndürülür.

Özellikler ve Yetenekler

Temel Özellikler

• Çoklu İmza Tanımı: Tek politika altında farklı mesaj alanlarını farklı algoritmalar ve anahtarlarla imzalama olanağı sağlar.
• Değişken Tabanlı Hedefleme: İmzalanacak veri ve imzanın yazılacağı alan için değişken seçimi yaparak hem istekte hem yanıtta esneklik sunar.
• Sertifika/Anahtar Entegrasyonu: Gizli anahtarlar veya sertifikalar Apinizer Secret Manager üzerinden seçilir, revokasyon kontrolleri otomatik yapılır.
• Aktif/Pasif Durum Kontrolü: Politikanın aktif veya pasif durumunu kolayca değiştirme (active/passive toggle). Pasif durumda politika uygulanmaz ancak yapılandırması saklanır.
• Koşul Bazlı Uygulama: Query Builder ile karmaşık koşullar oluşturarak politikanın ne zaman uygulanacağını belirleme (örn: sadece belirli endpoint'lere veya header değerlerine göre).

İleri Düzey Özellikler

• Dinamik Algoritma Yayını: signatureAlgorithmVar kullanılarak uygulanan algoritma adı mesaj içine yazdırılabilir ve tüketici sistemlere bilgi sağlar.
• Gelişmiş Değişken Yönetimi: Variable Update Dialog ile mevcut değişkenler üzerinde düzenleme yapmadan seçilip güncellenebilir.
• Anında Anahtar/Sertifika Oluşturma: Yapılandırma ekranından yeni Crypto Key veya sertifika kayıtları oluşturularak bekleme süresi olmadan politika güncellenir.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Geliştirme, Test, Canlı Ortam) import etme. Versiyon kontrolü ve yedekleme imkanı.
• Policy Group ve Proxy Group Desteği: Birden fazla politikayı Policy Group içinde yönetme. Proxy Group'lara toplu politika atama. Merkezi güncelleme ve deploy işlemleri.
• Deploy ve Versiyonlama: Politika değişikliklerini canlı ortama deploy etme. Hangi API Proxy'lerde kullanıldığını görme (Policy Usage). Proxy Group ve Policy Group kullanım raporları.

Kullanım Senaryoları

Senaryo	Durum	Çözüm (Politika Uygulaması)	Beklenen Davranış / Sonuç
REST Yanıtında JSON İmzalama	Dış sistemler yanıt gövdesinin bütünlüğünü doğrulamak istiyor	sourceVar=response.content, signatureVar=response.header.X-Signature, algoritma SHA256withRSA, Base64 çıktı, Crypto Key seç	Yanıt gönderilmeden önce imza hesaplanır, başlığa eklenir, doğrulama tarafı imzayı kontrol eder
SOAP İsteğinde Body İmzalama	ESB, gelen SOAP body'i imzalamak zorunda	sourceVar=request.soap.body, signatureVar=request.soap.header.Signature, algoritma SHA1withRSA, Hex çıktı, sertifika seç	İmza SOAP header'a eklenir, alt sistemler mesajın değişmediğini teyit eder
IoT Mesajında Algoritma Bildirimi	IoT ağ geçidi imzalama algoritmasını dinamik bildirmek istiyor	signatureAlgorithmVar=request.header.X-Sign-Alg tanımlanır, algoritma SHA512withECDSA	Mesaj hem imza hem algoritma adıyla zenginleşir, cihaz güncellemeye gerek kalmadan çalışır
Çoklu Alan İmzalama	Birden fazla JSON alanı ayrı anahtarlarla imzalanacak	İki farklı tanım ile farklı sourceVar ve Crypto Key seçilir	Her alan için bağımsız imza üretilir, tüketici taraf kombinasyon doğrulaması yapar
Mikroservisler Arası Yetkilendirme	Servisler arası çağrılarda kimlik doğrulaması için imza gerekiyor	İstek üstbilgisine imza eklenir, Condition ile sadece dahili çağrılarda çalışır	Mikroservis gelen isteğin gerçekten beklenen servisten geldiğini doğrular
Arşivleme Öncesi İmza	Belgeler saklanmadan önce değişmezlik garantisi isteniyor	Policy Group üzerinden toplu atanır, sourceVar belge içeriği, imza metadata alanına yazılır	Arşivlenen her belge imzalı hale gelir, denetimlerde kanıtlanabilirlik sağlanır
(opsiyonel) Veri Maskeleme Sonrası İmza	Maskelenmiş alanların değişmediğini göstermek için	Maskeleme politikası ardından çalıştırılır, aynı alan üzerine imza atılır	Maskelenmiş verinin bütünlüğü korunur, zincir halinde izlenebilir

Politika Parametrelerini Yapılandırma

Bu adımda, kullanıcı yeni bir politika oluşturabilir ya da mevcut politika parametrelerini yapılandırarak erişim kurallarını belirleyebilir. Tanımlanan parametreler, politikanın çalışma şeklini (örneğin hangi IP'lerin izinli olacağı, coğrafi kısıtlamalar, koşullu aktivasyonlar vb.) doğrudan etkiler. Bu sayede politika hem kuruma özel gereksinimlere göre özelleştirilebilir hem de merkezi olarak yönetilebilir.

Yeni Dijital İmza Politikası Oluşturma

Yapılandırma Adımları

Adım	Açıklama / İşlem
Adım 1: Oluşturma Sayfasına Gitme	- Sol menüden Development → Global Settings → Global Policies → Dijital İmza bölümüne gidin. - Sağ üstteki [+ Create] butonuna tıklayın.
Adım 2: Temel Bilgileri Girme	Policy Status (Politika Durumu): Aktif/Pasif durumu gösterir. Yeni politikalar varsayılan olarak aktiftir. Name (İsim) Zorunlu: Örnek: Production_DigitalSign - Benzersiz isim girin, boşlukla başlamaz. - Sistem otomatik kontrol eder. Yeşil tik: kullanılabilir. Kırmızı çarpı: mevcut isim. Description (Açıklama): Örnek: "Yanıt payload'ına HSM anahtarıyla imza ekler." - Maks. 1000 karakter. - Politikanın amacını açıklayın.
Adım 3: Variable Kullanımı	- Sayfanın üst kısmındaki işlem butonları alanında, [<> Variable] butonunu kullanarak dinamik değer seçebilirsiniz. - Context/global variable ifadeleri sayesinde politika parametrelerini sabit değer yerine değişken tabanlı yönetebilirsiniz. - Bu kullanım, değişen değerlerde manuel güncelleme ihtiyacını azaltır ve operasyonel kolaylık sağlar. - Detaylı bilgi için Dinamik Değişkenler sayfasını inceleyebilirsiniz.
Adım 4: İmza Tanımlarını Oluşturma	[+ Add] butonu ile imza tanımı açın. - sourceVar (imzalanacak veri kaynağı): İmzalanacak veriyi içeren değişkeni seçin. - signatureVar (imzanın yazılacağı hedef): İmzanın yazılacağı değişkeni seçin. - signatureAlgorithm: İmza algoritmasını seçin (örn: SHA256withRSA, SHA512withECDSA). - outputEncodingType: İmza çıktısının kodlama tipini seçin (BASE64 veya HEXADECIMAL). - signatureAlgorithmVar (isteğe bağlı): Algoritma bilgisinin yazılacağı değişkeni seçin.
Adım 5: Anahtar/Sertifika Seçimi	KEY seçilirse: - Crypto Key listesinden özel anahtar seçin veya yeni anahtar oluşturun. CERTIFICATE seçilirse: - Sertifika listesinden seçin. - ⚠️ Revoke edilmiş sertifikalar kırmızı etiketlenir, kullanılmamalıdır.
Adım 6: Çoklu Tanım ve Sıralama (Varsa)	- Farklı mesaj bölümleri için ek tanımlar ekleyin. - Her tanımı düzenleyerek farklı algoritma veya kodlama atayabilirsiniz. - Gerekmiyorsa tanımı [Delete] ile kaldırın.
Adım 7: Koşul Tanımlama (İsteğe Bağlı)	- Condition sekmesine geçin. - Koşullar, politikanın hangi durumda aktif olacağını belirler. Örnekler: - Ortam bazlı: Header = X-Environment, Operator = Equals, Value = production - API Key bazlı: Header = X-API-Key, Starts With = PROD- - Endpoint bazlı: Path = /api/admin/* Koşul tanımlamazsa politika her zaman aktif
Adım 8: Hata Mesajı Özelleştirme (İsteğe Bağlı)	- Error Message Customization sekmesine gidin. - Erişim reddedildiğinde dönecek mesajı özelleştirin. Varsayılan: { "statusCode": 500, "message": "Digital Signature policy failed! Error message is: {0}" } Özel: { "statusCode": 500, "errorCode": "ERR-088-CUSTOM", "message": "İmza üretilemedi, lütfen destinasyon alanını kontrol edin." }
Adım 9: Kaydetme	- Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: - Benzersiz isim - Zorunlu alanlar dolu - En az bir imza tanımı mevcut Sonuç: - Politika listeye eklenir. - API'lere bağlanabilir. - Global politikaysa otomatik uygulanır.

Koşullar ve Hata Mesajı Özelleştirme panellerinin açıklaması için Politika Nedir? sayfasındaki Koşullar ve Hata Mesajı Özelleştirme (Error Message Customization) bölümlerini inceleyebilirsiniz.

Hata mesajı yapılandırmasının tüm katmanları, öncelik sırası ve senaryo örnekleri için Hata Mesajı Yapılandırma Rehberi sayfasına bakın.

Politikayı Silme

Bu politikanın silme adımları ve kullanımdayken uygulanacak işlemler için Politika Yönetimi sayfasındaki Akıştan Politika Kaldırma bölümüne bakabilirsiniz.

Politikayı Dışa/İçe Aktarma

Bu politikanın dışa aktarma (Export) ve içe aktarma (Import) adımları için Export/Import sayfasına bakabilirsiniz.

Politikayı API'ye Bağlama

Bu politikanın API'lere nasıl bağlanacağına ilişkin süreç için Politika Yönetimi sayfasındaki Politikayı API'ye Bağlama bölümüne bakabilirsiniz.

İleri Düzey Özellikler

Özellik	Açıklama ve Adımlar
Dinamik Algoritma Bildirimi	- signatureAlgorithmVar için uygun header/body değişkenini belirleyin. - İmza tanımında değişkeni seçin. - Tüketici uygulamanın bu alanı okuyup doğrulama algoritmasını otomatik seçmesini sağlayın.
Revokasyon Takibi	- Sertifika seçimi sırasında revokasyon durumunu kontrol edin. - Revoked sertifika seçilirse kullanımdan kaçının. - Güncel sertifika ile politikayı yeniden deploy edin.
Çok Katmanlı İmza Zinciri	- Aynı mesaj için birden fazla imza tanımı ekleyin. - Tanımların sırasını veri bağımlılığına göre düzenleyin. - Hedef değişkenleri farklı header'lara veya body alanlarına yönlendirerek zincirli imza oluşturun.

Best Practices

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
Anahtar Yönetimi	Kötü: Expire olmuş sertifikayla imza atmak. İyi: Sertifika yenilendiğinde politikayı güncellemek. En İyi: Sertifika yenileme tarihlerini izleyip otomatik alarm kurmak.
Değişken Seçimi	Kötü: Aynı değişkeni hem kaynak hem hedef olarak kullanmak. İyi: Kaynak ve hedefi ayrı ayrı tanımlamak. En İyi: Tüketici beklentisine göre header/body ayrımı yapmak ve dökümante etmek.
Algoritma Kullanımı	Kötü: Varsayılan algoritmayı rastgele seçmek. İyi: Uygulama gereksinimine uygun algoritmayı belirlemek. En İyi: Güvenlik ekibi tarafından onaylanmış algoritma listesini kullanmak.
Çoklu Tanım Yönetimi	Kötü: Tüm alanları tek tanımda birleştirmek. İyi: Farklı alanlara özel tanımlar oluşturmak. En İyi: Tanımların açıklama alanlarını doldurup denetimlerde referans vermek.
Hata Mesajları	Kötü: Varsayılan hata mesajını kapatıp boş bırakmak. İyi: Genel bir hata mesajı sağlamak. En İyi: Operasyon ekiplerinin anlayacağı özelleştirilmiş mesaj ve hata kodu tanımlamak.

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Anahtar Depolama	Anahtarları sadece Secret Manager üzerinden yönetin; dışa aktarıp manuel dağıtmayın.
Sertifika Revokasyonu	Revoked sertifikalar kırmızı etiketle gösterilir, kesinlikle kullanılmamalıdır.
Erişim Kontrolü	Politika düzenleme yetkisini minimum kullanıcıya verin, IAM denetimlerini düzenli yapın.
Loglama	İmza başarısızlıklarını güvenlik loglarına yönlendirin, olağan dışı tekrar denemeleri analiz edin.
Algoritma Güvenliği	Zayıf algoritmaları (MD2, MD5) sadece geriye dönük uyumluluk zorunluluğu varsa kullanın, aksi halde modern seçenekleri tercih edin.

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Boş Kaynak Alanları	Neden kaçınılmalı: Boş içerik imza üretmez, hedef değişken de boş kalır. Alternatif: Kaynak değişkeni önceden doğrulayın veya Condition ile filtreleyin.
Tek Anahtar Bağımlılığı	Neden kaçınılmalı: Anahtar revokasyonunda tüm API'ler durur. Alternatif: Policy Group içinde yedek anahtar ile ikinci politika hazırlayın.
Test Edilmemiş Değişiklikler	Neden kaçınılmalı: Yanlış algoritma veya hedef değişken üretim ortamında hataya yol açar. Alternatif: Önce Geliştirme ortamında export/import ile test edin.
Hata Mesajı Gizleme	Neden kaçınılmalı: Operasyon ekipleri sorunu belirleyemez. Alternatif: Özel hata kodu ve açıklayıcı mesaj tanımlayın.

Performans İpuçları

Kriter	Öneri / Etki
İmza Tanımı Sayısı	Öneri: Gereksiz tanımları kaldırın. Etki: Her tanım ek CPU maliyeti getirir.
Algoritma Seçimi	Öneri: ECDSA gibi daha hafif algoritmaları değerlendirin. Etki: İşlem süresi azalır, throughput artar.
Anahtar Boyutu	Öneri: Güvenlik politikalarına uygun minimum anahtar uzunluğunu kullanın. Etki: Gereğinden uzun anahtarlar gecikmeyi artırır.
Koşul Kullanımı	Öneri: Politikanın sadece gerekli isteklerde çalışması için Condition tanımlayın. Etki: Trafik azaltılır, CPU yükü düşer.
Sıralama Yönetimi	Öneri: Politikayı akışta olabilecek en geç aşamada çalıştırın. Etki: Önceki politikaların başarısız olması durumunda boşa imza üretimi yapılmaz.

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Politika kaç farklı imza tanımı destekler?	Pratikte sınırlama yoktur; her tanım ayrı satır olarak eklenebilir, ancak performans etkisini göz önünde bulundurun.
Genel	Sertifika ve Crypto Key arasında nasıl seçim yapmalıyım?	Sertifika özel anahtar içeriyorsa kullanabilirsiniz; aksi halde Crypto Key seçerek HSM veya anahtar kasasındaki kayıtları tercih edin.
Teknik	İmza algoritmasını isteğe bağlı nasıl paylaşırım?	İmza tanımında signatureAlgorithmVar seçin; politika çalıştığında algoritma adı bu değişkene yazılır.
Teknik	Mesaj gövdesi JSON değilse politika çalışır mı?	Evet, değişken ile işaret edilen veri düz metin olduğu sürece imzalanır; veri formatı politikadan bağımsızdır.
Kullanım	Global politikayı local kopyaya dönüştürmek zorunda mıyım?	Hayır, ancak localize ederek API bazlı özelleştirme yapabilirsiniz; globalde yapılan değişiklikler otomatik yayılır.
Kullanım	Hata durumunda hangi logları incelemeliyim?	Policy loglarında POLICY_DIGITALSIGN hata kodunu ve özelleştirilmiş mesajı arayın; ayrıca Gateway genel loglarını kontrol edin.