Does the caller know the secret?

Does the caller know the secret AND did the caller sign this exact request at this time?

method + path + query + selected headers + body hash + timestamp + nonce

client and server share a secret
client builds canonical request
client computes HMAC(secret, canonical_request)
client sends signature metadata
server rebuilds canonical request
server computes expected HMAC
server compares signatures constant-time

The verifier must sign exactly the same bytes/semantics the signer signed.

message integrity
shared-secret authentication
proof that signer had the secret
request tamper detection
replay resistance if timestamp/nonce is included and enforced

confidentiality
public-key non-repudiation
identity proofing
user authentication
authorization
protection if shared secret leaks

HMAC request signing still requires HTTPS.

partner API performs high-value mutations
webhooks must be verified
request body integrity matters
replay must be rejected
client cannot use mTLS/OAuth properly
API key alone is too weak
intermediaries may terminate TLS before app layer

payment callback verification
order submission API
regulatory filing API
partner case transition API
inventory reservation API
banking-style transfer initiation
admin automation over public network

standard OAuth2/OIDC/mTLS already solves the problem
clients cannot implement canonicalization correctly
ecosystem interoperability matters more than custom control
request transformations by proxies are unpredictable

X-API-Key: ak_live_secret

X-Client-Id: client_123
X-Key-Id: key_abc
X-Timestamp: 2026-07-03T04:00:00Z
X-Nonce: 2f6a0e60-1f0a-4e7b-9b53-3d4a7b54a111
X-Content-SHA256: 0e5751c026e543b2e8ab2eb06099daa1...
X-Signed-Headers: host;x-timestamp;x-nonce;x-content-sha256
X-Signature: hmac-sha256=:MEUCIQDp...:

X-Client-Id: partner-acme
X-Key-Id: hmk_live_01HY7Q6MS5RVA4CNZ2Y9Q82F3K
X-Timestamp: 2026-07-03T04:00:00Z
X-Nonce: 01HY7Q7AT5YDSR2E3T7H7F4C5P
X-Content-SHA256: 8b1a9953c4611296a827abf8c47804d7...
X-Signed-Headers: host;x-client-id;x-key-id;x-timestamp;x-nonce;x-content-sha256
X-Signature: hmac-sha256=:base64url(signature):

method
path
query string
host
content hash
timestamp
nonce
client id
key id

payload_hash = SHA-256(empty byte array)

<HTTP_METHOD>\n
<CANONICAL_PATH>\n
<CANONICAL_QUERY>\n
<CANONICAL_HEADERS>\n
<SIGNED_HEADERS>\n
<PAYLOAD_SHA256_HEX>

POST
/api/v1/orders
currency=IDR&externalId=Q-123
host:api.example.com
x-client-id:partner-acme
x-content-sha256:8b1a9953c4611296a827abf8c47804d7...
x-key-id:hmk_live_01HY7Q6MS5RVA4CNZ2Y9Q82F3K
x-nonce:01HY7Q7AT5YDSR2E3T7H7F4C5P
x-timestamp:2026-07-03T04:00:00Z

host;x-client-id;x-content-sha256;x-key-id;x-nonce;x-timestamp
8b1a9953c4611296a827abf8c47804d7...

HMAC-SHA256\n
2026-07-03T04:00:00Z\n
SHA256_HEX(canonical_request)

uppercase HTTP method

post -> POST

use raw path as received by application after trusted proxy normalization
ensure it starts with /
do not collapse path segments unless both client and server do it identically
percent-encode consistently

/api/a/../b
/api/a/%2e%2e/b
/api/orders/%2Fsecret
/api/orders//123

split parameters
percent-decode only according to defined rules
sort by encoded name, then encoded value
preserve repeated keys
represent empty value consistently
join with &

?b=2&a=1&a=0&empty=

a=0&a=1&b=2&empty=

space as + vs %20
empty param vs missing param
repeated parameter order
unicode normalization

lowercase header names
trim leading/trailing spaces
collapse sequential internal whitespace to one space
sort by header name
include only signed headers
end canonical header block with newline

connection
keep-alive
transfer-encoding
upgrade
proxy-authenticate
proxy-authorization
te
trailer

x-forwarded-for
x-forwarded-host
x-forwarded-proto
content-length

payload_hash = lowercase hex SHA-256(request_body_bytes)

{"a":1,"b":2}

{
  "b": 2,
  "a": 1
}

timestamp window
nonce uniqueness
idempotency for mutation

Accept timestamp within ±5 minutes of server time.

Duration skew = Duration.between(requestTimestamp, clock.instant()).abs();
if (skew.compareTo(Duration.ofMinutes(5)) > 0) {
    throw new InvalidSignatureException("stale_signature");
}

Long replay window = attacker has more time to reuse captured requests.

SET hmac_nonce:{key_id}:{nonce} 1 NX EX 300

public final class RedisNonceStore {
    private final RedisClient redis;

    public void reserve(String keyId, String nonce, Duration ttl) {
        String key = "hmac_nonce:" + keyId + ":" + nonce;
        boolean inserted = redis.setIfAbsent(key, "1", ttl);
        if (!inserted) {
            throw new ReplayDetectedException();
        }
    }
}

Idempotency-Key: order-submit-20260703-abc

client_id + endpoint + idempotency_key

Nonce -> security replay
Idempotency key -> business duplicate effect

create table hmac_client (
    id uuid primary key,
    tenant_id uuid not null,
    client_code text not null,
    display_name text not null,
    status text not null check (status in ('active', 'disabled')),
    created_at timestamptz not null default now(),
    unique (tenant_id, client_code)
);

create table hmac_key (
    id uuid primary key,
    client_id uuid not null references hmac_client(id),
    key_id text not null unique,
    secret_ciphertext bytea not null,
    secret_version text not null,
    algorithm text not null default 'HMAC-SHA256',
    status text not null check (status in ('active', 'deprecated', 'revoked', 'expired')),
    created_at timestamptz not null default now(),
    expires_at timestamptz,
    revoked_at timestamptz,
    last_used_at timestamptz
);

KMS/Vault encrypted secret in DB
secret stored in dedicated secret manager by key id
derived verification key stored encrypted
HSM/KMS MAC verification if supported by platform

signature = HMAC(secret, string_to_sign)

k_date = HMAC(secret, yyyyMMdd)
k_service = HMAC(k_date, service_name)
k_signing = HMAC(k_service, "request-signing")
signature = HMAC(k_signing, string_to_sign)

limits impact of derived key exposure
supports date/service scoping
resembles battle-tested SigV4-style separation

more client complexity
more test vectors needed
more clock/date edge cases

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public final class HmacSigner {
    public static byte[] hmacSha256(byte[] key, String message) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(key, "HmacSHA256"));
            return mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        } catch (Exception e) {
            throw new IllegalStateException("Cannot compute HMAC", e);
        }
    }

    public static String base64Url(byte[] bytes) {
        return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
    }
}

import java.security.MessageDigest;

public final class SignatureVerifier {
    public static boolean constantTimeEquals(byte[] expected, byte[] actual) {
        return MessageDigest.isEqual(expected, actual);
    }
}

import java.security.MessageDigest;
import java.util.HexFormat;

public final class PayloadHash {
    public static String sha256Hex(byte[] body) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            return HexFormat.of().formatHex(digest.digest(body));
        } catch (Exception e) {
            throw new IllegalStateException("Cannot compute SHA-256", e);
        }
    }
}

String emptyHash = PayloadHash.sha256Hex(new byte[0]);

import java.util.*;
import java.util.stream.Collectors;

public final class CanonicalRequest {
    public static String build(
            String method,
            String path,
            List<QueryParam> queryParams,
            Map<String, List<String>> headers,
            List<String> signedHeaders,
            String payloadSha256Hex
    ) {
        String canonicalMethod = method.toUpperCase(Locale.ROOT);
        String canonicalPath = normalizePath(path);
        String canonicalQuery = canonicalizeQuery(queryParams);

        List<String> lowerSigned = signedHeaders.stream()
            .map(h -> h.toLowerCase(Locale.ROOT))
            .sorted()
            .toList();

        String canonicalHeaders = lowerSigned.stream()
            .map(name -> name + ":" + canonicalHeaderValue(headers, name) + "\n")
            .collect(Collectors.joining());

        String signedHeaderLine = String.join(";", lowerSigned);

        return canonicalMethod + "\n" +
            canonicalPath + "\n" +
            canonicalQuery + "\n" +
            canonicalHeaders + "\n" +
            signedHeaderLine + "\n" +
            payloadSha256Hex;
    }

    private static String normalizePath(String path) {
        if (path == null || path.isBlank()) {
            return "/";
        }
        if (!path.startsWith("/")) {
            return "/" + path;
        }
        return path;
    }

    private static String canonicalizeQuery(List<QueryParam> params) {
        return params.stream()
            .map(p -> percentEncode(p.name()) + "=" + percentEncode(p.value()))
            .sorted()
            .collect(Collectors.joining("&"));
    }

    private static String canonicalHeaderValue(Map<String, List<String>> headers, String lowerName) {
        List<String> values = headers.entrySet().stream()
            .filter(e -> e.getKey().equalsIgnoreCase(lowerName))
            .flatMap(e -> e.getValue().stream())
            .map(CanonicalRequest::normalizeWhitespace)
            .toList();

        if (values.isEmpty()) {
            throw new MissingSignedHeaderException(lowerName);
        }
        return String.join(",", values);
    }

    private static String normalizeWhitespace(String input) {
        return input.trim().replaceAll("\\s+", " ");
    }

    private static String percentEncode(String s) {
        // Simplified. For production, implement RFC-compatible percent encoding explicitly,
        // test it with golden vectors, and do not rely blindly on form encoders that encode space as '+'.
        return PercentEncoding.strictEncode(s);
    }
}

public record QueryParam(String name, String value) {}

extract signature headers
validate required fields
validate algorithm allowlist
lookup key id
validate key/client status
validate timestamp window
validate nonce uniqueness
validate payload hash
build canonical request
build string to sign
compute expected HMAC
constant-time compare
create authenticated principal
continue authorization

public final class HmacRequestAuthenticator {
    private final HmacKeyRepository keyRepository;
    private final NonceStore nonceStore;
    private final Clock clock;

    public HmacPrincipal authenticate(IncomingSignedRequest request) {
        SignatureHeaders sig = SignatureHeaders.from(request.headers());

        if (!sig.algorithm().equals("hmac-sha256")) {
            throw new InvalidSignatureException();
        }

        HmacKeyRecord key = keyRepository.findActive(sig.keyId())
            .orElseThrow(InvalidSignatureException::new);

        validateTimestamp(sig.timestamp());
        validatePayloadHash(request.bodyBytes(), sig.contentSha256());

        String canonicalRequest = CanonicalRequest.build(
            request.method(),
            request.path(),
            request.queryParams(),
            request.headers(),
            sig.signedHeaders(),
            sig.contentSha256()
        );

        String stringToSign = "HMAC-SHA256\n" +
            sig.timestamp() + "\n" +
            sha256Hex(canonicalRequest.getBytes(StandardCharsets.UTF_8));

        byte[] expected = HmacSigner.hmacSha256(key.secret(), stringToSign);
        byte[] actual = sig.signatureBytes();

        if (!MessageDigest.isEqual(expected, actual)) {
            throw new InvalidSignatureException();
        }

        nonceStore.reserve(key.keyId(), sig.nonce(), Duration.ofMinutes(5));

        return new HmacPrincipal(
            key.clientId(),
            key.tenantId(),
            key.keyId(),
            key.scopes()
        );
    }

    private void validateTimestamp(Instant timestamp) {
        Duration skew = Duration.between(timestamp, clock.instant()).abs();
        if (skew.compareTo(Duration.ofMinutes(5)) > 0) {
            throw new InvalidSignatureException();
        }
    }

    private void validatePayloadHash(byte[] body, String expectedHash) {
        String actual = PayloadHash.sha256Hex(body);
        if (!MessageDigest.isEqual(
                expectedHash.getBytes(StandardCharsets.US_ASCII),
                actual.getBytes(StandardCharsets.US_ASCII))) {
            throw new InvalidSignatureException();
        }
    }
}

Validate timestamp before expensive work.
Reserve nonce after signature passes, or before with careful abuse handling.

public final class HmacAuthenticationFilter extends OncePerRequestFilter {
    private final HmacRequestAuthenticator authenticator;

    public HmacAuthenticationFilter(HmacRequestAuthenticator authenticator) {
        this.authenticator = authenticator;
    }

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain chain
    ) throws ServletException, IOException {
        CachedBodyHttpServletRequest wrapped = new CachedBodyHttpServletRequest(request);

        try {
            if (!hasSignatureHeaders(wrapped)) {
                chain.doFilter(wrapped, response);
                return;
            }

            IncomingSignedRequest signed = IncomingSignedRequest.from(wrapped);
            HmacPrincipal principal = authenticator.authenticate(signed);

            Authentication auth = HmacAuthenticationToken.authenticated(
                principal,
                principal.authorities()
            );
            SecurityContextHolder.getContext().setAuthentication(auth);

            chain.doFilter(wrapped, response);
        } catch (InvalidSignatureException ex) {
            SecurityContextHolder.clearContext();
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.setContentType("application/json");
            response.getWriter().write("{\"error\":\"invalid_signature\"}");
        }
    }
}

Servlet request body can normally be read once.

max signed body size
streaming strategy for large uploads
reject unsupported content types if necessary

@Provider
@Priority(Priorities.AUTHENTICATION)
public final class HmacContainerRequestFilter implements ContainerRequestFilter {
    private final HmacRequestAuthenticator authenticator;

    @Override
    public void filter(ContainerRequestContext ctx) throws IOException {
        if (!hasSignatureHeaders(ctx)) {
            return;
        }

        byte[] body = readAndReplaceEntityStream(ctx);

        try {
            IncomingSignedRequest signed = IncomingSignedRequest.from(ctx, body);
            HmacPrincipal principal = authenticator.authenticate(signed);
            ctx.setSecurityContext(new HmacSecurityContext(principal, ctx.getSecurityContext().isSecure()));
        } catch (InvalidSignatureException ex) {
            ctx.abortWith(Response.status(Response.Status.UNAUTHORIZED)
                .type("application/json")
                .entity("{\"error\":\"invalid_signature\"}")
                .build());
        }
    }

    private byte[] readAndReplaceEntityStream(ContainerRequestContext ctx) throws IOException {
        byte[] body = ctx.getEntityStream().readAllBytes();
        ctx.setEntityStream(new ByteArrayInputStream(body));
        return body;
    }
}

POST /webhooks/payment-provider
X-Webhook-Id: evt_123
X-Timestamp: 2026-07-03T04:00:00Z
X-Signature: hmac-sha256=:...:
Content-Type: application/json

{ "eventId": "evt_123", "type": "payment.succeeded" }

source/provider id
signature
timestamp
event id uniqueness
payload schema
business idempotency

Store webhook event id.
Reject duplicate event id unless idempotent replay with same payload hash.

parse event -> update payment -> verify signature

read raw body -> verify signature -> parse event -> validate schema -> idempotency -> update payment

JSON parser may normalize/modify representation.
Signature must be computed over raw body bytes.

host
x-client-id
x-key-id
x-timestamp
x-nonce
x-content-sha256
content-type for body requests
idempotency-key for mutating requests

user-agent
accept-encoding
connection
content-length
x-forwarded-for unless controlled by trusted gateway
traceparent unless both sides preserve it exactly

application/json
application/json; charset=utf-8

window: ±5 minutes default
error: generic externally
log: timestamp_skew_seconds internally
response header: server time optional for troubleshooting

HTTP/1.1 401 Unauthorized
X-Server-Time: 2026-07-03T04:05:10Z
Content-Type: application/json

{ "error": "invalid_signature" }

Reject HMAC signing for bodies over configured size.
Require client-provided content hash and stream-verify while reading.
Use chunked signing protocol.
Use pre-signed upload URLs.
Use mTLS/OAuth and storage-level checksum instead.

max signed JSON body: e.g. 1MB or 10MB
max webhook body: provider-specific
max canonical header size
max query parameter count
max nonce length
max signed headers count

Canonicalization must be bounded before authentication to avoid CPU/memory DoS.

{ "error": "invalid_signature" }

missing_signature
unsupported_algorithm
unknown_key_id
client_disabled
key_revoked
stale_timestamp
nonce_reused
payload_hash_mismatch
canonical_header_missing
signature_mismatch

expected signature
canonical request string
server-computed string-to-sign
secret id status detail

canonical request hash
signed headers list
server time
payload hash mismatch yes/no

sample method
sample path
sample query
sample headers
sample body
canonical request
string to sign
secret
expected signature

@Test
void buildsCanonicalRequest() {
    String canonical = CanonicalRequest.build(
        "POST",
        "/api/v1/orders",
        List.of(new QueryParam("externalId", "Q-123"), new QueryParam("currency", "IDR")),
        Map.of(
            "Host", List.of("api.example.com"),
            "X-Timestamp", List.of("2026-07-03T04:00:00Z"),
            "X-Nonce", List.of("nonce-123"),
            "X-Content-SHA256", List.of("abc")
        ),
        List.of("host", "x-timestamp", "x-nonce", "x-content-sha256"),
        "abc"
    );

    assertThat(canonical).isEqualTo("""
        POST
        /api/v1/orders
        currency=IDR&externalId=Q-123
        host:api.example.com
        x-content-sha256:abc
        x-nonce:nonce-123
        x-timestamp:2026-07-03T04:00:00Z

        host;x-content-sha256;x-nonce;x-timestamp
        abc""".stripIndent());
}

query parameter reordered
body whitespace changed
timestamp stale
nonce reused
header missing
uppercase header name
duplicate query key
unicode query value
path encoded slash
wrong secret
wrong key id
revoked key

body hashing
canonicalization
secret lookup/decryption
HMAC computation
nonce store round trip
logging/audit

body read/hash for large payloads
KMS/Vault secret retrieval
Redis nonce check under high QPS
DB lookup if not cached

cache decrypted/derived key with short TTL
bound body size
use Redis pipelining if needed
rate limit before expensive verification for obvious invalid traffic
avoid verbose debug logging
precompute lower-case signed headers

single home region for signed endpoint
region-sticky routing per client
global strongly consistent nonce store
short replay window plus idempotency/event id
accept regional replay risk for low-risk endpoint

include region in signature scope and route accordingly
or use global nonce replication
or make mutation idempotent and globally constrained

host
path normalization
query encoding
headers
content-encoding
transfer-encoding
body compression
trailing slash

Verify signature at edge gateway before mutation.
Or ensure gateway forwards raw path/query and signed headers unchanged.
Or define canonicalization based on post-gateway representation and require clients to sign that representation.

Terminate TLS at trusted gateway.
Preserve raw path/query if app verifies.
Reject ambiguous paths.
Do not rewrite signed headers.
Document gateway behavior as part of auth protocol.

X-Signature: hmac-sha256=:...:

hmac-sha256

hmac-sha512

Mac.getInstance(request.getAlgorithm())

if (!algorithm.equals("hmac-sha256")) {
    throw new InvalidSignatureException();
}

multiple active keys per client
key id in header
last used per key
deprecated grace window
revocation
expiry warnings

performance
safe rotation
clear audit
no timing/key oracle

partner -> your API

external provider -> your webhook endpoint

Can this client submit this order?
Can this client access this tenant?
Can this client use this workflow transition?
Can this client refund this payment?

public void authorize(HmacPrincipal client, Order order, String action) {
    if (!client.scopes().contains("order:" + action)) {
        throw new ForbiddenException();
    }
    if (!client.tenantId().equals(order.tenantId())) {
        throw new ForbiddenException();
    }
    if (!order.partnerId().equals(client.clientId())) {
        throw new ForbiddenException();
    }
}

hmac.auth.success.count
hmac.auth.failure.count by reason
hmac.auth.latency
hmac.payload_hash.latency
hmac.nonce.reserve.latency
hmac.nonce.reuse.count
hmac.timestamp.skew.seconds
hmac.signature_mismatch.count
hmac.key.revoked.used.count

{
  "event": "hmac_auth_failed",
  "reason": "nonce_reused",
  "client_id": "partner-acme",
  "key_id": "hmk_live_01HY7Q6MS5RVA4CNZ2Y9Q82F3K",
  "path": "/api/v1/orders",
  "method": "POST",
  "source_ip": "203.0.113.10",
  "timestamp_skew_seconds": 12
}

shared secret
expected signature
raw Authorization/API key equivalent
full body for sensitive requests

canonical request hash
string-to-sign hash
signed headers list

request integrity matters
replay defense matters
partner cannot use mTLS
webhook verification is needed
shared-secret model is acceptable
client implementation can be controlled/tested

service identity is infrastructure-managed
certificate lifecycle is mature
private key protection is stronger than shared secret handling

standard token ecosystem is needed
central authorization server exists
scopes and token lifecycle are already mature

interoperable HTTP message signing is required
multiple components/signatures are needed
standard signature metadata matters

[ ] HMAC-SHA256 allowlisted
[ ] canonical request format documented
[ ] signed headers documented
[ ] payload hash required
[ ] timestamp required
[ ] nonce required
[ ] replay window defined
[ ] key id required
[ ] HTTPS required

[ ] exact byte body hash
[ ] strict header canonicalization
[ ] strict query canonicalization
[ ] constant-time signature compare
[ ] bounded body buffering
[ ] nonce store atomic SET NX
[ ] key status/expiry checked
[ ] algorithm confusion prevented
[ ] generic external errors

[ ] key rotation supported
[ ] revocation supported
[ ] golden vectors published
[ ] client SDK tested
[ ] logs redacted
[ ] signature failure metrics
[ ] replay alerts
[ ] proxy behavior documented
[ ] incident runbook ready

POST /api/v1/tenants/{tenantId}/orders/{orderId}/submit

partner-bound tenant
request body signed
replay rejected within 5 minutes
duplicate business submission idempotent
key rotation without downtime
signature debug support in sandbox

1. required headers
2. canonical request format
3. sample request
4. sample canonical request
5. string-to-sign
6. Java verifier
7. nonce store key design
8. authorization check
9. golden tests
10. incident runbook

same nonce different body
same body different nonce
timestamp 10 minutes old
query params reordered
header casing differs
body whitespace changes
proxy adds trailing slash
client signs compressed body but server sees decompressed body

Both sides must compute the same canonical representation of the same request, then compare signatures without leaking timing or replay surface.

canonicalization discipline
nonce/timestamp replay defense
safe key lifecycle
bounded resource usage
clear error semantics
golden test vectors
proxy-aware deployment