From 8990dac46a6c58977e534d49ca2182ffe97c2359 Mon Sep 17 00:00:00 2001 From: Matt Bullock Date: Thu, 30 Jan 2025 16:05:43 +0000 Subject: [PATCH 1/2] added details around securing MTLS rules --- .../docs/api-shield/security/mtls/configure.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/content/docs/api-shield/security/mtls/configure.mdx b/src/content/docs/api-shield/security/mtls/configure.mdx index b195982229ed9f3..e39ffe4104c6ed1 100644 --- a/src/content/docs/api-shield/security/mtls/configure.mdx +++ b/src/content/docs/api-shield/security/mtls/configure.mdx @@ -42,6 +42,21 @@ The second expression uses the `http.request.uri.path` field, combined with the 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, we recommend validating 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 the following expression: +`not (cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 eq "253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321")` + +To retrieve the SHA-256 fingerprint of your client certificate, run the following OpenSSL command: + +`openssl x509 -noout -fingerprint -sha256 -inform pem -in mtls.crt | cut -d "=" -f 2 | tr -d ':'` + +Example output: + +``` +253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321 +``` + ### Check for revoked certificates To check for [revoked client certificates](/ssl/client-certificates/revoke-client-certificate/), you can either add a new mTLS rule or add a new expression to the [default rule](#expression-builder). To check for revoked certificates, you must use the Expression Builder. From 996f82d98cc4d0835a98402d4f8377a5e8b6f5bb Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Thu, 30 Jan 2025 16:16:53 +0000 Subject: [PATCH 2/2] PCX review --- .../api-shield/security/mtls/configure.mdx | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/src/content/docs/api-shield/security/mtls/configure.mdx b/src/content/docs/api-shield/security/mtls/configure.mdx index e39ffe4104c6ed1..fb0cd3b488ab132 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,20 +39,23 @@ 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. - -For enhanced security, we recommend validating 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. +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. -You can implement this by using the following expression: -`not (cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 eq "253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321")` +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. -To retrieve the SHA-256 fingerprint of your client certificate, run the following OpenSSL command: +You can implement this by using an expression similar to the following: -`openssl x509 -noout -fingerprint -sha256 -inform pem -in mtls.crt | cut -d "=" -f 2 | tr -d ':'` +```txt +not (cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 eq "253E08C1AB67EB7630C61734D377D75D5DCCDE2F6E69986C221D66E848B64321") +``` -Example output: +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 ``` @@ -69,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/). :::