API Erişimi

Bu ekran ne işe yarar?

Kurum → API erişimi sayfası, kendi sistemlerinizin NetSSL ile konuşmasını sağlar. API ile panele girmeden şu işleri yaparsınız:

• Saldırgan IP adreslerini engeller veya engeli kaldırırsınız.
• Sitenin önbelleğini temizlersiniz.
• Bakım modunu açar veya kapatırsınız.
• Güvenlik olaylarını ve sitelerin durumunu çekersiniz.
• Joker SSL sertifikasının bilgilerini ve dosyalarını alır, yenilemeyi başlatırsınız.

Sayfayı yalnızca tüm hostlara yetkili kurum yöneticisi açabilir.

Ne zaman kullanırsınız?

• FortiGate gibi bir güvenlik duvarı, kendi tespit ettiği saldırgan IP'leri NetSSL'de de engellesin istiyorsunuz.
• SIEM veya SOME sisteminiz yeni güvenlik olaylarını düzenli olarak çekecek.
• Site güncellemesinden sonra yayın betiğiniz önbelleği otomatik temizlesin istiyorsunuz.
• Planlı bir çalışmada bakım modunu betikle açıp kapatacaksınız.
• Joker SSL sertifikasını kendi sunucularınıza betikle almak istiyorsunuz.

Kayıtların SIEM'e kendiliğinden gönderilmesini istiyorsanız API yerine SIEM / SOME aktarımını kullanın. Bu aktarım Bildirimler ve entegrasyonlar rehberinde anlatılır.

API erişimini açma

Anahtarlar bölümündeki API erişimini aç anahtarı tüm API'yi açar veya kapatır. Kapatınca bütün anahtarlarla gelen istekler hemen reddedilir. Anahtarlar silinmez, API'yi tekrar açınca çalışmaya devam eder.

Sayfanın üstündeki kutular API'nin durumunu, etkin anahtar sayısını, son 24 saatteki istekleri ve reddedilen istekleri gösterir.

Yeni anahtar oluşturma

Her entegrasyon için ayrı anahtar oluşturun. Bir anahtar sızarsa yalnızca onu iptal edersiniz.

1. Yeni anahtar bölümünde Anahtar adı yazın (ör. FortiGate otomatik engelleme).
2. Son kullanma süresini seçin: Süresiz, 30 gün, 90 gün veya 1 yıl. Varsayılan 1 yıldır.
3. Yetki olarak Salt okunur veya Okuma ve yazma seçin.
4. Siteler alanında Tüm siteler veya Seçtiğim siteler seçin.
5. Yalnızca bu IP / ağlardan kullanılabilsin (önerilir) alanına sisteminizin IP adresini veya ağını yazın.
6. Anahtarı oluştur düğmesine basın.

• IP alanını boş bırakırsanız anahtar her yerden kullanılabilir. Alanın altında şu anki adresiniz yazar.
• Yazma yetkili anahtar oluşturmak kritik bir işlemdir ve e-posta koduyla onaylanır. Dört göz onayı açıksa ikinci bir kurum yöneticisinin onayı da gerekir.
• Bir kurumda en fazla 20 etkin anahtar olabilir.

Anahtar oluşunca ekranda iki değer çıkar:

• Anahtar kimliği (X-NetSSL-Key): isteklerde gönderilir, gizli değildir.
• Gizli anahtar: istekleri imzalamak için kullanılır, isteklerde gönderilmez.

Gizli anahtar yalnızca bu ekranda bir kez gösterilir. Aynı ekranda, anahtarınızın içine yazıldığı hazır bir bash komutu da bulunur. Anahtar oluşunca kurum yöneticilerine e-posta gider.

Anahtar listesi ve iptal

Anahtarlar tablosu her anahtarın adını, kimliğini, oluşturan kişiyi ve tarihini gösterir.

• İptal et düğmesi anahtarı kalıcı olarak kapatır. Bu anahtarla gelen istekler hemen reddedilir. İşlem geri alınamaz, gerekirse yeni anahtar oluşturursunuz.
• Son istekler bölümü API isteklerini yöntem, adres, anahtar adı, IP ve sonuç koduyla listeler. İstekler 90 gün saklanır.
• Yazma işlemleri Kayıtlar › Panel işlemleri bölümünde “API: anahtar adı” kaynağıyla görünür.

İmzalı istek nasıl gönderilir?

API adresi Belgeler bölümünün başında yazar ve /api/v1 ile biter. Yanıtlar JSON biçimindedir. Başarılı yanıt {"ok":true,"data":…}, hatalı yanıt {"ok":false,"error":{"code","message"}} biçimindedir.

Her istekte üç başlık gönderilir:

İmza şu formülle hesaplanır: hex( HMAC-SHA256( gizli_anahtar, YÖNTEM + "\n" + YOL?SORGU + "\n" + ZAMAN + "\n" + hex(SHA256(gövde)) ) )

• Gövdesiz isteklerde (GET) boş metnin SHA256 değeri kullanılır.
• Yol, /api/v1 ile başlar ve sorgu metnini de içerir.
• Adreslerde {site} yerine site adı veya site numarası yazılabilir.
• Gizli anahtar ağda hiç gitmez. İmza yalnızca 5 dakika geçerlidir, bu yüzden sunucunuzun saati doğru olmalıdır.
• Değişiklik yapan isteğin imzası ikinci kez kabul edilmez. Araya giren biri isteği tekrarlayamaz.
• Aynı değişiklik isteğini aynı gövdeyle aynı saniyede iki kez göndermeyin. İkincisi tekrar sayılır ve reddedilir.

Uç noktalar

Güvenlik olaylarını çekme

• /events ve /hosts/{site}/events adresleri after_id, since, action, ip ve limit parametrelerini alır. limit en fazla 1000 olur.
• Olayları düzenli çekmek için ilk istekte since gönderin. Sonraki isteklerde yanıttaki next_after_id değerini after_id olarak gönderin. Böylece hiçbir olay kaçmaz ve hiçbiri iki kez gelmez.

IP engelleme

• Bir istekte en fazla 100 IP veya ağ gönderebilirsiniz. IPv4'te en geniş ağ /16 olur.
• Muaf (beyaz) listedeki IP'ler API ile engellenemez.
• Ağ engelini kaldırmak için adrese ?ip=1.2.3.0/24 ekleyin.

Joker SSL dosyası alma

Joker SSL sertifikanızın dosyalarını API ile alabilirsiniz. Örneğin tam zinciri almak için şu adrese istek gönderin: GET /api/v1/certs/<alan-adı>/files/fullchain.pem

• Dosyalar: fullchain.pem, cert.pem, chain.pem, privkey.pem, cert.pfx, cert-legacy.pfx, keystore.p12, keystore.jks, ssl.zip.
• Yanıt JSON'dur. PEM dosyaları content alanında metin olarak gelir. Diğer biçimler base64 olarak gelir ve yanıtta dosyanın parolası (password) da bulunur.
• fullchain.pem, cert.pem ve chain.pem salt okunur anahtarla da alınır. Özel anahtar içeren dosyalar için okuma ve yazma yetkili anahtar gerekir.
• /renew isteği bitişe 30 gün kala açılır. Daha önce gönderilirse 409 too_early yanıtı gelir. Saatte en fazla 5 deneme yapılabilir. Yenileme bitince cert.renewed webhook olayı gelir.

Joker SSL'in kendisi ve sunuculara dağıtımı Otomatik SSL ve joker SSL ile SSL dağıtım ajanı rehberlerinde anlatılır.

Hata kodları ve sınırlar

• Anahtar başına dakikada 120 istek gönderilebilir.
• Aynı adresten çok sayıda hatalı istek gelirse o adres 10 dakika reddedilir.
• Gizli anahtar panelde şifreli saklanır.

Hazır örnekler

Belgeler bölümünün sonundaki Örnek kod alanında üç hazır örnek vardır: bash / curl, PHP ve Python. Her örnek imzalı istek gönderen küçük bir işlev içerir. Kopyala düğmesiyle kodu alır, anahtar kimliğini ve gizli anahtarı kendi değerlerinizle değiştirirsiniz.

• bash örneği netssl GET /ping ile bağlantıyı dener ve bir IP'yi engeller.
• PHP örneği bir sitenin güvenlik olaylarını çeker.
• Python örneği bir sitede bakım modunu açar.

Sayfanın üstündeki Örnek istek düğmesi örnek istek ve yanıtları gösterir. Olay çekme, IP engelleme ve yeni anahtar e-postası örnekleri buradadır.

Sık sorulan sorular

Gizli anahtarı kaybettim, tekrar görebilir miyim?

Hayır. Gizli anahtar yalnızca oluşturulduğu anda bir kez gösterilir. Eski anahtarı İptal et ile kapatın ve yeni bir anahtar oluşturun.

Her istekte 401 hatası alıyorum.

İmza hatalı hesaplanıyor olabilir. İmzalanan metinde yolun /api/v1 ile başladığını ve sorgu metnini içerdiğini kontrol edin. GET isteklerinde boş metnin SHA256 değerini kullanın. Sunucunuzun saati 5 dakikadan fazla sapmışsa imza da reddedilir.

403 hatası alıyorum.

Üç neden olabilir. Anahtar salt okunur olabilir ve yazma işlemi deniyor olabilirsiniz. İsteğin geldiği IP, anahtarın IP sınırının dışında olabilir. Ya da API erişimini aç anahtarı kapalı olabilir.

Salt okunur anahtarla sertifika alabilir miyim?

fullchain.pem, cert.pem ve chain.pem dosyalarını alabilirsiniz. Özel anahtar içeren privkey.pem, PFX, P12, JKS ve ZIP dosyaları için okuma ve yazma yetkili anahtar gerekir.

API isteklerini kim gördü, nasıl takip ederim?

Her istek Son istekler bölümünde 90 gün listelenir. Yazma işlemleri ayrıca Kayıtlar › Panel işlemleri bölümüne “API: anahtar adı” kaynağıyla yazılır. Yeni anahtar oluşunca kurum yöneticilerine e-posta da gider.