easy-hmac

A pure Python package with zero dependencies to generate and verify HMAC-SHA256 signatures for HTTP request authentication.

Installation

pip install easy-hmac

Quick Start

Generate a signature

import datetime
from base64 import b64encode

from easy_hmac import generate_hmac_sha256

secret = "my-secret-key"
body = '{"event": "updated", "status": "PROCESSING"}'
method = "POST"
path = "/api/v1/webhook"
timestamp = datetime.datetime.now(datetime.UTC).strftime("%a, %d %b %Y %H:%M:%S GMT")

digest = generate_hmac_sha256(secret, method, body, path, timestamp)
signature = b64encode(digest).decode()

Verify a signature

from easy_hmac import verify_hmac, AuthenticationFailed

try:
    verify_hmac(
        secret=secret,
        hmac_base64=signature,
        md5_body=content_md5,
        raw_body=body.encode(),
        timestamp=timestamp,
        content_type="application/json",
        path=path,
        request_method=method,
    )
except AuthenticationFailed:
    # Signature invalid, body tampered, or timestamp expired (>15 min)
    pass

API

generate_hmac_sha256(secret, method, body, path, timestamp)

Generates an HMAC-SHA256 digest from HTTP request components.

Returns: bytes — the raw HMAC digest.

verify_hmac(secret, hmac_base64, md5_body, raw_body, timestamp, content_type, path, request_method)

Verifies an incoming HMAC signature against the request components. Checks the body integrity via MD5 hash and rejects requests older than 15 minutes.

Returns: True if verification succeeds.

Raises: AuthenticationFailed if the signature is invalid, the body was tampered, the timestamp is malformed, or the request is older than 15 minutes.

Exceptions

AuthenticationFailed

Raised by verify_hmac when verification fails. Subclass of Exception.

Message Format

Both functions construct the HMAC message by joining components with newlines:

HTTP_METHOD\nCONTENT_MD5\nCONTENT_TYPE\nTIMESTAMP\nPATH

This follows a common pattern for REST API HMAC authentication where the content MD5 ensures body integrity and the timestamp prevents replay attacks.

Development

# Clone and set up
uv sync

# Run tests
uv run pytest

# Build
uv build

License

MIT