Şifreleme

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?

• Ş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

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. Şifreleme Tanımlarının Yürütülmesi: Her policyEncryptionDef girdisi 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.
4. 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.
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 Ş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 Info varlıklarından, sertifikalar ise Certificate yö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: 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: Ş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 5: 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 6: Ş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 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 şifreleme 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	- 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.