Genel Bakış
Amacı Nedir?
- API Proxy (API Vekil Sunucusu) üzerinde şifreli payload segmentlerinin çözülmesini otomatikleştirerek arka uç servislerin şifreleme detaylarından bağımsız kalmasını sağlar.
- Mesajın hangi bölümünün çözüleceğini ve sonucun nereye yazılacağını değişkenlerle kontrol ederek karmaşık entegrasyon senaryolarında esneklik sunar.
- Secret Manager üzerinden Crypto Key Info veya sertifika nesneleriyle merkezi anahtar yönetimini güçlendirir ve güvenlik standartlarına uyumu kolaylaştırır.
- Algoritma adını istek içeriğinden okunabilir kılarak farklı istemcilerden gelen dinamik şifreleme senaryolarını destekler.
Ç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ü: Şifre Açma 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ı?
- Şifre Açma Tanımları: Politika, kayıtlı her şifre açma tanımını sırasıyla ele alır; hedef değişkenden şifreli içeriği okur, gerekirse IV bilgisini toplar, algoritmayı sabit tanımdan veya mesajdaki değişkenden belirler ve Secret Manager’dan ilgili anahtar/sertifikayı çeker.
- Karar Verme:
- Eşleşme Var: Tanım gereksinimleri karşılanırsa içerik çözülür, sonuç belirlenen değişkene yazılır ve akış bir sonraki Policy aşamasına devam eder.
- Eşleşme Yok: Tanıma uymayan veya eksik parametre barındıran içerik için şifre açma atlanır ya da özelleştirilmiş hata mesajı tetiklenir.
- 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 Şifre Açma Tanımı: Aynı politika altında farklı mesaj segmentleri için ayrı algoritma ve anahtar kombinasyonları tanımlanabilir.
- Algoritma Esnekliği: AES, DES, DESede ve RSA varyasyonları dahil olmak üzere yaygın decryption algoritmalarını destekler.
- Secret Manager Entegrasyonu: Crypto Key Info kayıtları veya sertifikalar üzerinden güvenli anahtar erişimi 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
- Dinamik Algoritma Çözümleme: Algoritma adını istekteki değişkenden okuyarak istemci bazlı şifreleme farklılıklarına uyum sağlar.
- IV Yönetim Otomasyonu: Algoritmaya göre IV zorunluluğunu otomatik belirler ve IV değişkeni/encoding’ini doğrular.
- Değişken Güncelleme Diyalogları: Kaynak, hedef, IV ve algoritma değişkenleri için hızlı düzenleme pencereleri sunar.
- 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ç |
|---|---|---|---|
| Ödeme Yanıtı Şifre Çözme | 3DES ile şifrelenmiş kart verisi SOAP yanıtında Base64 olarak dönüyor. | Target var olarak yanıt gövdesindeki CardData, source var olarak maskeleme değişkeni seçilir; algoritma DESede_CBC_PKCS5Padding, Crypto Key Info referansı tanımlanır. | Kart verisi çözülerek backend servise maskelenmiş alanla birlikte iletilir. |
| Dinamik Algoritma İçeren İstek | İstemci header içinde kullanılacak algoritma ismini gönderiyor. | sourceOfAlgorithm = FIND, cipherAlgorithmVar header değişkeni olarak ayarlanır, anahtar sertifikadan okunur. | Algoritma header’dan okunur, doğru anahtar seçilir ve içerik başarıyla çözülür. |
| JWT Payload Şifre Açma | JWT içindeki özel claim Hex formatında AES ile şifrelenmiş. | inputEncodingType = HEXADECIMAL, algoritma AES_CBC_PKCS5Padding, IV varlığı işaretlenip IV değişkeni tanımlanır. | Claim çözümlenip API Gateway üzerinden doğrulama adımına iletilir. |
| Microservice Arası Sır Paylaşım | Mikroservisler arası mesajda IV bilgisi gövdede ayrı alanda geliyor. | IV değişkeni mesaj alt alanına bağlanır, ivEncodingType = BASE64, anahtar Crypto Key Info’daki paylaşımlı key’den alınır. | Mesaj arayüzü IV + payload ile çözülür, loglama düz metinle yapılmaz. |
| Revoked Sertifika Uyarısı | Kullanılan sertifika revoke edilmiş ama politika hala çalışmalı. | Sertifika seçilir, revoked listesi takip edilir, hata mesajı ile kullanıcı bilgilendirilir. | Politika çalışmaya devam eder, loglarda sertifika uyarısı yer alır. |
| Local Policy ile Test | Geliştirme ortamında API özelinde farklı anahtar kullanmak gerekiyor. | Global politikadan Localize edilip anahtar değiştirilen local policy bağlanır. | API sadece local policy ile çalışır, diğer API’ler global yapılandırmadan etkilenmez. |
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.Yeni Şifre Açma 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 → Decryption 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_Decryption- 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: “Ödeme servisleri için kart verisi çözümü” - Maks. 1000 karakter. - Politikanın amacını açıklayın. |
| Adım 3: Şifre Açma Tanımlarını Yönetme | - Decryption Definitions bölümünde [+ Add] butonuna tıklayarak yeni tanım ekleyin. - Her tanım için kısa açıklama, mesaj bölümü (source variable), şifresi açılmış içeriğin yeri (target variable) belirleyin. - Birden fazla tanım ekleyerek farklı mesaj segmentlerini ayrı ayrı çözebilirsiniz. |
| Adım 4: Algoritma ve Anahtar Kaynağını Belirleme | Source of Algorithm alanında SPECIFY seçerseniz algoritmayı listeden belirleyin ve Crypto Key Info ya da sertifikayı seçin. FIND seçimi ile algoritma adını mesajdaki cipherAlgorithmVar değişkeninden okutabilirsiniz.! Anahtar veya sertifika seçimi olmadan kayıt yapılamaz. |
| Adım 5: IV ve Kodlama Ayarlarını Yapma | Algoritma IV gerektiriyorsa ivExists otomatik işaretlenir; IV değişkenini ve ivEncodingType değerini seçin. Şifreli içerik formatını inputEncodingType (BASE64/HEXADECIMAL) ile belirleyin.! Yanlış encoding seçimi çözülemeyen veri doğurur. |
| 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 şifre açma 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 Kullanım Adımları |
|---|---|
| Dinamik Algoritma Kaynağı Yönetimi | - sourceOfAlgorithm alanını FIND olarak ayarlayın.- İstekten okunacak değişkeni cipherAlgorithmVar ile eşleyin.- Desteklenen algoritma isimlerinin istemciyle mutabık olduğundan emin olun. |
| Sertifika Revocation İzleme | - Sertifika seçim listesindeki kırmızı işaretli (revoked) kayıtları kontrol edin. - Revoked sertifika ile çalışıyorsanız hata mesajında kullanıcıyı bilgilendirin. - Gerekirse yeni sertifikayı oluşturup politikayı güncelleyin. |
| IV Yönetimini Otomatikleştirme | - Algoritma seçimi sonrası ivExists otomatik işaretlenirse IV değişkenini belirleyin.- ivEncodingType için mesajdaki formatla uyumlu kodlamayı seçin.- IV üretmeyen algoritmalar için ivVar alanını temizleyerek gereksiz iş yükünü önleyin. |
Best Practices
Yapılması Gerekenler ve En İyi Uygulamalar
| Kategori | Açıklama / Öneriler |
|---|---|
| Algoritma Seçimi | Kötü: Varsayılan algoritmayı her tanımda kullanmak. İyi: İhtiyaç duyulan algoritmayı elle seçmek. En İyi: Algoritma adlarını mesajdan okuyarak istemci bazlı esneklik sağlamak. |
| Anahtar Yönetimi | Kötü: Anahtarları manuel dosya olarak saklamak. İyi: Crypto Key Info kayıtlarını kullanmak. En İyi: Anahtar rotasyonunu Secret Manager otomasyonu ile yapmak. |
| IV Kullanımı | Kötü: IV gerekmeyen algoritmalar için IV alanı bırakmak. İyi: IV gerektiren algoritmalarda sabit IV kullanmak. En İyi: IV’yi mesajdan dinamik olarak okuyup uygun encoding ile eşlemek. |
| Değişken Yönetimi | Kötü: Mesaj alanlarını hardcode etmek. İyi: Variable dialog ile mevcut değişkenleri seçmek. En İyi: Katmanlı değişken isimlendirmesi ve açıklamalarla bakım maliyetini azaltmak. |
| Hata Mesajları | Kötü: Varsayılan 500 hatasını döndürmek. İyi: Şifre açma başarısızlıklarında anlamlı mesaj eklemek. En İyi: Duruma özel hata kodu ve yönlendirme bilgisi içeren mesajlar tasarlamak. |
Güvenlik En İyi Uygulamaları
| Güvenlik Alanı | Açıklama / Uyarılar |
|---|---|
| Anahtar Rotasyonu | Anahtarların SLA’ya göre periyodik rotasyonunu planlayın, rotasyon sonrası politikaları güncelleyin. |
| Sertifika Geçerliliği | Sertifika son kullanma ve revoke durumlarını kontrol edin, revoked sertifikalar için acil aksiyon planı oluşturun. |
| Erişim Logları | Decryption sonuçlarına erişen servisler için erişim loglarını merkezi SIEM’de toplayın. |
| Koşul Yönetimi | Politika koşullarını minimizasyon ilkesine göre tanımlayın; gereksiz geniş kapsamlı koşullardan kaçının. |
| Hata İçeriği | Hata mesajlarında hassas anahtar veya algoritma detaylarını paylaşmayın; genel ifadeler kullanın. |
Kaçınılması Gerekenler
| Kategori | Açıklama / Uyarılar |
|---|---|
| Yanlış Encoding Seçimi | Neden kaçınılmalı: Kodlama uyumsuzluğu decryption başarısızlığına yol açar. Alternatif: Mesaj formatını doğrulayıp doğru inputEncodingType seçin. |
| Paylaşımlı Sabit IV | Neden kaçınılmalı: Güvenlik zafiyeti oluşturur. Alternatif: IV’yi mesajdan alın veya her istek için dinamik üretin. |
| Revoked Sertifika Kullanımı | Neden kaçınılmalı: Güvenlik ihlali riskini artırır. Alternatif: Aktif sertifikaları kullanın, revoke edilenleri hızla değiştirin. |
| Koşulsuz Global Etki | Neden kaçınılmalı: Tüm API Proxy’lerde beklenmedik davranışlara sebep olur. Alternatif: Koşulları daraltın veya local policy oluşturun. |
Performans İpuçları
| Kriter | Öneri / Etki |
|---|---|
| Tanım Sayısı | Öneri: Gereksiz tanımları temizleyin. Etki: Şifre açma döngüsündeki işlem süresi kısalır. |
| Algoritma Seçimi | Öneri: Gereksiz yere ağır algoritmalar (RSA) yerine simetrik seçenekleri tercih edin. Etki: CPU yükü azalır, gecikme düşer. |
| IV Kaynağı | Öneri: IV’yi mesajdan okumak yerine gereksiz sorguları engelleyin. Etki: IO maliyetleri düşer. |
| Secret Manager Çağrıları | Öneri: Aynı anahtarı kullanan tanımları gruplayın. Etki: Anahtar getirme çağrıları azalır. |
| Hata Loglaması | Öneri: Başarılı çalışmalarda debug log seviyesini kapatın. Etki: Log hacmi ve disk kullanımı düşer. |
Sık Sorulan Sorular (SSS)
| Kategori | Soru | Cevap |
|---|---|---|
| Genel | Şifre Açma Politikası tek bir API’de mi kullanılabilir? | Hem global hem local olarak tanımlanabilir; global politikayı birden çok API Proxy ile paylaşabilir, local kopyalarla özelleştirebilirsiniz. |
| Genel | Aynı politikada kaç tanım oluşturabilirim? | Sınır bulunmaz; performans gereksinimlerinize göre mantıklı sayıda tanım oluşturabilirsiniz. |
| Teknik | Algoritma adını istekte nasıl göndermeliyim? | sourceOfAlgorithm = FIND seçiliyse, algoritma adını belirlediğiniz değişkene (örn. header veya body alanı) yazmalısınız. |
| Teknik | IV bilgisi hangi formatta olmalı? | IV değeri seçtiğiniz ivEncodingType (BASE64 veya HEXADECIMAL) ile uyumlu olmalıdır; aksi halde decryption hata verir. |
| Kullanım | Sertifika revoked görünüyorsa politika çalışır mı? | Çalışır ancak revoked sertifika güvenlik riski oluşturur; en kısa sürede geçerli bir sertifika ile güncelleyin. |
| Kullanım | Hata mesajını özelleştirmek zorunda mıyım? | Hayır, ancak kullanıcı deneyimi ve izlenebilirlik için özelleştirilmiş hata kodu/mesajı tanımlamanız önerilir. |