HMAC Oluşturucu

HMAC nasıl çalışır?

HMAC (hash tabanlı mesaj kimlik doğrulama kodu, RFC 2104), kriptografik bir hash fonksiyonunu gizli bir anahtarla birleştirir. Bir mesaj için doğru değeri yalnızca anahtarı bilen biri üretebilir; bu nedenle eşleşen bir HMAC aynı anda iki şeyi kanıtlar: mesaj değiştirilmemiştir ve anahtara sahip biri tarafından gönderilmiştir.

Yapı şöyledir: H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Anahtar, hash fonksiyonunun blok boyutundan (MD5, SHA-1 ve SHA-256 için 64 bayt, SHA-384 ve SHA-512 için 128 bayt) uzunsa önce hash'lenir; ardından sıfırlarla bu boyuta tamamlanır. Sonra mesaj üzerinden bir iç hash hesaplamak için ipad (0x36 değerindeki baytlar) ile, iç sonuç üzerinden bir dış hash hesaplamak için de opad (0x5c değerindeki baytlar) ile XOR işlemine sokulur. Basit bir SHA-256(key ‖ message) yapısında dış hash yoktur; bu yüzden tek bir etiketi gören herkes mesaja veri ekleyip anahtar olmadan geçerli yeni bir etiket hesaplayabilir (uzunluk genişletme saldırısı).

Çıktı, temel alınan hash fonksiyonunun uzunluğundadır: HMAC-SHA256 için 32 bayt, yani 64 hex karakteri. RFC 2104 en az bu uzunlukta bir anahtar önerir; rastgele Base64 oluşturucu bu amaca uygun anahtarlar üretir.

HMAC imzalarının kullanıldığı yerler

• GitHub webhook'ları. X-Hub-Signature-256 başlığı, sha256= ve ardından ham istek gövdesinin webhook gizli anahtarıyla hesaplanmış hex HMAC-SHA256 değerinden oluşur. Başlık değerinin tamamını "Karşılaştırılacak değer" alanına yapıştırabilirsiniz; sha256= öneki yok sayılır.
• Stripe webhook'ları. Stripe-Signature başlığı bir t zaman damgası ve bir v1 imzası taşır: imza; zaman damgası, bir nokta ve ham gövdeden oluşan dizenin, metin olarak kullanılan uç nokta gizli anahtarıyla (whsec_...) hesaplanmış hex HMAC-SHA256 değeridir.
• Shopify webhook'ları. X-Shopify-Hmac-Sha256, ham gövdenin uygulamanın istemci gizli anahtarıyla (client secret) hesaplanmış HMAC-SHA256 değerini Base64 olarak içerir; bu yüzden Base64 çıktısını seçin veya başlık değerini "Karşılaştırılacak değer" alanına yapıştırın.
• AWS Signature Version 4. İmzalama anahtarı, HMAC-SHA256 hesaplamaları zincirlenerek türetilir: önce tarihin HMAC değeri, AWS4 ile gizli erişim anahtarının birleşimi anahtar olarak kullanılarak hesaplanır; ardından aynı işlem bölge, hizmet ve aws4_request için, her seferinde bir önceki sonuç anahtar olarak kullanılarak tekrarlanır. Bir adımın çıktısını bir sonrakine aktarmak için anahtar biçimini "Onaltılık" olarak ayarlayın.
• JSON Web Token'lar. HS256, HS384 ve HS512; kodlanmış başlık, bir nokta ve kodlanmış yük üzerinden hesaplanan HMAC-SHA256, -384 ve -512'dir. Token'ın üçüncü bölümü, URL güvenli Base64 ile yazılmış bu HMAC'tir ve "Karşılaştırılacak değer" alanı onu olduğu gibi kabul eder. JWT çözücü token'ların tamamını doğrular.

HMAC'i her zaman ham gövde üzerinden, tam olarak alındığı hâliyle hesaplayın. JSON'u ayrıştırıp yeniden serileştirmek boşlukları veya anahtar sırasını değiştirir; tek bir fazladan satır sonu bile tamamen farklı bir HMAC verir.

Kodda HMAC

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # sabit zamanlı karşılaştırma

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual uzunluklar farklıysa hata fırlatır, bu yüzden önce onları kontrol edin
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: mesaj anahtardan önce gelir
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: önce metin anahtar, ardından aynı anahtar hex olarak
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Test vektörü: anahtar "key", mesaj "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Kendi kodunuzda bir imzayı doğrularken yukarıdakiler gibi sabit zamanlı bir karşılaştırma kullanın. Basit bir == ilk farklı karakterde durur ve bu zamanlama farkı, bir saldırganın geçerli bir imzayı bayt bayt bulmasını sağlayabilir. Stripe'ınki gibi zaman damgalı şemalarda, zaman damgası birkaç dakikadan eski olan istekleri de reddedin; bu, yeniden oynatma (replay) saldırılarını engeller.