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
- İstek Gelişi: API Gateway’e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
- 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ı?
- 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.
- 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.
- 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ı:
signatureAlgorithmVarkullanı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: İ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 4: 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 5: Ç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 6: 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 7: 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 8: 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. |
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. |