Skip to content

added details around securing MTLS rules #19561

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 30, 2025
Merged

added details around securing MTLS rules #19561

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8990dac
added details around securing MTLS rules
mbullock1986 Jan 30, 2025
996f82d
PCX review
pedrosousa Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 21 additions & 4 deletions src/content/docs/api-shield/security/mtls/configure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,9 @@ sidebar:
head:
- tag: title
content: Configure mTLS

---

import { Render } from "~/components"
import { Render } from "~/components";

When you specify API hosts in [mTLS authentication](/api-shield/security/mtls/), Cloudflare will block all requests that do not have a [client certificate](/ssl/client-certificates/) for mTLS authentication.

Expand Down Expand Up @@ -40,7 +39,25 @@ The first expression — `not cf.tls_client_auth.cert_verified` — returns `tru

The second expression uses the `http.request.uri.path` field, combined with the `in` operator, to capture the URI paths your mTLS rule applies to.

Because the [action](/ruleset-engine/rules-language/actions/) for your rule is *Block*, only requests that present a valid client certificate can access the specified hosts.
Because the [action](/ruleset-engine/rules-language/actions/) for your rule is _Block_, only requests that present a valid client certificate can access the specified hosts.

For enhanced security, Cloudflare recommends that you validate the SHA-256 certificate hash alongside the verified certificate field. This ensures that only requests presenting a valid client certificate with a specific fingerprint are allowed.

You can implement this by using an expression similar to the following:

```txt
not (cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 eq "253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321")
```

To obtain the SHA-256 fingerprint of a client certificate stored in the `mtls.crt` file, you can run the following OpenSSL command:

```sh
openssl x509 -noout -fingerprint -sha256 -inform pem -in mtls.crt | cut -d "=" -f 2 | tr -d ':'
```

```txt output
253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321
```

### Check for revoked certificates

Expand All @@ -54,5 +71,5 @@ When a request includes a revoked certificate, the `cf.tls_client_auth.cert_revo

:::caution

This check only applies to client certificates issued by the Cloudflare managed CA. Cloudflare currently does not check certificate revocation lists (CRL) for [CAs that have been uploaded](/ssl/client-certificates/byo-ca/).
This check only applies to client certificates issued by the Cloudflare managed CA. Cloudflare currently does not check certificate revocation lists (CRL) for [CAs that have been uploaded](/ssl/client-certificates/byo-ca/).
:::