API Security Deep Dive: HMAC Signatures with Timestamp & Nonce Anti-Replay
This article explains why token authentication alone is insufficient for open APIs and details a three-layer defense using HMAC-SHA256 signatures, timestamps, and nonces to prevent tampering, long-term replay, and short-term replay attacks, with Java implementation examples.
Introduction
The author opens with a story: Xiao A builds an open API, and the first partner immediately finds that request parameters are sent in plaintext. By capturing and replaying requests, they can tamper with amounts (e.g., changing amount=1 to amount=100) and replay yesterday's payment request to cause duplicate charges. Xiao A realizes that login authentication (token/OAuth2) only answers "who you are and what permissions you have," while interface security must answer "has the request been tampered with, is it a replay, and does it come from a legitimate caller holding the appSecret." These are two distinct defense lines.
Concept Definitions
2.1 What Is an Interface Signature
Definition: The caller uses a secret key to compute an HMAC over key request content, producing an unforgeable digest sent with the request. The callee recomputes with the same key and compares. Analogy: a seal on the request — only the key holder can seal; any parameter change breaks the seal.
2.2 Three Lines of Interface Defense
Integrity — Mechanism: Signature (HMAC). Prevents: Tampering — changed parameters break signature.
Freshness — Mechanism: Timestamp + nonce. Prevents: Replay — old or duplicate requests rejected.
Source Legitimacy — Mechanism: appSecret signature. Prevents: Impersonation — without appSecret cannot forge signature.
2.3 Core Terms
HMAC — Hash-based Message Authentication Code — keyed hash for tamper-proofing and source verification.
appSecret — Caller secret key for signing, never transmitted.
timestamp — Request Unix timestamp (ms), limits validity window, prevents long-term replay.
nonce — One-time random number, used once then rejected, prevents short-term replay.
Replay Attack — Capture legitimate request and resend verbatim for duplicate execution.
Timing Attack — Exploit response-time differences to brute-force signature/key character by character.
2.4 Distinction from Related Concepts
Login Auth (token) — Solves: Identity & permissions. Relation: Prerequisite, does not replace signature.
HTTPS — Solves: Transport channel security. Relation: Prevents eavesdropping/tampering in transit, does not stop caller replay or impersonation.
OAuth2 — Solves: Third-party authorization. Relation: Manages granted permissions, does not guarantee request integrity.
Business Idempotency — Solves: Network retry duplicates. Relation: Business-layer safety net, complementary to nonce.
Why Interface Signatures Are Needed
3.1 Why Token Auth Alone Fails
Token has three gaps:
Tampering — Example: Man-in-the-middle changes amount=100 to amount=1; token still valid, backend executes.
Replay — Example: Capture old request and resend; request appears legitimate, backend executes again (duplicate charge).
Impersonation — Example: Leaked token lets anyone call; backend cannot distinguish legitimate caller.
Root cause: access_token only proves "permission to call," not "content unmodified, not replayed, from genuine key holder."
3.2 Three Gaps Filled by Signature Suite
Signature — prevents tampering & impersonation (no appSecret = no valid signature)
Timestamp — prevents long-term replay (expires after 5 minutes)
Nonce — prevents in-window replay (one-time use)
All three correspond to integrity, freshness, source legitimacy — none can be omitted.
3.3 Is Signature Still Needed with HTTPS?
Yes. Common misconception.
Eavesdropping in transit — HTTPS: ✅ Encrypted channel
Man-in-the-middle tampering in transit — HTTPS: ✅ Prevents MITM
Caller replays captured request — HTTPS: ❌ Request is valid; HTTPS does not block
Impersonation after token leak — HTTPS: ❌ Token valid; HTTPS does not verify caller identity
Caller tampers own parameters before sending — HTTPS: ❌ HTTPS prevents MITM, not caller self-modification
Client-side proxy decrypts via trusted CA — HTTPS: ⚠️ HTTPS bypassed if client trusts proxy cert
Key insight: HTTPS secures the transport layer ; interface signature secures the request itself (integrity, freshness, source). Open platforms standardize on HTTPS + OAuth2 + Interface Signature — all three required.
Analogy: Parcel Delivery with Seals
Tamper-evident seal on parcel → Signature (HMAC) — broken seal = tampering; only key holder can seal
Sender holds private seal, receiver verifies → appSecret signature — only key holder can produce
Parcel marked with ship date, expired rejected → Timestamp — reject after 5 minutes
Unique parcel ID, duplicate ID rejected → Nonce — one-time use
Sealed armored truck for transport → HTTPS — encrypted transit
Receiver checks sender ID → Login auth — verifies identity & permissions
Key points:
Signature is "tamper-evident seal": seal broken (parameter changed) → detected; only seal holder (appSecret) can seal.
Timestamp is "expiry date": expired parcels rejected, prevents next-day resend.
Nonce is "parcel tracking number": duplicate number rejected, prevents duplicate delivery.
HTTPS is "sealed container": prevents en-route snooping/tampering, but does not prevent sender from sending duplicate parcels.
Positive & Negative Examples
5.1 Negative: Only Token, No Signature
POST /api/pay
Authorization: Bearer xxx
{"orderId": 1, "amount": 100}Packet capture reveals amount=100; change to amount=1 and resend — backend executes.
Capture full request and replay — duplicate charge.
Token leak allows anyone to call; no verification of genuine caller.
5.2 Negative: Sign Only Body
POST /api/delete
X-Sign: hmac(body)
body: {"id": 1}Attacker modifies parts outside body:
Change URL: /api/query → /api/delete — body unchanged, signature passes.
Change query param: id=1 → id=2 — body unchanged, signature passes.
Change HTTP method: GET → DELETE — body unchanged, signature passes.
5.3 Positive: Full Coverage + Timestamp + Nonce
POST /api/pay?appId=xxx×tamp=1730000000&nonce=abc123
X-Sign: HMAC-SHA256(secret, "POST
/api/pay
appId=xxx&nonce=abc123×tamp=1730000000
{\"orderId\":1,\"amount\":100}")
{"orderId": 1, "amount": 100}Signature covers method + path + sorted query + body + appId + timestamp + nonce — any change breaks signature.
Timestamp > 5 min rejected — blocks long-term replay.
Nonce one-time — blocks in-window replay.
Core 1: Signature Algorithm Design
6.1 Signature Coverage Scope
HTTP_METHOD + "
"
+ URL_PATH + "
"
+ Sorted query params (by key lexicographic) + "
"
+ body + "
"
+ app_id + "
"
+ timestamp + "
"
+ nonceWhy full coverage:
Missing Method → Attack: GET → DELETE, signature still passes
Missing Path → Attack: /query → /delete, signature still passes
Missing Query → Attack: Modify query params, signature still passes
Missing Body → Attack: Modify body, signature still passes
Missing appId → Attack: Swap to another's appId, signature still passes
Why sort query params: Both ends must build identical string; lexicographic key order guarantees consistency.
Why newline delimiters: Prevents concatenation ambiguity. Example: a=1 + b=2 without delimiter could produce a=1b=2 which might equal a=1b + =2. Newlines make boundaries explicit.
6.2 HMAC-SHA256 Algorithm
HMAC principle: Keyed double-hash producing a keyed digest. Without key cannot generate correct digest; cannot reverse key from digest.
/** HMAC-SHA256 signature */
public static String hmacSha256(String secret, String message) {
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
mac.init(keySpec);
byte[] digest = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest); // to hex string
}Why HMAC not bare SHA:
Bare SHA (e.g., SHA256(message)) has no key — anyone can compute, cannot verify source.
HMAC includes key — only appSecret holder can produce correct digest; provides both tamper-proofing and source verification.
6.3 Symmetric vs Asymmetric Signing
Symmetric (HMAC) — Algorithm: HMAC-SHA256. Key: Shared secret. Non-repudiation: ❌. Performance: High. Use Case: Internal, open platforms.
Asymmetric — Algorithm: RSA, ECDSA. Key: Caller private key signs, callee public key verifies. Non-repudiation: ✅. Performance: Low. Use Case: Finance, contracts, non-repudiation required.
Key difference:
HMAC: both parties share secret; sign and verify use same key; fast but no non-repudiation — either party could have generated the signature.
Asymmetric: private key unique to caller; sign with private, verify with public; signer cannot deny, but slower.
Applicability:
Open platforms, internal systems: HMAC (sufficient, efficient, non-repudiation rarely needed).
Finance, contracts, compliance: Asymmetric (non-repudiation mandatory).
6.4 Complete Signature Utility Class
public class SignatureUtil {
/** Build string-to-sign per rules */
public static String buildSignString(String method, String path,
Map<String, String> query, String body,
String appId, long timestamp, String nonce) {
StringBuilder sb = new StringBuilder();
sb.append(method).append('
');
sb.append(path).append('
');
// query sorted by key lexicographic
query.entrySet().stream()
.sorted(Map.Entry.comparingByKey())
.forEach(e -> sb.append(e.getKey()).append('=').append(e.getValue()).append('&'));
if (!query.isEmpty()) sb.deleteCharAt(sb.length() - 1); // remove trailing &
sb.append('
');
sb.append(body == null ? "" : body).append('
');
sb.append(appId).append('
');
sb.append(timestamp).append('
');
sb.append(nonce);
return sb.toString();
}
/** Compute HMAC-SHA256 signature */
public static String sign(String secret, String signString) {
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] digest = mac.doFinal(signString.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest);
} catch (NoSuchAlgorithmException | InvalidKeyException e) {
throw new IllegalStateException("Signing failed", e);
}
}
/** Constant-time signature comparison (prevents timing attacks) */
public static boolean constantTimeEquals(String a, String b) {
if (a == null || b == null) return false;
if (a.length() != b.length()) return false;
int result = 0;
for (int i = 0; i < a.length(); i++) {
result |= a.charAt(i) ^ b.charAt(i);
}
return result == 0;
}
}Core 2: Timestamp Prevents Long-Term Replay
7.1 Timestamp Role
Request carries timestamp (Unix ms). Backend validates: currentTime - timestamp > validityWindow (e.g., 5 min) → reject.
Prevents: Attacker captures request and replays days later; timestamp is days old, exceeds window, rejected.
7.2 Why Timestamp Alone Is Insufficient
Timestamp cannot stop in-window replay — capture and resend within 1 minute; timestamp still valid, backend cannot distinguish. Hence nonce needed for short-term replay.
7.3 Setting Validity Window
Too short (e.g., 10 sec): normal requests rejected under network latency.
Too long (e.g., 1 hour): large replay window, high risk.
Typically 5 minutes : balances latency tolerance and risk.
7.4 Clock Synchronization Issues
Caller and callee clock drift causes valid requests to be rejected as "expired" or "future."
Solutions:
Allow ±60 seconds clock skew during validation.
Require NTP synchronization for critical scenarios.
Issue timestamp from server (e.g., OAuth2 token endpoint returns server time).
/** Timestamp validation (allows 60 sec clock skew) */
private static final long MAX_SKEW = 60_000L; // 60 sec
private static final long VALID_WINDOW = 5 * 60_000L; // 5 min
public void checkTimestamp(long timestamp) {
long now = System.currentTimeMillis();
if (Math.abs(now - timestamp) > MAX_SKEW + VALID_WINDOW) {
throw new ApiException(401, "Request expired");
}
// Also prevent "future" timestamps — timestamp cannot be too far ahead
if (timestamp - now > MAX_SKEW) {
throw new ApiException(401, "Request time anomaly");
}
}Core 3: Nonce Prevents Short-Term Replay
8.1 Nonce Role
Nonce (Number used once) is a unique random per request. Backend records "used nonces"; duplicate → reject.
Prevents: In-window (5 min) replay. Capture and immediate resend — timestamp valid, but nonce already used, rejected.
8.2 Why Nonce Alone Fails
Without timestamp, nonces must be stored permanently (unknown when attacker might replay) → storage explosion. With timestamp, nonces only stored for validity window (5-6 min), auto-expire.
8.3 Timestamp + Nonce Collaboration
Timestamp limits validity window (5 min).
Nonce stored only for validity window (TTL 6 min, slightly longer for seamless overlap).
Timestamp blocks out-of-window replay; nonce blocks in-window replay.
Nonce auto-expires, storage stays bounded.
TTL setting: Nonce TTL slightly longer than timestamp window (e.g., 5 min window → 6 min TTL). In-window replays find nonce still present; out-of-window replays caught by timestamp first.
8.4 SETNX Atomic Operation
Check-then-set concurrency flaw:
Request A: GET nonce → not exist → (has not SET yet)
Request B: GET nonce → not exist → (A not SET, B also sees not exist)
Request A: SET nonce
Request B: SET nonce
Both pass, replay succeedsConcurrent "check then set" has a race window — two identical requests may both see "absent" then both set, allowing replay.
SETNX atomic operation:
if (!nonceBucket.setIfAbsent("nonce:" + nonce, "1", Duration.ofMinutes(6))) {
throw new ApiException(401, "Duplicate request");
}setIfAbsent(Redis SETNX) is atomic — "check + record" in one step. First request succeeds, second fails, eliminating race window.
Critical: Nonce replay protection must use atomic operations; check-then-set has concurrency vulnerability.
8.5 Why Redis Not Database for Nonce Storage
High-frequency read/write — Nonce read/write per request; database cannot handle thousands per second.
Short-lived — Nonce TTL 5-6 min; Redis auto-expiry, no manual cleanup.
Atomic operations — Redis SETNX atomic check+set; database needs unique constraint + transaction, complex & slow.
Performance — Redis sub-millisecond; database millisecond-level; auth path latency-sensitive.
To be continued…
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
