HMAC 생성기

웹훅 서명 검증에서 대부분은 이 실수입니다

결제 완료 웹훅을 받는 서버를 만들면 반드시 서명 검증을 해야 합니다. 안 하면 누구나 "결제 성공" 요청을 흉내 내 상품을 공짜로 가져갈 수 있습니다. 그런데 검증 코드를 처음 짜면 거의 예외 없이 서명이 불일치합니다. 원인은 대개 하나입니다 — 파싱된 객체를 다시 문자열로 만들어 서명하기 때문입니다.

보내는 쪽은 자기가 전송한 본문 바이트 그대로에 서명합니다. 받는 쪽이 JSON으로 파싱한 뒤 다시 문자열로 만들면 공백·줄바꿈·키 순서·한글 이스케이프가 미묘하게 달라지고, 한 바이트만 달라도 HMAC은 완전히 다른 값이 됩니다. 반드시 원본 바이트(raw body)에 서명해야 합니다.

// Express: 이 라우트만 원본 바이트를 받는다 (전역 express.json() 보다 먼저)
app.post("/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.get("X-Signature") || "";
    const mine = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET)
      .update(req.body)          // Buffer 그대로. 파싱 후 재직렬화 금지
      .digest("hex");

    const a = Buffer.from(sig, "utf8");
    const b = Buffer.from(mine, "utf8");
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));  // 검증에 성공한 뒤에 파싱
    res.sendStatus(200);
  });

값이 안 맞을 때 점검 순서

위 탭에서 "검증"을 고르면 기대값 칸이 나타납니다. 상대가 보낸 서명을 그대로 붙여넣으면 방금 계산한 값과 비교해 일치·불일치를 알려줍니다. GitHub 스타일의 sha256= 접두어는 자동으로 떼어내고 hex와 Base64를 모두 인식합니다. 불일치라면 아래를 순서대로 보세요.

• 비밀키 형식 — 같은 키 문자열이라도 텍스트로 읽느냐 16진수로 읽느냐 Base64로 읽느냐에 따라 완전히 다른 바이트가 됩니다. 문서에 "hex로 인코딩된 키"라고 적혀 있으면 반드시 16진수 탭을 고르세요. 이 항목에서 틀리는 경우가 가장 많습니다.
• 출력 형식 — 상대가 Base64를 기대하는데 hex를 보내면 당연히 안 맞습니다. 길이가 두 배 가까이 차이 나면 이걸 의심하세요.
• 알고리즘 — SHA-256인지 SHA-1인지. 결과 바이트 수(32 vs 20)로 바로 구분됩니다.
• 메시지의 앞뒤 공백·줄바꿈 — 복사하다 딸려온 개행 하나로 값이 바뀝니다. CRLF와 LF도 다른 바이트입니다.
• 인코딩 — 메시지에 한글이 있으면 양쪽 다 UTF-8이어야 합니다. 이 도구는 UTF-8로 인코딩합니다.
• 서명 대상 — 본문만인지, 타임스탬프와 본문을 특정 형식으로 이어붙인 것인지. 서비스마다 다르니 연동 문서를 보세요.

왜 == 로 비교하면 안 되나 (타이밍 공격)

문자열 비교는 보통 앞에서부터 한 바이트씩 보다가 다르면 즉시 멈춥니다. 즉 첫 바이트가 틀린 값과 앞 열 바이트가 맞는 값은 비교에 걸리는 시간이 다릅니다. 공격자가 서명을 조금씩 바꿔가며 응답 시간을 수천 번 측정하면, 맞은 바이트가 하나 늘 때마다 아주 미세하게 느려지는 지점을 찾아 한 바이트씩 정답을 알아낼 수 있습니다.

실제 인터넷 너머로 이 차이를 측정하는 것은 네트워크 잡음 때문에 쉽지 않습니다. 하지만 같은 데이터센터 안이거나 요청을 대량으로 반복할 수 있으면 통계적으로 걸러집니다. 무엇보다 방어 비용이 0입니다 — 함수 하나만 바꾸면 됩니다.

HMAC과 단순 해시는 무엇이 다른가

"비밀키를 앞에 붙이고 해시하면 되는 것 아닌가" — sha256(secret + message) 방식은 실제로 취약합니다. SHA-256을 포함한 여러 해시 함수는 내부 구조상 길이 확장 공격이 가능합니다. 공격자가 secret 값을 몰라도 secret+message 의 해시 값과 message 만 알면, 뒤에 임의의 데이터를 덧붙인 메시지에 대한 올바른 해시를 계산해낼 수 있습니다. 키를 모르는 채로 유효한 서명을 위조하는 셈입니다.

HMAC은 키를 두 번에 나눠 안쪽 해시와 바깥쪽 해시로 감싸는 구조라 이 공격이 통하지 않습니다. 서명 방식을 직접 만들지 말고 표준 HMAC을 쓰라는 말이 나오는 이유입니다.

서명이 맞아도 막지 못하는 것 — 재전송 공격

HMAC이 검증해 주는 것은 "이 메시지가 키를 가진 쪽에서 왔고 도중에 바뀌지 않았다"는 사실뿐입니다. 그 메시지가 언제 만들어졌는지, 이미 처리한 것인지는 알려주지 않습니다. 공격자가 유효한 요청을 그대로 복사해 100번 다시 보내면 서명은 100번 다 통과합니다.

• 타임스탬프를 서명 대상에 포함하고, 서버 시각과 5분 이상 차이 나는 요청은 거부하세요. 타임스탬프가 서명 밖에 있으면 공격자가 고쳐 쓸 수 있으니 반드시 서명 안에 넣어야 합니다.
• 이벤트 ID를 기록해 이미 처리한 것은 무시하세요(멱등 처리). 웹훅은 정상적으로도 중복 도착합니다.
• 금액·주문번호 같은 핵심 값은 서명이 맞더라도 우리 DB의 원장과 대조해 확인하세요.
• 비밀키와 메시지는 이 브라우저 안에서만 처리되고 서버로 가지 않습니다. 비밀키는 저장조차 하지 않아 새로고침하면 사라집니다. 그래도 운영 키를 웹 도구에 붙여넣는 습관은 권하지 않습니다 — 테스트 키로 형식을 맞춰본 뒤 코드로 옮기세요.