diff --git a/src/content/docs/api-shield/security/mtls/configure.mdx b/src/content/docs/api-shield/security/mtls/configure.mdx index b195982229ed9f..fb0cd3b488ab13 100644 --- a/src/content/docs/api-shield/security/mtls/configure.mdx +++ b/src/content/docs/api-shield/security/mtls/configure.mdx @@ -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. @@ -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 @@ -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/). :::