HMAC Specification

Before You Change Anything

Security reference pages are precise for a reason. Treat changes here as trust-boundary changes, not routine config tweaks.

This is the extra signature check that mobile requests must pass before they reach the backend.

In plain language, this page is the rulebook for the signed mobile headers. It defines how the signature is built and what the edge filter checks before the backend is allowed to see the request.

HMAC here means a shared-secret signature. The client proves it knows the shared key by sending a signature that the gateway can recompute and verify.

HMAC Scheme

signature = HMAC-SHA256(secret, token + ":" + timestamp)

Field	Source	Format
secret	Shared key in WASM filter config	Raw string
token	Value of X-Token header	Firebase ID token
timestamp	Value of X-Timestamp header	RFC3339Nano
signature	Value of X-Signature header	Hex-encoded

The mobile HMAC is validated at the edge by the WASM filter.

That means this check happens once, before the request enters the backend. The orchestrator does not repeat the same signature validation.

What The WASM Filter Validates

For requests using the X-Token auth path, the filter performs these checks:

Requests with Authorization: Bearer bypass HMAC validation entirely. JWT validation is handled by Envoy's SecurityPolicy.

1

Step 1

Check the headers

The filter first verifies that x-timestamp, x-signature, x-device-info, and x-version are present. Missing headers return 401.

2

Step 2

Parse the timestamp

The timestamp must parse as RFC3339Nano. Bad input returns 400.

3

Step 3

Check freshness

The request must be within the 2-minute window, with 30 seconds of clock skew tolerance. Stale requests return 403.

4

Step 4

Verify the signature

The filter recomputes the HMAC-SHA256 signature with constant-time comparison. Mismatches return 403.

Requests with Authorization: Bearer bypass HMAC validation entirely. JWT validation is handled by Envoy's SecurityPolicy.

EnvoyExtensionPolicy

The filter is deployed as an EnvoyExtensionPolicy targeting the public gateway.

If that resource name is unfamiliar, the practical meaning is simple: it attaches the custom validation logic to the gateway before traffic is forwarded deeper into the platform.

• HMAC secret injected from the hmac-wasm-config K8s Secret
• failOpen: false
• applied at the gateway edge before requests reach the backend

Environment Skip

In local and test, the filter passes requests through without validation.

That keeps development and automated tests from depending on the full edge stack.

Build And Deploy

Implementation detail: the filter is a proxy-wasm module compiled with TinyGo and run by Envoy at the gateway edge.

The filter source is crawbl-backend/cmd/envoy-auth-filter/main.go.

crawbl app build auth-filter --tag dev --push

Secret Rotation

To rotate the mobile HMAC secret, follow this flow:

1

Step 1

Update the secret

Change crawbl/dev/edge/hmac in AWS Secrets Manager.

2

Step 2

Re-sync ESO

Re-sync the ExternalSecret in envoy-gateway-system.

kubectl annotate externalsecret hmac-config \
  -n envoy-gateway-system force-sync=$(date +%s) --overwrite

3

Step 3

Restart Envoy if needed

Restart the affected Envoy workload only if the new value does not pick up automatically.

🔗 Terms On This Page

If a term below is unfamiliar, open its glossary entry. For the full list, go to Internal Glossary.

• HMAC: A shared-secret signature scheme used to prove a request came from a trusted client.
• Envoy Gateway: The public gateway that receives incoming traffic and routes it to internal services.
• SecurityPolicy: The gateway rule that validates bearer tokens before traffic reaches the backend.
• External Secrets Operator: The controller that copies secrets from AWS Secrets Manager into Kubernetes Secrets.