You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/learning-paths/mtls/concepts/mtls-cloudflare.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,12 +11,12 @@ Some common mTLS use cases are:
11
11
- Protect and verify legitimate API traffic by verifying Client Certificates they provide during TLS/SSL handshakes.
12
12
- Check IoT devices' identity by verifying Client Certificates they provide during TLS/SSL handshakes.
13
13
14
-
There are two main ways to use mTLS at Cloudflare, either by using [API Shield](https://developers.cloudflare.com/api-shield/) or [Cloudflare Access](/cloudflare-one/policies/access/). Below is a non-exhaustive overview table of their differences:
14
+
There are two main ways to use mTLS at Cloudflare, either by using the Application Security offering (optionally including [API Shield](api-shield/)) or [Cloudflare Access](/cloudflare-one/policies/access/). Below is a non-exhaustive overview table of their differences:
| Mainly used for | External Authentication (that is, APIs) | Internal Authentication (that is, employees) |
19
-
| Availability | By default, 100 Client Certificates per Zone are included. For more certificates or [API Shield features](/api-shield/), contact your account team. | Zero Trust Enterprise only feature. |
19
+
| Availability | By default, 100 Client Certificates per Zone are included for free. For more certificates or [API Shield features](/api-shield/), contact your account team. | Zero Trust Enterprise only feature. |
20
20
|[Certificate Authority (CA)](/ssl/concepts/#certificate-authority-ca)| Cloudflare-managed or customer-uploaded (BYO CA). There's a soft-limit of up to [five customer-uploaded CAs](/ssl/client-certificates/byo-ca/#availability). | Customer-uploaded only (BYO CA). There's a soft-limit of up to [50 CAs](/cloudflare-one/account-limits/#access). |
21
21
| Client Certificate Details | Forwarded to the origin server via [Cloudflare API](/ssl/client-certificates/enable-mtls/#cloudflare-api), [Cloudflare Workers](/ssl/client-certificates/enable-mtls/#cloudflare-workers), and [Managed Transforms](/ssl/client-certificates/enable-mtls/#managed-transforms). | Forwarded to the origin server via [Cloudflare API](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-api), [Cloudflare Workers](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#cloudflare-workers), and [Managed Transforms](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#managed-transforms). Client Certificate headers and [Cf-Access-Jwt-Assertion](/cloudflare-one/identity/authorization-cookie/validating-json/) JWT header can be forwarded to the origin server. |
22
22
| Client Certificates Revocation | Use the WAF [Custom Rules](/waf/custom-rules/) to check for [*cf.tls\_client\_auth.cert\_revoked*](/ssl/client-certificates/revoke-client-certificate/), which only applies to Cloudflare-managed CA. <br /><br /> For BYO CAs, it would be the same approach as with Cloudflare Access. | Generate a [Certificate Revocation List (CRL)](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/#create-a-crl) and enforce the revocation in a Cloudflare Worker. |
Copy file name to clipboardExpand all lines: src/content/docs/learning-paths/mtls/mtls-app-security/index.mdx
+9-1Lines changed: 9 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: mTLS with API Shield
2
+
title: mTLS with Application Security
3
3
pcx_content_type: overview
4
4
sidebar:
5
5
order: 1
@@ -22,6 +22,14 @@ By default, mTLS uses Client Certificates issued by a Cloudflare Managed CA. Clo
22
22
23
23
3. Select **Create Certificate** to generate the private key (usually referred to as Private Certificate) and Certificate Signing Request (CSR) with Cloudflare (which includes the Public Certificate), or use your own private key and CSR. Using your own allows you to also [label client certificates](/ssl/client-certificates/label-client-certificate/).
24
24
25
+
To generate and use your own CSR, you can run a command like the following:
Or use a script like this one from [Github](https://github.com/erfianugrah/rootcatest/blob/main/fullgenerator.py).
32
+
25
33
## 2. Install the client certificate
26
34
27
35
In order for a client to utilize the Client Certificate you created, it must be on the devices that you want to use them on. You will want to place them in the same directory as your process / script that targets your APIs / hostnames.
Copy file name to clipboardExpand all lines: src/content/docs/learning-paths/mtls/mtls-app-security/related-features.mdx
+18-6Lines changed: 18 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -66,12 +66,12 @@ The recommended TLS versions for mTLS are:
66
66
Using outdated versions like TLS 1.0 or 1.1 is not recommended due to known vulnerabilities.
67
67
68
68
:::note
69
-
For modern mTLS implementations, Elliptic Curve Cryptography (EC) is recommended because it offers faster handshakes and better performance, uses smaller key sizes result in reduced computational overhead while maintaining strong security, and EC is more scalable for large-scale deployments, such as in cloud-native applications, microservices, and mobile networks. RSA is only recommended if you have legacy systems that cannot support EC or if you require compatibility with systems that only work with RSA.
69
+
For modern mTLS implementations, Elliptic Curve Cryptography (EC) and [modern Cipher Suites](/ssl/edge-certificates/additional-options/cipher-suites/supported-cipher-suites/) are recommended because it offers faster handshakes and better performance, uses smaller key sizes result in reduced computational overhead while maintaining strong security, and EC is more scalable for large-scale deployments, such as in cloud-native applications, microservices, and mobile networks. RSA is only recommended if you have legacy systems that cannot support EC or if you require compatibility with systems that only work with RSA.
70
70
:::
71
71
72
72
## TLS Session Resumption
73
73
74
-
Browsers connecting to a domain with a [wildcard](/dns/manage-dns-records/reference/wildcard-dns-records/)[Edge Certificate](ssl/edge-certificates/) in place, connecting to the same domain's mTLS subdomain could cause a non-authentication event, due to TLS Session Resumption.
74
+
Browsers connecting to a domain with a [wildcard](/dns/manage-dns-records/reference/wildcard-dns-records/)[Edge Certificate](ssl/edge-certificates/) in place, connecting to the same domain's mTLS subdomain could cause a non-authentication event, due to TLS Session Resumption, or also called [Connection Resumption](/speed/optimization/protocol/0-rtt-connection-resumption/).
75
75
76
76
It is generally not recommended to use wildcard certificates.
77
77
@@ -83,7 +83,7 @@ Review the [troubleshooting documentation](/ssl/client-certificates/troubleshoot
83
83
Resumption and renegotiation are essentially opposites. Resumption re-establishes a previous TLS session over a new TCP connection, keeping the same TLS parameters. In contrast, renegotiation updates certain TLS parameters within an existing session, continuing over the same TCP connection.
84
84
:::
85
85
86
-
If you need to use Client Certificates after the TLS handshake via renegotiation, you'll need to use a prior version. This is because TLS 1.3 doesn't support renegotiation.
86
+
If you need to use Client Certificates after the TLS handshake via renegotiation, you'll need to use a prior TLS version than 1.3. This is because TLS 1.3 doesn't support renegotiation.
87
87
88
88
For example, if you're using mTLS and you're restricting requests to certain folders, based on a URL path in the request, rather than all content on your origin server, a TLS renegotiation may be triggered. Connections using TLS 1.3 don't support renegotiation.
89
89
@@ -96,7 +96,7 @@ Contact your account team for more information.
96
96
## WAF for Client Certificates
97
97
98
98
:::note
99
-
[Revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates are not automatically blocked unless you have an active WAF Custom Rule specifically checking for and blocking them. 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 by the customer ([BYO CA](/ssl/client-certificates/byo-ca/)). One can opt for Workers to manage a custom business logic and block revoked Client Certificates. See the [Workers section](placeholder) for more information.
99
+
[Revoked](/api-shield/security/mtls/configure/#check-for-revoked-certificates) Client Certificates are not automatically blocked unless you have an active WAF Custom Rule specifically checking for and blocking them. 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 by the customer ([BYO CA](/ssl/client-certificates/byo-ca/)). One can opt for Workers to manage a custom business logic and block revoked Client Certificates. See the [Workers section](/learning-paths/mtls/mtls-workers/) for more information.
100
100
:::
101
101
102
102
In order to effectively implement mTLS with Cloudflare, it is strongly recommended to properly configure the [Cloudflare WAF](/waf/). Review the available []`cf.tls_*`](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_cipher) dynamic fields.
@@ -119,6 +119,14 @@ Another example WAF Custom Rule with action block, using the [cf.tls_client_auth
119
119
(http.request.uri.path in {"/headers"} and http.host in {"mtls.example.com" "mtls2.example.com"} and not cf.tls_client_auth.cert_verified and cf.tls_client_auth.cert_fingerprint_sha256 ne "ADD_STRING_OF_CLIENT_CERT_SHA256_FINGERPRINT")
120
120
```
121
121
122
+
Here's another example of a WAF custome rule to associate a serial number with a hostname:
123
+
124
+
```txt
125
+
(http.host in {"mtls.example.com" "mtls2.example.com"} and cf.tls_client_auth.cert_serial ne "ADD_STRING_OF_CLIENT_CERT_SERIAL")
126
+
```
127
+
128
+
This expression will check for a specific [Client Certificate serial number](/ruleset-engine/rules-language/fields/dynamic-fields/#cftls_client_authcert_serial) linked to specific hostnames, allowing for more granular control.
129
+
122
130
## Rate Limiting by Client Certificates
123
131
124
132
By enabling [forwarding a certificate](/ssl/client-certificates/enable-mtls/#cloudflare-api) via the Cloudflare API, the first request of an mTLS connection will include the following headers:
@@ -140,8 +148,12 @@ With the same characteristics...
140
148
141
149
## Cloudflare API Shield
142
150
143
-
In addition to mTLS, customers can purchase [API Shield](/api-shield/) features, such as API Discovery, API Routing, Volumetric Abuse Detection, Sequence Mitigation, JWT Validation, and Schema Validation.
151
+
In addition to mTLS, customers can purchase [API Shield](/api-shield/) features, such as API Discovery, API Routing, Volumetric Abuse Detection, Sequence Mitigation, JWT Validation, Schema Validation, and more.
144
152
145
153
## Cloudflare Workers
146
154
147
-
Cloudflare Workers can provide details around the Client Certificate, such as returning information via headers to the client or to the origin server. Learn more in the [mTLS with Workers section](placeholder) below.
155
+
Cloudflare Workers can provide details around the Client Certificate, such as returning information via headers to the client or to the origin server. Learn more in the [mTLS with Workers section](/learning-paths/mtls/mtls-workers/) below.
156
+
157
+
158
+
:::note
159
+
Snippets do not support any [Bindings](/workers/runtime-apis/bindings/) and does not work with mTLS.
Copy file name to clipboardExpand all lines: src/content/docs/learning-paths/mtls/mtls-implementation/index.mdx
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,8 @@ There are different ways to implement mTLS authentication. The most common ones
11
11
12
12
This version of mTLS is for device certificates, primarily focused on the number of IoT devices, not user devices.
13
13
14
+
here we recommend using [mTLS with Application Security](/learning-paths/mtls/mtls-app-security/).
15
+
14
16
## Option 2: mTLS User Authentication
15
17
16
18
When a user wants to establish a secure connection with a server, they present their certificate to the server, which verifies its authenticity. Once the certificate is authenticated, an encrypted connection is established between the user and the server, and all data transmitted between them is encrypted to protect against interception by third parties.
0 commit comments