​

Güvenli API İstek İmzalama ve Idempotency Mekanizması

​

Genel Bakış

​

1. HMAC İmzası (X-Signature Başlığı)

​

Nedir?

​

Amacı

• Bütünlük: İsteğin herhangi bir kısmının (yöntem, URI, gövde, zaman damgası) değiştirilip değiştirilmediğini tespit eder.
• Kimlik Doğrulama: İsteğin gizli anahtarı bilen güvenilir bir istemciden geldiğini doğrular.
• Yeniden Oynatma Önleme: Bir zaman damgasına ve benzersiz değerlere bağlı olarak yeniden oynatma saldırılarını tespit edilebilir hale getirir.

​

Nasıl Kullanılır?

• İstemci imzalamak için HTTP yöntemini, tam istek yolunu (sorgu dahil), milisaniye cinsinden geçerli zaman damgasını ve çözümlenmiş istek gövdesini birleştiren bir dize oluşturur:

dataToSign = HTTP_METHOD + "|" + PATH_WITH_QUERY + "|" + TIMESTAMP + "|" + BODY

• İstemci, paylaşılan anahtarı (güvenli bir kasada tutulur, asla ifşa edilmez) kullanarak HMAC SHA256 imzasını oluşturur:

X-Signature = HMAC_SHA256(secret, dataToSign)

• Bu imza X-Signature istek başlığında gönderilir.

​

Kullanılmazsa ne olur?

• İstemci http durumu 400 - Hatalı İstek ile bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}

​

İmza geçerli değilse ne olur?

• İstemci, http durumu 401 - Yetkisiz olan bir hata mesajı alacaktır.

{
  "timestamp": "2025-04-14T16:57:50.083970026",
  "status": 401,
  "error": "Yetkisiz",
  "message": "Geçersiz istek imzası",
  "path": "/auth/login"
}

​

2. Zaman Damgası (X-Timestamp Başlığı)

​

Nedir?

​

Amaç

• Tekrar Oynatma Önleme: Sunucu geçerli istekler için katı zaman pencereleri uygulayabildiğinden, bir saldırganın daha önce geçerli olan bir isteği tekrar kullanmasını önler.

​

Nasıl Kullanılır?

• İstemci, isteği göndermeden hemen önce zaman damgasını oluşturur ve bunu X-Timestamp başlığı olarak ekler.

​

Kullanılmazsa ne olur?

• İstemci, http durumu 400 - Hatalı İstek olan bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}

​

3. Nonce - Tek Seferlik (X-Nonce Başlığı)

​

Nedir?

​

Amaç

• Yeniden Oynatma Önleme: Her isteği benzersiz bir şekilde tanımlayarak isteğin yeniden oynatılmasını daha da önler. Yöntem, URI ve gövde aynı olsa bile, nonce farklı olacaktır.

​

Nasıl Kullanılır?

• İstemci her istek için yeni bir UUID v4 oluşturur ve bunu X-Nonce başlığı olarak ekler.

​

Kullanılmazsa ne olur?

• İstemci, http durumu 400 - Hatalı İstek olan bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:58:10.414972912",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik imza, zaman damgası veya nonce başlıkları",
  "path": "/auth/login"
}

​

Yeniden kullanılırsa ne olur?

• İstemci http durumu 409 - Çakışma ile bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:57:21.168927321",
  "status": 409,
  "error": "Çakışma",
  "message": "Yeniden oynatma saldırısı tespit edildi (nonce yeniden kullanıldı)",
  "path": "/endpoint/uri/here"
}

​

4. Idempotency Anahtarı (X-Idempotency-Key Başlığı)

​

Nedir?

​

Amaç

• Idempotency: Ağ hataları nedeniyle bir isteğin yeniden denenmesinin yinelenen kaynak oluşturma veya yan etkilere neden olmayacağını garanti eder.

​

Nasıl Kullanılır?

• İstemci her işlem için yeni bir UUID v4 oluşturur ve bunu X-Idempotency-Key başlığı olarak gönderir.

​

What if not used?

• İstemci, http durumu 400 - Hatalı İstek olan bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:26:54.203118461",
  "status": 400,
  "error": "Hatalı İstek",
  "message": "Eksik X-Idempotency-Key başlığı",
  "path": "/endpoint/uri/here"
}

​

Yeniden kullanılırsa ne olur?

• İstemci http durumu 409 - Çakışma ile bir hata mesajı alacaktır

{
  "timestamp": "2025-04-14T16:56:28.671809875",
  "status": 409,
  "error": "Çakışma",
  "message": "Yinelenen istek algılandı (X-Idempotency-Key)",
  "path": "/endpoint/uri/here"
}

X-Signature: 75c759570bbb5dfd40136cffd3dbaa51b28d4620e51359161686790adcc53bea
X-Timestamp: 1752751106704
X-Nonce: 684a0dca-bd6a-4056-a449-2567f9847f9c
X-Idempotency-Key: 777edc03-ad49-4c17-be6b-9baf05a1b9e0

​

Özet Tablo