HMAC Üretici ve İmza Doğrulayıcı

HMAC Nedir?

const crypto = require('crypto');

// HMAC-SHA256 with a UTF-8 text key, hex output
const hmac = crypto
  .createHmac('sha256', 'my-secret-key')
  .update('Hello, World!')
  .digest('hex');

console.log(hmac);
// → 'cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699'

// Verify a signature in constant time
function verify(message, key, expectedHex) {
  const actual = crypto.createHmac('sha256', key).update(message).digest();
  const expected = Buffer.from(expectedHex, 'hex');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(actual, expected);
}

Temel Özellikler

HMAC Örnekleri

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

{"id":42,"event":"user.created"}

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

HMAC Nasıl Üretilir ve Doğrulanır

1. 1

   Algoritmayı seçin

   HMAC-SHA256'yı seçin (varsayılan ve neredeyse tüm webhook, API ve JWT'ler için doğru tercih) ya da bunu gerektiren bir sisteme uymak için SHA-1, SHA-384 veya SHA-512'ye geçin. Dördü de Web Crypto API üzerinden tarayıcınızda yerel olarak çalışır.

2. 2

   Gizli anahtarı girin ve kodlamasını ayarlayın

   Gizli anahtarınızı yazın veya yapıştırın, ardından Anahtar kodlamasını sunucunun onu nasıl yorumladığına uyacak şekilde ayarlayın: düz bir dize için Metin (UTF-8), onaltılık bir blob için Hex veya base64 bir gizli anahtar için Base64. Bunu yanlış yapmak HMAC uyuşmazlıklarının baş nedenidir, bu yüzden tereddütteyseniz üçünü de deneyin.

3. 3

   Mesajı girin

   İmzalamak istediğiniz tam baytları yapıştırın — bir webhook için bu, yeniden serileştirme veya boşluk değişikliği olmadan, bayt bayt ham istek gövdesidir. HMAC siz düzenledikçe canlı olarak yeniden hesaplanır ve sunucuya hiçbir şey gönderilmez.

4. 4

   Çıktı biçimini seçin ve kopyalayın

   Entegrasyonunuzun beklediğine uymak için Hex (GitHub tarzı), Base64 (Stripe/AWS tarzı) veya Base64URL (JWT tarzı) seçin, ardından imzayı almak için Kopyala'ya tıklayın.

5. 5

   Mevcut bir imzayı doğrulayın

   Doğrula sekmesine geçin, bir başlıktan veya tokendan Beklenen HMAC'i yapıştırın; araç, hesapladığınız imzanın eşleşip eşleşmediğini sabit zamanda doğrular — böylece bir yük üzerinde işlem yapmadan önce onu kimlik doğrulayabilirsiniz.

Yaygın HMAC Hataları

// Server stored a base64 secret but you sign the literal string
createHmac('sha256', 'c2VjcmV0LWtleQ==').update(msg)

// Decode the base64 secret to raw bytes first
createHmac('sha256', Buffer.from('c2VjcmV0LWtleQ==', 'base64')).update(msg)

// Provider sends base64, you compare hex
expected = 'Cd2f7z...=' // base64
actual   = digest('hex') // hex — never matches

// Produce the same encoding the provider uses
actual = digest('base64')

// Re-serialization changes the bytes
body = JSON.stringify(JSON.parse(rawBody))
verify(hmac(body))

// Sign the raw bytes exactly as received
verify(hmac(rawBody))

if (received === computed) { /* trust */ }

if (crypto.timingSafeEqual(receivedBuf, computedBuf)) { /* trust */ }

HMAC Ne İçin Kullanılır

Webhook imzalarını doğrula

GitHub, Stripe, Slack ve Twilio gibi sağlayıcılar her webhook'u istek gövdesi ve yalnızca sizinle paylaştıkları bir gizli anahtar üzerinde HMAC ile imzalar. Etiketi yeniden hesaplayın ve başlıkla (örneğin X-Hub-Signature-256) karşılaştırarak, üzerinde işlem yapmadan önce olayın gerçek olduğunu doğrulayın. Bunu tek seferlik kod yazmadan yapmak için Doğrula sekmesini kullanın.

API isteklerini imzala

Kimlik doğrulamalı API'ler genellikle istemcinin gizli anahtarın kendisini göndermek yerine, isteği (yöntem, yol, zaman damgası, gövde) paylaşılan bir gizli anahtarla HMAC ile imzalamasını ister. AWS Signature Version 4 kanonik örnektir. Bu araç, bu imzaları adım adım yeniden üretmenize ve hata ayıklamanıza olanak tanır.

Mesaj bütünlüğünü garanti et

Servisler arasında bir token, çerez veya mesaj geçirdiğinizde bir HMAC eklemek, alıcının her türlü kurcalamayı tespit etmesini sağlar. Etiket bir gizli anahtara bağlı olduğundan saldırgan, veriyi değiştirdikten sonra onu yeniden hesaplayamaz — düz bir sağlama toplamının aksine.

JWT HS256 imzalamayı anla

HS256 ile imzalanan bir JWT, yalnızca base64url(header) + '.' + base64url(payload)'dır; HMAC-SHA256 ile imzalanır ve sonuç Base64URL olarak yayılır. Bu imzanın tam olarak nasıl üretildiğini görmek için burada algoritmayı SHA-256'ya, çıktıyı Base64URL'ye ayarlayın, ardından JWT olusturucuda çapraz kontrol edin.

Eşleşmeyen bir imzayı ayıkla

HMAC'iniz sunucununkiyle eşleşmediğinde, bu araç nedenini izole etmenin en hızlı yoludur: anahtarı Metin, Hex ve Base64 olarak deneyin, çıktıyı Hex ile Base64 arasında değiştirin ve tam ham baytları imzaladığınızdan emin olun — hepsi herhangi bir kodu yeniden dağıtmadan.

HMAC Nasıl Çalışır

RFC 2104 yapısı

HMAC, H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m)) olarak tanımlanır; burada ipad tekrarlanan 0x36 baytı, opad ise tekrarlanan 0x5c baytıdır ve ikisi de hash'in blok boyutuna kadar uzanır. Blok boyutundan uzun bir anahtar önce hash'lenir; daha kısa bir anahtar sıfırla doldurulur. Bu iki geçişli iç içe yapı, HMAC'e güvenlik kanıtını verir ve bu kanıt, alttaki hash çakışmaya dirençli olmasa bile geçerlidir.

Anahtarlı bir hash neden düz bir hash'i yener

Düz bir hash yalnızca verinin rastlantısal olarak bozulmadığını kanıtlar, çünkü herkes onu herhangi bir mesaj için — değiştirilmiş bir mesaj dahil — yeniden hesaplayabilir. HMAC araya gizli bir anahtar katar, böylece yalnızca anahtar sahipleri geçerli bir etiket üretebilir. Bu, yalnızca-bütünlüğü, webhook'ların ve imzalı isteklerin gerçekten ihtiyaç duyduğu özellik olan bütünlük artı gerçekliğe dönüştürür.

Uzunluk uzatma direnci

Çıplak SHA-1, SHA-256 ve SHA-512, uzunluk uzatmaya açık Merkle–Damgård hash'leridir: H(secret ‖ msg) verildiğinde bir saldırgan, gizli anahtarı bilmeden H(secret ‖ msg ‖ extra) hesaplayabilir. Naif 'gizli-önekli MAC' şemaları bununla kırılır. HMAC'in dış hash'i bu saldırıyı etkisizleştirir; bu da gizli anahtarı ve mesajı birlikte hash'lemek yerine HMAC kullanmanın başlıca nedenidir.

SHA-256 ile SHA-512 arasında seçim

HMAC-SHA256, 256 bit (64 hex karakter) bir etiket üretir ve birlikte çalışabilirlik varsayılanıdır — hızlı, yaygın ve her yerde desteklenir. HMAC-SHA512, 512 bit (128 hex karakter) bir etiket üretir ve SHA-512 64 bit kelimeler kullandığından 64 bit CPU'larda genellikle daha hızlıdır. Bir spesifikasyon veya eş sistem SHA-512 gerektirmedikçe SHA-256'yı seçin; ikisi de kimlik doğrulama için güvenlidir.

Web Crypto uygulaması

Bu araç, anahtarınızı (Metin, Hex veya Base64'ten çözülmüş) yüklemek için crypto.subtle.importKey'i ve etiketi hesaplamak için crypto.subtle.sign('HMAC', ...) çağrısını kullanır, ardından ham baytları Hex, Base64 veya Base64URL olarak kodlar. Bu, tarayıcının TLS için kullandığı, hız için JavaScript motorunun dışında çalışan, aynı yerel ve denetlenmiş uygulamadır.

HMAC En İyi Uygulamaları

Hash çıktısı kadar uzun bir anahtar kullanın

HMAC-SHA256 için en az 32 rastgele bayt (256 bit), SHA-512 için 64 bayt uzunluğunda bir gizli anahtar kullanın. Kısa veya düşük entropili bir anahtar en zayıf halkadır. Anahtarları kriptografik olarak güvenli bir rastgele kaynaktan üretin — asla bir paroladan veya tahmin edilebilir bir dizeden değil.

Etiketleri her zaman sabit zamanda karşılaştırın

İmzaları == veya dize eşitliği yerine sabit zamanlı bir karşılaştırmayla (Node'da crypto.timingSafeEqual, Python'da hmac.compare_digest) doğrulayın. Naif bir karşılaştırma, farklılaşan ilk baytta erken döner ve bir saldırganın geçerli bir etiketi bayt bayt kurtarmasına izin verebilecek zamanlama sızdırır. Bu aracın Doğrula sekmesi zaten sabit zamanda karşılaştırır.

Gizli anahtarı asla loglamayın veya ifşa etmeyin

İmzalama gizli anahtarlarını loglardan, hata mesajlarından, URL'lerden ve istemci tarafı koddan uzak tutun. Bunları bir gizli anahtar yöneticisinde veya ortam değişkenlerinde saklayın, periyodik olarak döndürün ve her entegrasyonu kendi anahtarıyla kapsayın ki bir sızıntı her şeyi tehlikeye atmasın.

HMAC-SHA256 veya daha güçlüsünü tercih edin

Varsayılan olarak HMAC-SHA256 kullanın; bir eş gerektirdiğinde SHA-384 veya SHA-512'ye yükseltin. Yeni sistemlerde HMAC-SHA1'den kaçının ve asla HMAC-MD5 kullanmayın. HMAC, ham bir imzaya göre daha zayıf bir hash'i daha iyi tolere etse de modern bir hash'ten başlamak size en büyük marjı verir.

Zaman damgası dahil tam baytları imzalayın

Ham, değiştirilmemiş yükü imzalayın — JSON'u yeniden serileştirmek veya boşlukları kırpmak baytları değiştirir ve doğrulamayı bozar. İstek imzalama için imzalanan veriye bir zaman damgası veya nonce ekleyin ve yeniden oynatma (replay) saldırılarını önlemek için eski imzaları reddedin.

HMAC SSS