Şifre Açma

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) ü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

1. İstek Gelişi: API Gateway'e gelen her HTTP/HTTPS isteği için, istemin kaynak IP adresi tespit edilir.
2. 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ı?
3. Ş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.
4. 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.
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 Ş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: 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: Ş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 5: 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 6: 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 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 şifre açma 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 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.