Dijital İmza Doğrulama

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?

• API Proxy (API Vekil Sunucusu) üzerinden geçen isteğin içeriğinin değiştirilmediğini garanti altına almak için dijital imzayı doğrular.
• İsteğin gerçekten yetkili istemciden geldiğini kanıtlamak için imza üretiminde kullanılan anahtar veya sertifikayı kontrol eder.
• Çoklu imza tanımı sayesinde farklı endpoint veya payload türleri için ayrı doğrulama kuralları uygulamaya imkan tanır.
• İmza doğrulama algoritmasını dinamik olarak belirleyerek farklı imza formatlarıyla uyumluluk sağlar.

Ç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 Doğrulama 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 Doğrulama Kontrolü: Tanımlı her doğrulama girdisi için istekteki imza değişkeni alınır, seçilen algoritma (belirtilmiş veya değişkenden okunan) ile kaynak veri çözümlenir ve seçilen anahtar/sertifika ile imza doğrulanır. Girdi BASE64 veya HEX kodlamasına göre çözülür.
4. Karar Verme:
   • Eşleşme Var: Tüm tanımlar için imza doğrulanır, istek işleme akışına devam eder.
   • Eşleşme Yok: Herhangi bir tanım başarısız olursa istek durdurulur, yapılandırılan hata mesajı döndürülür.
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ı Yönetimi: Farklı payload veya endpoint kombinasyonları için birden fazla dijital imza doğrulama girdisi tanımlanabilir; her girdi bağımsız parametrelerle çalışır.
• Dinamik Algoritma Seçimi: İmza algoritması sabit değer olarak belirlenebilir veya istekteki değişkenlerden otomatik alınarak farklı imzalama stratejilerine uyum sağlanır.
• Gizli Anahtar ve Sertifika Entegrasyonu: Secret Manager'dan Crypto Key veya sertifika seçilerek merkezi anahtar yönetimiyle uyumlu güvenlik sağlar.
• 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

• Değişken Bazlı İmza Çözümleme: İmza ve kaynak veri, global değişken deposundan seçilerek runtime sırasında parametrik doğrulama yapılmasını sağlar.
• Algoritma Keşfi: FIND modu, imza algoritmasını istek içeriğinden okuyarak aynı politika ile çok sayıda istemciyi destekler.
• Revoked Sertifika Uyarısı: Liste ekranında iptal edilmiş sertifikalar kırmızı renkle belirtilir, geçersiz sertifikaların tekrar kullanılmasını engeller.
• Export/Import Özelliği: Politika yapılandırmasını ZIP dosyası olarak export etme. Farklı ortamlara (Development, Test, Production) 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 JSON İsteği İmza Doğrulama	Mobil uygulama istekleri JSON gövdesi ve Base64 imza taşıyor	sourceVar=body.json, signatureVar=header.X-Signature, inputEncodingType=BASE64, signatureAlgorithm=SHA256withRSA, Crypto Key seçili	İstek yalnızca imza eşleşirse devam eder, aksi halde 403 döner
XML Doküman İmzalama Kontrolü	BPM sistemi SOAP/XML ile imzalı içerik gönderiyor	sourceVar=body.xml, signatureVar=body.signature, inputEncodingType=HEXADECIMAL, signatureAlgorithm=SHA1withDSA, Sertifika seçili	XML dokümanı değiştirilirse politika isteği reddeder
Algoritmayı Header'dan Alma	Birden fazla algoritma kullanan müşteriler aynı endpoint'i çağırıyor	sourceOfAlgorithm=FIND, signatureAlgorithmVar=header.X-Signature-Alg, signatureVar=header.X-Signature, sourceVar=body.raw	Header'da bildirilen algoritma ile imza doğrulanır, eksik/yanlışsa hata üretilir
Revoked Sertifika Denetimi	İptal edilmiş sertifika ile imzalanan isteği engelleme	Sertifika listesinde revoked olarak işaretli kaydı seçmeden önce uyarı notu eklenir, güncel sertifika zorunlu kılınır	İptal edilmiş sertifika ile gelen istekler 403 Forbidden döner
Çoklu Bölüm İmzalama	Aynı istekte hem payload hem metadata imzalanıyor	İki ayrı doğrulama tanımı oluşturulur; her biri farklı sourceVar ve signatureVar kullanır	Her iki imza da doğrulanırsa istek geçer, biri hatalıysa engellenir
Harici Anahtar Rotasyonu	Anahtar rotasyon sürecinde eski ve yeni anahtarlar aynı anda kullanılacak	İki tanım eklenir; biri eski Crypto Key, diğeri yeni Crypto Key ile	Geçiş sürecinde her iki anahtar da kabul edilir, rotasyon sonrası eski tanım silinir
Performans İzleme (opsiyonel)	Yoğun trafik altında doğrulama süresi ölçülmek isteniyor	Condition ile belirli Header değerlerine sahip isteklerde politika aktif, Logging ile süre tutulur	Kritik işlemlerde doğrulama sürer, gereksiz isteklere uygulanmaz

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 Doğrulama 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 Doğrulama Politikası 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_DigitalSignVerify - 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: "Mobil imzalı JSON isteği doğrulaması" - 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: Dijital İmza Tanımlarını Oluşturma	[+ Add Verification] ile modal açın. - Signature Var: İmzanın bulunduğu değişkeni seçin. - Source Var: İmzanın üretildiği ham veriyi temsil eden değişkeni seçin. - Input Encoding Type: İmzanın BASE64 veya HEX olduğunu belirtin. - Açıklama girerek tanımı gruplayın.
Adım 5: Algoritma ve Anahtar Yapılandırması	Modal içinde Source of Algorithm alanını belirleyin. - SPECIFY seçilirse algoritmayı listeden seçin. - FIND seçilirse Signature Algorithm Var ile algoritmayı istekteki değişkenden okuyun. - Key or Certificate bölümünde Crypto Key veya Sertifika modunu seçin; gerekirse yeni anahtar/sertifika oluşturma diyaloglarını kullanın.
Adım 6: Çoklu Tanım ve Öncelik Yönetimi	- Birden fazla imza tanımı ekleyin. - Tanımlar listedeki sırayla değerlendirilir. - Her tanım için düzenleme/silme işlemleri aynı modal üzerinden yapılır. - Öneri: Farklı endpoint'ler için anlamlı açıklamalar kullanı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": 403, "message": "[Default hata mesajı]" } Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" }
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
Runtime Algoritma Seçimi	- Source of Algorithm alanını FIND olarak ayarlayın. - Algoritma değerini taşıyan değişkeni Signature Algorithm Var olarak seçin. - Değişkenin istekte zorunlu olarak gönderildiğinden emin olun ve eksik durumda hata mesajı tanımlayın.
Anahtar/Sertifika Rotasyonu	- Yeni ve eski anahtarlar için iki ayrı imza tanımı oluşturun. - Condition sekmesinde tarih veya header bazlı kural tanımlayarak geçiş sürecini yönetin. - Rotasyon tamamlandığında eski tanımı silerek politika listesini sadeleştirin.
Çoklu Payload Doğrulama	- Her payload bölümü için ayrı sourceVar ve signatureVar seçin. - Tanımları anlamlı açıklamalarla belgeleyin. - Tanımların sırasını kontrol ederek kritik kontrolleri üstte konumlandırın.

Best Practices

Yapılması Gerekenler ve En İyi Uygulamalar

Kategori	Açıklama / Öneriler
İsimlendirme Stratejisi	Kötü: policy1 İyi: DigitalSignVerify_Prod En İyi: DSV-Prod-CustomerPayload
Değişken Kullanımı	Kötü: Hard-coded header isimleri İyi: Önceden tanımlı değişkenleri kullanmak En İyi: Dinamik değişkenleri Query Builder koşullarıyla doğrulamak
Algoritma Yönetimi	Kötü: Tüm istemcilerde aynı algoritmayı varsaymak İyi: Ana kullanılan algoritmayı SPECIFY ile tanımlamak En İyi: FIND modu ile istemci bazlı algoritmaları desteklemek
Anahtar/Sertifika Güncelleme	Kötü: Sertifikayı manuel değiştirmek İyi: Yeni sertifikayı tanımlayıp eskisini silmek En İyi: Rotasyon sürecinde iki tanımı paralel çalıştırıp geçişten sonra temizlik yapmak
Hata Mesajı Yönetimi	Kötü: Varsayılan mesajı olduğu gibi bırakmak İyi: Hata kodunu belirtmek En İyi: İzlenebilirlik için errorCode ve hedef log referansını eklemek

Güvenlik En İyi Uygulamaları

Güvenlik Alanı	Açıklama / Uyarılar
Anahtar Gizliliği	Crypto Key referanslarını sadece yetkili projelerle paylaşın; gereksiz erişimleri engelleyin.
Sertifika Geçerliliği	Revoked sertifikaları tekrar kullanmayın; liste ekranındaki kırmızı uyarılara dikkat edin.
Hata Mesajı İçeriği	Saldırganlara bilgi vermemek için hata mesajında algoritma veya anahtar detaylarını paylaşmayın.
Kayıt ve İzleme	Başarısız doğrulama denemelerini SIEM sistemine yönlendirerek olası saldırıları erken tespit edin.
Koşullu Aktifleştirme	Kritik endpoint'ler için ek Condition kriterleri tanımlayarak gereksiz doğrulama yükünü azaltın, istek yüzeyini sınırlayın.

Kaçınılması Gerekenler

Kategori	Açıklama / Uyarılar
Eksik İmza Tanımı	Neden kaçınılmalı: Tanım olmadan politika devreye girmez. Alternatif: En az bir tanımı zorunlu alanları doldurarak ekleyin.
Yanlış Encoding Seçimi	Neden kaçınılmalı: Base64/HEX uyumsuzluğu doğrulamayı bozar. Alternatif: İmza sağlayıcısından alınan bilgiye göre encoding seçin.
Revoked Sertifika Kullanımı	Neden kaçınılmalı: Güvenlik riski oluşturur ve doğrulama başarısız olur. Alternatif: Geçerli sertifikayı Secret Manager'dan seçin.
Koşulsuz Global Etki	Neden kaçınılmalı: Tüm trafiği gereksiz doğrulamaya zorlayarak performansı düşürür. Alternatif: Condition ile sadece kritik endpoint veya istemcileri hedefleyin.

Performans İpuçları

Kriter	Öneri / Etki
Tanım Sayısı	Öneri: Benzer imza gereksinimlerini tek tanımda birleştirin. Etki: Her istekte yapılan doğrulama sayısı azalır.
Algoritma Kaynağı	Öneri: Sabit algoritma kullanabiliyorsanız SPECIFY seçin. Etki: FIND modundaki ek değişken çözümlemesini ortadan kaldırır.
Condition Kullanımı	Öneri: Sadece imzalanmış isteklerin geleceği endpoint'leri koşul ile hedefleyin. Etki: Gereksiz doğrulama maliyetini düşürür.
Anahtar Yönetimi	Öneri: Aynı anahtarı birden fazla tanımda tekrar etmeyin, ortak senaryoları gruplayın. Etki: Bellek kullanımını ve lookup süresini azaltır.
İzleme	Öneri: Başarısız doğrulama sayısını metrik olarak toplayın. Etki: Performans anomalilerini ve saldırı girişimlerini erken tespit edersiniz.

Sık Sorulan Sorular (SSS)

Kategori	Soru	Cevap
Genel	Farklı endpoint'lerde farklı imza kuralları uygulayabilir miyim?	Evet, her endpoint için ayrı Condition tanımlayıp uygun imza tanımlarını ekleyebilirsiniz.
Genel	Politika pasif olduğunda kayıtlı tanımlar silinir mi?	Hayır, pasif moda alınca yapılandırma korunur ve yeniden etkinleştirildiğinde aynı ayarlarla çalışır.
Teknik	İmza algoritmasını runtime'da belirleyemezsem ne olur?	FIND seçili ancak değişken boşsa doğrulama başarısız olur ve özelleştirilmiş hata mesajı döner; SPECIFY moduna geçebilirsiniz.
Teknik	Sertifika yenilendiğinde politikayı nasıl güncellerim?	Yeni sertifikayı Secret Manager'a ekleyip tanımda sertifika referansını güncelleyin veya paralel tanım ekleyerek kesintisiz geçiş yapın.
Kullanım	Aynı politika hem global hem local kullanılabilir mi?	Global politikayı localize ederek kopyalayabilirsiniz; local kopya sadece seçili API'de görünür.
Kullanım	İmza başarılı olsa bile özel HTTP kodu döndürebilir miyim?	Evet, Error Message Customization sekmesinde varsayılan yanıtı değiştirerek farklı statusCode veya payload tanımlayabilirsiniz.