hmac — 메시지 인증용 키 기반 해시

hmac — 메시지 인증용 키 기반 해시 (Keyed-Hashing for Message Authentication)

hmac 모듈은 RFC 2104에 기술된 HMAC 알고리즘을 구현해요. 이 인터페이스는 고정된(fixed) 다이제스트 크기를 가진 어떤 해시 함수든 사용할 수 있게 해 줍니다. 특히 SHAKE-128이나 SHAKE-256 같은 확장 가능한 출력 함수(extendable output function)는 HMAC에 사용할 수 없어요.

출처: Python 표준 라이브러리

new()

  • hmac.new(key, msg=None, digestmod)

새 hmac 객체를 반환해요. key는 비밀 키를 담은 bytes 또는 bytearray 객체예요. msg가 있으면 update(msg) 메서드 호출이 이뤄집니다. digestmod는 HMAC 객체가 사용할 다이제스트 이름, 다이제스트 생성자(constructor) 또는 모듈이에요. hashlib.new()에 적합한 어떤 이름이든 쓸 수 있어요. 인자 위치상 뒤에 있지만, 필수 인자입니다.

버전 3.4에서 변경: key 매개변수가 bytes 또는 bytearray 객체가 될 수 있어요. msg 매개변수는 hashlib가 지원하는 어떤 타입이든 될 수 있고, digestmod 매개변수는 해시 알고리즘의 이름이 될 수 있습니다.

버전 3.8에서 변경: digestmod 인자가 이제 필수예요. 초기 msg가 없을 때 생기는 어색함을 피하려면 키워드 인자로 전달하세요.

digest()

  • hmac.digest(key, msg, digest)

주어진 비밀 key와 digest에 대한 msg의 다이제스트를 반환해요. 이 함수는 HMAC(key, msg, digest).digest()와 동일하지만, 최적화된 C 또는 인라인 구현을 사용해서 메모리에 들어가는 크기의 메시지에 대해 더 빠릅니다. key, msg, digest 매개변수는 new()에서와 같은 의미를 가져요.

CPython 구현 세부사항: 최적화된 C 구현은 digest가 문자열이면서 OpenSSL이 지원하는 다이제스트 알고리즘의 이름일 때만 사용됩니다.

버전 3.7에서 추가됨.

HMAC 클래스

  • class hmac.HMAC

HMAC 객체는 다음과 같은 메서드를 가져요:

update()

  • HMAC.update(msg)

msg로 hmac 객체를 갱신해요. 반복 호출은 모든 인자를 이어 붙인 단일 호출과 동일합니다: m.update(a); m.update(b)는 m.update(a + b)와 같아요.

버전 3.4에서 변경: msg 매개변수는 hashlib가 지원하는 어떤 타입이든 될 수 있어요.

digest()

  • HMAC.digest()

지금까지 update() 메서드에 전달된 bytes의 다이제스트를 반환해요. 이 bytes 객체는 생성자에 주어진 다이제스트의 digest_size와 같은 길이예요. NUL 바이트를 포함한 비-ASCII 바이트를 담을 수 있습니다.

경고: digest()의 출력을 검증 루틴에서 외부에서 공급된 다이제스트와 비교할 때는 == 연산자 대신 compare_digest() 함수를 쓰는 것이 타이밍 공격(timing attack)에 대한 취약성을 줄이는 데 권장돼요.

hexdigest()

  • HMAC.hexdigest()

digest()와 같지만 다이제스트를 두 배 길이의, 16진수 숫자만 담은 문자열로 반환해요. 이메일이나 다른 바이너리가 아닌 환경에서 값을 안전하게 주고받는 데 사용할 수 있습니다.

경고: hexdigest()의 출력을 검증 루틴에서 외부에서 공급된 다이제스트와 비교할 때는 == 연산자 대신 compare_digest() 함수를 쓰는 것이 타이밍 공격에 대한 취약성을 줄이는 데 권장돼요.

copy()

  • HMAC.copy()

hmac 객체의 복사본("클론")을 반환해요. 공통의 초기 부분 문자열을 공유하는 문자열들의 다이제스트를 효율적으로 계산하는 데 사용할 수 있습니다.

속성

  • HMAC.digest_size — 결과 HMAC 다이제스트의 크기(바이트).
  • HMAC.block_size — 해시 알고리즘의 내부 블록 크기(바이트). 버전 3.4에서 추가됨.
  • HMAC.name — 이 HMAC의 정식 이름으로 항상 소문자. 예: hmac-md5. 버전 3.4에서 추가됨.

버전 3.10에서 변경: 문서화되지 않았던 속성 HMAC.digest_cons, HMAC.inner, HMAC.outer가 제거됐어요.

compare_digest()

이 모듈은 다음 헬퍼 함수도 제공해요:

  • hmac.compare_digest(a, b)

a == b를 반환해요. 이 함수는 콘텐츠 기반 단락(short-circuiting) 동작을 피해 타이밍 분석을 막도록 설계된 접근 방식을 쓰므로 암호학에 적합합니다. a와 b는 둘 다 같은 타입이어야 해요: str(예: HMAC.hexdigest()가 반환하는 것처럼 ASCII만) 또는 bytes류 객체.

참고: a와 b의 길이가 다르거나 오류가 발생하면, 타이밍 공격이 이론적으로 a와 b의 타입과 길이에 대한 정보를 드러낼 수 있어요 — 다만 값 자체는 드러나지 않습니다.

버전 3.3에서 추가됨. 버전 3.10에서 변경: 가능하면 내부적으로 OpenSSL의 CRYPTO_memcmp()를 사용해요.

함께 보기: hashlib 모듈 — 보안 해시 함수를 제공하는 Python 모듈.

더 알아보기