Genel Bakış
Amacı Nedir?
- Şifreleme politikası, hassas veriyi API Proxy (API Vekil Sunucusu) akışında standart algoritmalarla şifreleyerek verinin iletim ve saklama güvenliğini artırır.
- Kaynak değişkenlerdeki veriyi hedef değişkenlere şifrelenmiş biçimde yazıp maskelenmemiş veri erişimini engeller.
- Gizli anahtar ve sertifika yönetimini merkezi hale getirerek tutarlı güvenlik konfigürasyonu sağlar.
- Koşul bazlı etkinleşme sayesinde yalnızca belirlenen endpoint veya header kriterleri sağlandığında şifreleme uygulanı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ü: Şifreleme 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ı?
- Şifreleme Tanımlarının Yürütülmesi: Her
policyEncryptionDefgirdisi için kaynak değişken okunur, seçilen algoritma ve anahtar/sertifika ile şifreleme uygulanır, sonuç hedef değişkende saklanır, gerekiyorsa IV ve algoritma bilgisi ilgili değişkenlere yazılır. - Karar Verme:
- Eşleşme Var: Tüm tanımlar başarıyla işlenir, akış bir sonraki politikaya veya endpoint’e yönlendirilir.
- Eşleşme Yok: Koşul sağlanmadığında politika atlanır, veri üzerinde değişiklik yapılmaz.
- 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 Şifreleme Adımı Yönetimi: Tek politikada birden fazla şifreleme tanımı oluşturularak farklı veri alanları için ayrı algoritma ve hedef değişkenler tanımlanır.
- Algoritma Esnekliği: AES, DES, Triple DES ve RSA gibi farklı mod ve padding seçenekleri desteklenir; çalışma zamanında algoritma değişkeni ile dinamik seçim yapılabilir.
- Anahtar/Sertifika Entegrasyonu: Gizli anahtarlar
Crypto Key Infovarlıklarından, sertifikalar iseCertificateyönetiminden seçilerek merkezi gizli yönetim sistemine entegre edilir. - 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
- IV Yönetimi: IV gerektiren algoritmalarda IV üretimi veya harici değişkenden alınması, IV formatının BASE64 ya da HEX olarak belirlenmesi sağlanır.
- Değişken Güncelleme Diyalogları: Kaynak, hedef, algoritma ve IV değişkenleri için ayrı dinamik seçim pencereleri ile doğru değişkenlerin seçimi kolaylaştırılır.
- Yerelleştirme ve Global Mod: Global politikalar local kopyaya dönüştürülebilir; local politika global depoya eklenerek merkezi yönetim altına alınabilir.
- 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ç |
|---|---|---|---|
| Müşteri Verisi Şifreleme | Müşteri TCKN alanı düz metin olarak geliyor | sourceVar=request.body.customerId, targetVar=request.body.customerIdEnc, AES_CBC_PKCS5Padding, BASE64 çıktı. | Düz metin gizlenir, şifreli değer API’ye yönlendirilir. |
| RSA ile Token Saklama | JWT üretiminde private anahtar kullanılmalı | RSA_ECB_PKCS1Padding, enumKeyCertificateType=KEY, cryptoKeyInfoId seçili. | Anahtar yönetimi güvenli, token oluşurken doğru algoritma kullanılır. |
| Sertifika Tabanlı Şifreleme | Partner sistem sertifika dayatıyor | RSA_ECB_OAEPWithSHA_256AndMGF1Padding, enumKeyCertificateType=CERTIFICATE, sertifika seçimi. | İstek partner sertifikası ile şifrelenir, karşı taraf çözebilir. |
| Dinamik Algoritma Seçimi | Algoritma türü header’a göre değişiyor | cipherAlgorithmVar seçili, header’dan algoritma adı okunur. | runtime’da algoritma değiştirilir, esnek politika uygulanır. |
| IV Üretimi Gerektiren Akış | NoPadding modunda IV bekleniyor | createIV=true, ivVar=response.headers.iv, HEX format. | Politika IV üretip çıktı değişkenine yazar, hedef sistem okuyabilir. |
| Local Politika Testi | Tek API üzerinde deneme yapılacak | Global politikayı Localize ile kopyala, local modda düzenle. | Canlıyı etkilemeden test ortamında şifreleme senaryosu denenir. |
| (Opsiyonel) SOAP Zarfları | SOAP envelope içeriği şifrelenmeli | sourceVar=request.body.soapPayload, Triple DES algoritması, BASE64. | SOAP gövdesi şifrelenir, hedef servis çözene kadar gizli kalır. |
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 Şifreleme 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 → Encryption 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_Encryption- 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: “Müşteri hassas verilerini AES ile şifreler” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Şifreleme Tanımlarını Oluşturma | - Add butonu ile policyEncryptionDef ekleyin.- Kaynak ( sourceVar) ve hedef (targetVar) değişkenleri seçin.- Algoritma ( cipherAlgorithm) ve çıktı formatını (outputEncodingType) belirleyin.- Algoritma değişkeni gerekiyorsa ( cipherAlgorithmVar) tanımlayın. |
| Adım 4: Anahtar/Sertifika ve IV Yapılandırması (Varsa) | - RSA algoritmalarında KEY veya CERTIFICATE seçin, ilgili cryptoKeyInfoId veya certificateId değerini belirleyin.- CBC modunda IV gerekiyorsa createIV, ivEncodingType ve ivVar alanlarını doldurun. |
| Adım 5: Şifreleme Tanımı Yönetimi (Varsa) | - Her tanım için açıklama girerek bakım kolaylığı sağlayın. - Tanımı düzenlemek için satırdaki kalem ikonunu, kaldırmak için çöp kutusunu kullanın. - Sıra, şifreleme işlemlerinin yürütülme sırasını belirler. |
| 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": 403, "message": "[Default hata mesajı]" }Özel: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Özel mesaj]" } |
| Adım 8: Kaydetme | - Sağ üstteki [Save] butonuna tıklayın. Kontrol Listesi: Benzersiz isim. Zorunlu alanlar dolu. En az bir şifreleme 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 |
|---|---|
| Runtime Algoritma Seçimi | - cipherAlgorithmVar için değişken seçin.- İstek sırasında header/body üzerinden algoritma adı sağlayın. - Desteklenen sabit değerlerden biri olduğundan emin olun, aksi halde varsayılan algoritma uygulanmaz. |
| IV Enjeksiyonu Yönetimi | - createIV alanını aktif edin veya mevcut ivVar değişkenini seçin.- IV kodlamasını BASE64 ya da HEX olarak belirleyin. - Hedef sistemin IV formatıyla uyumlu olduğundan emin olun. |
| Sertifika Döngüsü Kontrolü | - RSA modunda enumKeyCertificateType=CERTIFICATE seçin.- Geçerli (revoked olmayan) sertifikayı listeden seçin. - Sertifika yenilendiğinde politikayı güncelleyip tekrar deploy edin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Değişken Yönetimi | Kötü: Aynı değişkeni hem kaynak hem hedef yapma. İyi: Kaynak ve hedefi ayrı değişkenlerde tutma. En İyi: Hedef değişkeni yalnızca şifrelenmiş değer için kullan, düz veriyi politikadan sonra temizle. |
| Algoritma Seçimi | Kötü: Desteklenmeyen algoritma adlarını runtime ile gönderme. İyi: Sabit algoritma seçip test etme. En İyi: Desteklenen algoritmaları merkezi şablonda tut, gereksiz varyasyonlardan kaçın. |
| Anahtar/Sertifika Döngüsü | Kötü: Süresi dolan sertifikayı politikada tutma. İyi: Sertifika yenilendiğinde politikayı güncelleme. En İyi: Sertifika yenileme planı çıkar, güncelleme sonrası hızlı deploy yap. |
| Hata Mesajı Yönetimi | Kötü: Varsayılan mesajı bırakıp kullanıcıya teknik detay vermek. İyi: Genel hata mesajı tanımlamak. En İyi: Hata kodu ve izleme ID içeren özelleştirilmiş JSON mesajı döndürmek. |
| Test Süreci | Kötü: Doğrudan canlıda deneme yapmak. İyi: Test ortamında manuel senaryo yürütmek. En İyi: Otomatik testler ile şifreleme/çözme uyumluluğunu doğrulayarak Canlı Ortam öncesi onay almak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Anahtar Saklama | Gizli anahtarları yalnızca Crypto Key Info üzerinden yönetin, düz metinle konfigürasyona yazmayın. |
| Sertifika Geçerliliği | Revoked sertifikalar listede işaretlidir, üretimde kullanmayın ve güncel sertifika yükleyin. |
| IV Kullanımı | NoPadding modlarında IV olmadan şifreleme yapmayın, IV üretimini zorunlu tutun. |
| Algoritma Sıkılığı | Zayıf algoritmaları (DES) sadece geriye dönük uyumluluk için kullanın, mümkünse AES veya RSA OAEP tercih edin. |
| Koşul Kontrolü | Politika koşullarını daraltarak yalnızca gerekli endpoint’lerde çalıştırın, gereksiz şifreleme CPU yükü yaratır. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Yanlış Değişken Ataması | Neden kaçınılmalı: Kaynak veriyi kaybedip şifreli değeri aynı alana yazabilirsiniz. Alternatif: Ayrı hedef değişken kullanın ve orijinali gerektiğinde log’lamayın. |
| Revoked Sertifika Kullanımı | Neden kaçınılmalı: Şifreleme başarısız olur veya partner sistem reddeder. Alternatif: Güncel sertifika seçin, revoke edilenleri temizleyin. |
| Test Edilmemiş Algoritma Değişiklikleri | Neden kaçınılmalı: Üretimde çözümleme hataları oluşur. Alternatif: Geliştirme ortamında çift yönlü test yapın. |
| IV’siz CBC Kullanımı | Neden kaçınılmalı: Şifreleme deterministik hale gelir, güvenlik zayıflar. Alternatif: createIV veya ivVar ile IV yönetin. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Tanım Sayısı | Öneri: Aynı politikada gereksiz çok sayıda şifreleme tanımı oluşturmaktan kaçının. Etki: Daha düşük CPU kullanımı ve daha hızlı gateway yanıtı. |
| Algoritma Seçimi | Öneri: AES_GCM modları desteklenmediği için AES_CBC kullanırken payload boyutunu optimize edin. Etki: Şifreleme süresi kısalır. |
| Anahtar Yönetimi | Öneri: Crypto Key Info nesnelerini cache’leyin, her istekte yeniden oluşturmaktan kaçının. Etki: Gizli yönetimi I/O yükü azalır. |
| Koşul Filtreleri | Öneri: Query Builder ile dar koşullar tanımlayın. Etki: Politikanın gereksiz tetiklenmesi engellenir. |
| IV Hesaplama | Öneri: createIV=true ise IV’nin hedef değişkende tekrar kullanılmadığından emin olun.Etki: Bellek ve işlem maliyeti minimumda tutulur. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Şifreleme politikası hangi veri tipleri üzerinde çalışır? | JSON, XML veya form-data gibi yapılandırılmış payload’lardan seçilen değişkenler üzerinde çalışır; değişken tanımıyla uyumlu her içerik şifrelenebilir. |
| Genel | Politikayı pasif yaptığımda tanımlarım silinir mi? | Hayır, pasif durumda konfigürasyon saklanır ve tekrar aktive ettiğinizde aynı şekilde uygulanır. |
| Teknik | RSA algoritması için key mi sertifika mı seçmeliyim? | Servis sağlayıcı public key ile şifreleme bekliyorsa sertifika seçin; kendi private key’iniz varsa Crypto Key Info kullanın. |
| Teknik | IV değişkeni zorunlu mu? | CBC ve createIV=true durumunda IV değişkeni zorunludur; aksi halde politika doğrulaması başarısız olur. |
| Kullanım | Aynı politikayı birden fazla API Proxy (API Vekil Sunucusu) üzerinde kullanabilir miyim? | Global modda evet, deploy sonrası bütün bağlı API Proxy (API Vekil Sunucusu) örneklerinde aynı konfigürasyon çalışır. |
| Kullanım | Politikayı local’e çevirirsem global sürümü etkiler mi? | Hayır, Localize işlemi global politikanın kopyasını oluşturur, orijinal politika değişmeden kalır. |