HMAC 생성기 및 서명 검증 도구

HMAC이란 무엇인가요?

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);
}

주요 기능

HMAC 예시

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

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

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

HMAC 생성 및 검증 방법

1. 1

   알고리즘 선택

   HMAC-SHA256(기본값이며 거의 모든 webhook, API, JWT에 적합한 선택)을 선택하거나, 이를 요구하는 시스템에 맞게 SHA-1, SHA-384, SHA-512로 전환하세요. 네 가지 모두 Web Crypto API를 통해 브라우저에서 기본적으로 실행됩니다.

2. 2

   비밀 키 입력 및 인코딩 설정

   비밀 키를 입력하거나 붙여넣은 다음, 서버가 해석하는 방식에 맞게 '키 인코딩'을 설정하세요. 일반 문자열은 Text(UTF-8), 16진수 바이트열은 Hex, base64 시크릿은 Base64입니다. 이를 잘못 설정하는 것이 HMAC 불일치의 가장 큰 원인이므로 확실하지 않으면 세 가지 모두 시도하세요.

3. 3

   메시지 입력

   서명하려는 정확한 바이트를 붙여넣으세요. webhook의 경우 재직렬화나 공백 변경 없이 바이트 단위 그대로의 원시 요청 본문입니다. HMAC은 편집에 따라 즉석에서 다시 계산되며 서버로 아무것도 전송되지 않습니다.

4. 4

   출력 형식 선택 및 복사

   Hex(GitHub 방식), Base64(Stripe/AWS 방식), Base64URL(JWT 방식) 중 연동 대상이 기대하는 것에 맞게 선택한 다음 '복사'를 클릭해 서명을 가져오세요.

5. 5

   기존 서명 검증

   '검증' 탭으로 전환해 헤더나 토큰의 '예상 HMAC'을 붙여넣으면, 도구가 계산한 서명이 일치하는지 상수 시간으로 확인합니다. 따라서 페이로드에 대해 행동하기 전에 인증할 수 있습니다.

흔한 HMAC 실수

// 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의 용도

webhook 서명 검증

GitHub, Stripe, Slack, Twilio 같은 제공업체는 여러분과만 공유하는 시크릿으로 요청 본문에 대한 HMAC을 사용해 각 webhook에 서명합니다. 태그를 다시 계산해 헤더(예: X-Hub-Signature-256)와 비교하여 행동하기 전에 이벤트가 진짜인지 확인하세요. '검증' 탭을 사용하면 일회용 코드를 작성하지 않고도 할 수 있습니다.

API 요청 서명

인증된 API는 종종 시크릿 자체를 보내는 대신 공유 시크릿으로 요청(메서드, 경로, 타임스탬프, 본문)을 HMAC 서명하도록 클라이언트에 요구합니다. AWS Signature Version 4가 대표적인 예입니다. 이 도구로 그러한 서명을 단계별로 재현하고 디버깅할 수 있습니다.

메시지 무결성 보장

서비스 간에 토큰, 쿠키 또는 메시지를 전달할 때 HMAC을 붙이면 수신자가 모든 변조를 탐지할 수 있습니다. 태그가 시크릿에 의존하므로 공격자는 데이터를 수정한 후에 다시 계산할 수 없습니다. 일반 체크섬과는 다릅니다.

JWT HS256 서명 이해

HS256으로 서명된 JWT는 base64url(header) + '.' + base64url(payload)를 HMAC-SHA256으로 서명하고 결과를 Base64URL로 출력한 것일 뿐입니다. 여기서 알고리즘을 SHA-256, 출력을 Base64URL로 설정하면 그 서명이 정확히 어떻게 생성되는지 볼 수 있으며, JWT 인코더에서 교차 확인할 수 있습니다.

일치하지 않는 서명 디버깅

HMAC이 서버의 것과 일치하지 않을 때, 이 도구는 원인을 분리하는 가장 빠른 방법입니다. 키를 Text, Hex, Base64로 시도하고, 출력을 Hex와 Base64 사이에서 전환하며, 정확한 원시 바이트에 서명하고 있는지 확인하세요. 모두 코드를 재배포하지 않고 할 수 있습니다.

HMAC 작동 원리

RFC 2104 구조

HMAC은 H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m))으로 정의되며, 여기서 ipad는 반복된 바이트 0x36, opad는 반복된 0x5c로, 둘 다 해시의 블록 크기까지 채워집니다. 블록 크기보다 긴 키는 먼저 해시되고, 더 짧은 키는 0으로 패딩됩니다. 이 2단계 중첩이 HMAC의 보안 증명을 제공하며, 기반 해시가 충돌 저항성을 갖지 않더라도 성립합니다.

키 적용 해시가 일반 해시보다 나은 이유

일반 해시는 데이터가 우발적으로 손상되지 않았다는 것만 증명합니다. 누구나 어떤 메시지(변조된 것 포함)에 대해서도 다시 계산할 수 있기 때문입니다. HMAC은 시크릿을 섞어 넣으므로 키 보유자만 유효한 태그를 생성할 수 있습니다. 이는 무결성만 있는 것을 무결성과 진정성으로 바꾸며, webhook과 서명된 요청이 실제로 필요로 하는 속성입니다.

길이 확장 저항성

맨 SHA-1, SHA-256, SHA-512는 Merkle–Damgård 해시로 길이 확장에 취약합니다. H(secret ‖ msg)가 주어지면 공격자는 시크릿을 모르고도 H(secret ‖ msg ‖ extra)를 계산할 수 있습니다. 순진한 '시크릿 접두사 MAC' 방식은 이로 인해 깨집니다. HMAC의 외부 해시가 이 공격을 무력화하며, 이것이 시크릿과 메시지를 함께 해시하는 대신 HMAC을 사용하는 주된 이유입니다.

SHA-256과 SHA-512 중 선택

HMAC-SHA256은 256비트(64 hex 문자) 태그를 생성하며 상호 운용성의 기본값입니다. 빠르고, 보편적이며, 어디서나 지원됩니다. HMAC-SHA512는 512비트(128 hex 문자) 태그를 생성하며, SHA-512가 64비트 워드를 사용하므로 64비트 CPU에서 종종 더 빠릅니다. 사양이나 상대 시스템이 SHA-512를 요구하지 않는 한 SHA-256을 선택하세요. 둘 다 인증에 안전합니다.

Web Crypto 구현

이 도구는 crypto.subtle.importKey를 호출해 키를 로드하고(Text, Hex 또는 Base64에서 디코딩), crypto.subtle.sign('HMAC', ...)으로 태그를 계산한 다음, 원시 바이트를 Hex, Base64 또는 Base64URL로 인코딩합니다. 이는 브라우저가 TLS에 사용하는 것과 동일한 기본적이고 감사된 구현으로, 속도를 위해 JavaScript 엔진 밖에서 실행됩니다.

HMAC 모범 사례

해시 출력 이상의 길이의 키 사용

HMAC-SHA256에는 최소 32 무작위 바이트(256비트)의 시크릿을, SHA-512에는 64바이트를 사용하세요. 짧거나 엔트로피가 낮은 키는 가장 약한 고리입니다. 키는 암호학적으로 안전한 무작위 소스에서 생성하세요. 절대 비밀번호나 예측 가능한 문자열을 사용하지 마세요.

태그는 항상 상수 시간으로 비교

서명은 ==나 문자열 동등성이 아니라 상수 시간 비교(Node의 crypto.timingSafeEqual, Python의 hmac.compare_digest)로 검증하세요. 순진한 비교는 처음으로 다른 바이트에서 일찍 반환하여, 공격자가 유효한 태그를 한 바이트씩 복원할 수 있는 타이밍을 누출합니다. 이 도구의 '검증' 탭은 이미 상수 시간으로 비교합니다.

비밀 키를 절대 로깅하거나 노출하지 않기

서명 시크릿을 로그, 오류 메시지, URL, 클라이언트 측 코드에서 배제하세요. 시크릿 관리자나 환경 변수에 저장하고, 주기적으로 교체하며, 각 연동을 각자의 키로 범위 지정하여 한 번의 유출이 모든 것을 위태롭게 하지 않도록 하세요.

HMAC-SHA256 이상을 우선하기

기본값은 HMAC-SHA256으로 하고, 상대가 요구하면 SHA-384나 SHA-512로 올리세요. 새 시스템에서 HMAC-SHA1은 피하고 HMAC-MD5는 절대 사용하지 마세요. HMAC이 맨 서명보다 약한 해시를 더 잘 견디더라도, 최신 해시에서 시작하면 가장 큰 여유를 얻습니다.

타임스탬프를 포함한 정확한 바이트에 서명

원시이며 변경되지 않은 페이로드에 서명하세요. JSON을 재직렬화하거나 공백을 다듬으면 바이트가 바뀌어 검증이 깨집니다. 요청 서명의 경우 서명 데이터에 타임스탬프나 nonce를 포함하고 오래된 서명을 거부하여 재전송 공격을 방지하세요.

HMAC 자주 묻는 질문