Cloudflare Docs
Firewall Rules
Cloudflare Docs
Firewall Rules
GitHub icon
Visit Firewall Rules on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Firewall Rules
  3. Common use cases
  4. Require a valid HMAC token

Require a valid HMAC token

Use the Rules language HMAC validation function to validate hash-based message authentication code (HMAC) tokens in a firewall rule expression.

This example uses HMAC token authentication to protect a static private asset hosted by example.com.

The http.request.uri for this example is

/download/cat.jpg?verify=1484063787-9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D

where

  • /download/cat.jpg? represents the path to the asset—the HMAC message to authenticate

  • ?verify= is the separator between the path to the asset and the timestamp when the HMAC token was issued

  • 1484063787 represents the timestamp when the token was issued, expressed as Unix time in seconds

  • 9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D is a base64-encoded MAC

The firewall rule below blocks requests to example.com that do not include a valid HMAC.

The rule supplies the value of the secret key shared between the website and Cloudflare as the first argument to the HMAC validation function, and it uses the value of http.request.uri for the MessageMAC:

ExpressionAction
http.host eq "downloads.example.com" and not is_timed_hmac_valid_v0("secretKey", http.request.uri, 10800, http.request.timestamp.sec,8)Block

The is_timed_hmac_valid_v0() function compares the value of a MAC generated using secretKey to the value encoded in http.request.uri.

If the MAC values match and

http.request.timestamp.sec < (timestamp-issued + 10800)

then the token is valid and the function returns true.

Since the expression in this example uses the not operator, it only matches when the HMAC token is not valid. When the token is not valid, the Cloudflare triggers the action and blocks the request.

​​ Protecting multiple paths using the same secret

You can use the same secret key to protect multiple URI paths.

This is illustrated in the example above, where http.request.uri is passed as the MessageMAC argument to the validation function.

Since http.request.uri includes the path to the asset and that value is extracted for each request, the validation function evaluates all request URIs to downloads.example.com using the same secret key.

Note that while you can use the same secret key to authenticate multiple paths, you must generate an HMAC token for each unique message you want to authenticate.