Integrating secrets token generation with hmac.compare_digest for expiring credentials

Core Pattern: MAC-then-Expiry Verification

Issue a token that carries its own expiry, authenticate it with an HMAC, and verify the MAC before checking the timestamp. This satisfies all three open questions without a database.

Token Structure

token = base64url(payload) + "." + base64url(hmac_sha256(key, base64url(payload)))

Where payload is a JSON object:

{
  "nonce": "",
  "exp": 1731456000,          // Unix epoch seconds
  "kid": "key-2024-11"        // Key identifier for rotation
}

The nonce provides entropy; exp embeds expiry; kid enables key rotation.

Verification Flow

1. Split token on '.' into payload_b64 and sig_b64.
2. Recompute expected_sig = hmac.new(key, payload_b64, 'sha256').digest().
3. Compare with hmac.compare_digest(expected_sig, base64url_decode(sig_b64)).
4. Only if MAC matches, decode payload, parse exp, reject if time.time() > exp.

This order prevents timing oracles on the expiry field.

Key Rotation Across Instances

• Deploy a keys.json mapping kid to base64-encoded secrets (e.g., {"key-2024-11": "...", "key-2024-10": "..."}).
• Issuers always use the newest kid.
• Verifiers accept any kid present in the local keys.json.
• Retire old keys after the longest token TTL plus a clock-skew grace period.

No shared secret store is needed; each instance holds the same static file.

Assumptions & Verification

• Python 3.8+ with secrets, hmac, base64, json, time.
• System clocks synchronized via NTP (max skew < 30 s).
• Token TTL short (e.g., 5–15 min) to limit replay window.

Verify with:

python -c "
import secrets, hmac, base64, json, time
key = b'shared-secret-32-bytes-long!!'
nonce = secrets.token_urlsafe(16)
exp = int(time.time()) + 300
payload = json.dumps({'nonce': nonce, 'exp': exp, 'kid': 'key-1'}, separators=(',', ':')).encode()
payload_b64 = base64.urlsafe_b64encode(payload).rstrip(b'=')
sig = hmac.new(key, payload_b64, 'sha256').digest()
sig_b64 = base64.urlsafe_b64encode(sig).rstrip(b'=')
token = payload_b64 + b'.' + sig_b64
print(token.decode())
"

Then feed the printed token into the verifier before and after exp to confirm MAC-first rejection.

One Diagnostic Detail Needed

What is the maximum acceptable clock skew between your service instances? This determines the grace period added to exp during verification and the safe key-retirement delay.