HMAC 인증 개요

모든 보호 요청에는 네 헤더가 필요합니다.

X-API-KEY: {api_key}
X-TIMESTAMP: {unix_epoch_milliseconds}
X-NONCE: {uuid-v4}
X-SIGNATURE: {base64_hmac_sha256}

각 필드를 줄바꿈 두 개로 연결해 서명 대상 문자열을 만듭니다.

{HTTP_METHOD}\n\n{PATH_WITH_QUERY}\n\n{TIMESTAMP}\n\n{NONCE}\n\n{BODY_JSON}

메서드는 대문자, 경로와 쿼리는 실제 전송값 그대로 사용합니다. GET·DELETE의 body는 빈 문자열입니다. POST는 서명한 JSON 문자열과 실제 전송 바이트가 같아야 하며 공백이나 키 순서가 바뀌면 서명도 달라집니다.

재시도를 포함한 모든 요청에서 timestamp, nonce, signature를 새로 만드십시오. Nonce를 재사용하면 NONCE_REPLAYED, 시각 차이가 크면 INVALID_TIMESTAMP가 반환될 수 있습니다.

구현 예제와 문제 해결은 HMAC 요청 서명을 참고하십시오.

정규화 체크리스트

• 쿼리 순서와 percent encoding을 포함해 실제 전송 문자열을 그대로 사용합니다.
• 헤더와 정규 문자열에 동일한 timestamp 텍스트를 사용합니다.
• POST body는 한 번만 직렬화하고 그 문자열을 서명하고 그대로 전송합니다.
• 다섯 필드의 앞뒤에 추가 줄바꿈을 넣지 않습니다.
• 본문이 빈 문자열이어도 nonce 뒤의 구분자 \n\n은 유지합니다.
• 표시용 token이나 마스킹된 secret이 아닌 실제 HMAC 서명 키를 사용합니다.

검증 전략

고정 입력과 예상 Base64 서명을 이용해 서명 함수를 단위 테스트합니다. /time 호출 후 GET 한 건과 JSON POST 한 건을 서명하는 통합 테스트도 준비합니다. 문제를 분석할 때는 비밀이나 전체 정규 요청을 기록하지 않고 hash 또는 마스킹된 필드 길이를 비교합니다.

인증 오류를 일반 재시도 루프로 처리하지 않습니다. 반환된 action에 따라 시각 동기화, 새 nonce 생성, 키 교체 또는 서명 재생성을 수행합니다.