Skip to content

Commit f28895c

Browse files
thomasgauvinOxyjun
thomasgauvin
and
Oxyjun
authored
[Hyperdrive] drafting custom cert support for Hyperdrive (#21105)
* [Hyperdrive] drafting custom cert support for Hyperdrive * corrections * wip * add changelog * adjust per comments * add note on wrangler version * add troubleshooting guides for ssl certs * change changelog entry date * Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx * Update src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx * PCX review * added changelog entry --------- Co-authored-by: Jun Lee <[email protected]>
1 parent 00eb1e0 commit f28895c

File tree

5 files changed

+222
-18
lines changed

5 files changed

+222
-18
lines changed

‎src/content/changelog/hyperdrive/2025-04-09-hyperdrive-custom-certificate-support.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Hyperdrive now supports custom TLS/SSL certificates
3+
description: You can now configure custom certificates for secure database connections with Hyperdrive, including both server certificate verification and client certificates
4+
products:
5+
- hyperdrive
6+
date: 2025-04-09T17:00:00Z
7+
---
8+
9+
import { Code } from "~/components";
10+
11+
Hyperdrive now supports more SSL/TLS security options for your database connections:
12+
13+
- Configure Hyperdrive to verify server certificates with `verify-ca` or `verify-full` SSL modes and protect against man-in-the-middle attacks
14+
- Configure Hyperdrive to provide client certificates to the database server to authenticate itself (mTLS) for stronger security beyond username and password
15+
16+
Use the new `wrangler cert` commands to create certificate authority (CA) certificate bundles or client certificate pairs:
17+
18+
```bash
19+
# Create CA certificate bundle
20+
npx wrangler cert upload certificate-authority --ca-cert your-ca-cert.pem --name your-custom-ca-name
21+
22+
# Create client certificate pair
23+
npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name your-client-cert-name
24+
```
25+
26+
Then create a Hyperdrive configuration with the certificates and desired SSL mode:
27+
28+
```bash
29+
npx wrangler hyperdrive create your-hyperdrive-config \
30+
--connection-string="postgres://user:password@hostname:port/database" \
31+
--ca-certificate-id <CA_CERT_ID> \
32+
--mtls-certificate-id <CLIENT_CERT_ID>
33+
--sslmode verify-full
34+
```
35+
36+
Learn more about [configuring SSL/TLS certificates for Hyperdrive](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) to enhance your database security posture.

‎src/content/docs/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
pcx_content_type: concept
3+
title: SSL/TLS certificates
4+
sidebar:
5+
order: 6
6+
badge:
7+
text: Beta
8+
---
9+
10+
import { TabItem, Tabs, Render, WranglerConfig } from "~/components";
11+
12+
Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports:
13+
14+
1. **Server certificates** for TLS (SSL) modes such as `verify-ca` and `verify-full` for increased security. When configured, Hyperdrive will verify that the certificates have been signed by the expected certificate authority (CA) to avoid man-in-the-middle attacks.
15+
2. **Client certificates** for Hyperdrive to authenticate itself to your database with credentials beyond beyond username/password. To properly use client certificates, your database must be configured to verify the client certificates provided by a client, such as Hyperdrive, to allow access to the database.
16+
17+
Hyperdrive can be configured to use only server certificates, only client certificates, or both depending on your security requirements and database configurations.
18+
19+
:::note
20+
21+
Support for server certificates and client certificates is not available for MySQL (beta). Support for server certificates and client certificates is only available for local development using `npx wrangler dev --remote` which runs your Workers and Hyperdrive in Cloudflare's network with local debugging.
22+
23+
:::
24+
25+
## Server certificates (TLS/SSL modes)
26+
27+
Hyperdrive supports 3 common encryption [TLS/SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html) to connect to your database:
28+
29+
- `require` (default): TLS is required for encrypted connectivity and server certificates are validated (based on WebPKI).
30+
- `verify-ca`: Hyperdrive will verify that the database server is trustworthy by verifying that the certificates of the server have been signed by the expected root certificate authority or intermediate certificate authority.
31+
- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname to match a Subject Alternative Name (SAN) present on the certificate.
32+
33+
By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires your database to be configured to accept encrypted connections (with SSL/TLS).
34+
35+
You can configure Hyperdrive to use `verify-ca` and `verify-full` for a more stringent security configuration, which provide additional verification checks of the server's certificates. This helps guard against man-in-the-middle attacks.
36+
37+
To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which has been used to sign the certificate of your database.
38+
39+
### Step 1: Upload your the root certificate authority (CA) certificate
40+
41+
Using Wrangler, you can upload your root certificate authority (CA) certificate:
42+
43+
```bash
44+
# requires Wrangler 4.9.0 or greater
45+
npx wrangler cert upload certificate-authority --ca-cert \<ROUTE_TO_CA_PEM_FILE\>.pem --name \<CUSTOM_NAME_FOR_CA_CERT\>
46+
47+
---
48+
49+
Uploading CA Certificate tmp-cert...
50+
Success! Uploaded CA Certificate <CUSTOM_NAME_FOR_CA_CERT>
51+
ID: <YOUR_ID_FOR_THE_CA_CERTIFICATE>
52+
...
53+
```
54+
55+
:::note
56+
57+
You must use the CA certificate bundle that is for your specific region. You can not use a CA certificate bundle that contains more than one CA certificate, such as a global bundle of CA certificates containing each region's certificate.
58+
59+
:::
60+
61+
### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode
62+
63+
Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use.
64+
65+
<Tabs>
66+
67+
<TabItem label="Wrangler">
68+
69+
Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with the CA certificate and a `verify-full` SSL mode:
70+
71+
```bash
72+
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id <YOUR_CA_CERT_ID> --sslmode verify-full
73+
```
74+
</TabItem>
75+
76+
<TabItem label="Dashboard">
77+
78+
From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates:
79+
80+
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
81+
2. Select **Server certificates**.
82+
3. Specify a SSL mode of **Verify CA** or **Verify full**
83+
4. Select the SSL certificate of the certificate authority (CA) of your database that you have previously uploaded with Wrangler.
84+
85+
</TabItem>
86+
87+
</Tabs>
88+
89+
90+
91+
When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the provided credentials. If the command provides successful results, you have properly configured your Hyperdrive configuration to verify the certificates provided by your database server.
92+
93+
:::note
94+
95+
Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.
96+
97+
:::
98+
99+
## Client certificates
100+
101+
Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves as an additional factor to authenticate clients (in addition to the username and password).
102+
103+
For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`).
104+
105+
### Step 1: Upload your client certificates (mTLS certificates)
106+
107+
Upload your client certificates to be used by Hyperdrive using Wrangler:
108+
109+
```bash
110+
# requires Wrangler 4.9.0 or greater
111+
npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
112+
113+
---
114+
115+
Uploading client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>...
116+
Success! Uploaded client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
117+
ID: <YOUR_ID_FOR_THE_CLIENT_CERTIFICATE_PAIR>
118+
...
119+
```
120+
121+
### Step 2: Create a Hyperdrive configuration
122+
123+
You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler.
124+
125+
126+
<Tabs>
127+
128+
<TabItem label="Wrangler">
129+
130+
Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with using the client certificate pair:
131+
132+
```bash
133+
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --mtls-certificate-id <YOUR_CLIENT_CERT_PAIR_ID>
134+
```
135+
</TabItem>
136+
137+
<TabItem label="Dashboard">
138+
139+
From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates:
140+
141+
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
142+
2. Select **Client certificates**.
143+
3. Select the SSL client certificate and private key pair for Hyperdrive to use during the connection setup with your database server.
144+
145+
</TabItem>
146+
147+
</Tabs>
148+
149+
150+
When Hyperdrive connects to your database, it will provide a client certificate signed with the private key to the database server. This allows the database server to confirm that the client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database to ensures that only Hyperdrive can connect to it.
151+
152+
:::note
153+
154+
Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.
155+
156+
:::

‎src/content/docs/hyperdrive/examples/connect-to-postgres/index.mdx‎

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -72,24 +72,6 @@ Other drivers and ORMs not listed may also be supported: this list is not exhaus
7272

7373
<Render file="nodejs_compat" product="workers" />
7474

75-
## Supported TLS (SSL) modes
76-
77-
Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database:
78-
79-
| Mode | Supported | Details |
80-
| ------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
81-
| `none` | No | Hyperdrive does not support insecure plain text connections. |
82-
| `prefer` | No (use `require`) | Hyperdrive will always use TLS. |
83-
| `require` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). |
84-
| `verify-ca` | Not currently supported in beta | Verifies the server's TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts. |
85-
| `verify-full` | Not currently supported in beta | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. |
86-
87-
:::caution
88-
89-
Hyperdrive does not currently support uploading client CA certificates. In the future, you will be able to provide the client CA to Hyperdrive as part of your database configuration.
90-
91-
:::
92-
9375
## Driver examples
9476

9577
The following examples show you how to:

‎src/content/docs/hyperdrive/observability/troubleshooting.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ Hyperdrive will also issue an empty test query, a `;` in PostgreSQL, to validate
2525
| `2015` | Generic error. | Hyperdrive failed to connect and could not determine a reason. Open a support ticket so Cloudflare can investigate. |
2626
| `2016` | Test query failed. | Confirm that the user Hyperdrive is connecting as has permissions to issue read and write queries to the given database. |
2727

28+
### Failure to connect
29+
30+
Hyperdrive may also emit `Failed to connect to the provided database` when it fails to connect to the database when attempting to create a Hyperdrive configuration. This is possible when the TLS (SSL) certificates are misconfigured. Here is a non-exhaustive table of potential failure to connect errors:
31+
32+
| Error message | Details | Recommended fixes |
33+
| ---------- | -------------------- | --------------------- |
34+
| Server return error and closed connection. | This message occurs when you attempt to connect to a database that has client certificate verification enabled. | Ensure you are configuring your Hyperdrive with [client certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) if your database requires them. |
35+
| TLS handshake failed: cert validation failed. | This message occurs when Hyperdrive has been configured with server CA certificates and is indicating that the certificate provided by the server has not been signed by the expected CA certificate. | Ensure you are using the expected the correct CA certificate for Hyperdrive, or ensure you are connecting to the right database. |
36+
2837
## Connection errors
2938

3039
Hyperdrive may also return errors at runtime. This can happen during initial connection setup, or in response to a query or other wire-protocol command sent by your driver.
@@ -34,6 +43,8 @@ Hyperdrive errors that do not map 1:1 with an error message code [documented by
3443

3544
Hyperdrive may also encounter `ErrorResponse` wire protocol messages sent by your database. Hyperdrive will pass these errors through unchanged when possible.
3645

46+
47+
3748
### Hyperdrive specific errors
3849

3950
| Error Message | Details | Recommended fixes |

‎src/content/docs/hyperdrive/reference/supported-databases-and-features.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,25 @@ The following is a non-exhaustive list of database providers:
3030
| Planetscale | ✅ | All | Planetscale currently runs MySQL 8.x |
3131
| MariaDB | ✅ | All | MySQL-compatible. |
3232

33+
## Supported TLS (SSL) modes
34+
35+
Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database:
36+
37+
| Mode | Supported | Details |
38+
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
39+
| `none` | No | Hyperdrive does not support insecure plain text connections. |
40+
| `prefer` | No (use `require`) | Hyperdrive will always use TLS. |
41+
| `require` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). |
42+
| `verify-ca` | Yes | Verifies the server's TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts. |
43+
| `verify-full` | Yes | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. |
44+
45+
Refer to [SSL/TLS certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) documentation for details on how to configure `verify-ca` or `verify-full` TLS (SSL) modes for Hyperdrive.
46+
:::note
47+
48+
Hyperdrive support for `verify-ca` and `verify-full` is not available for MySQL (beta).
49+
50+
:::
51+
3352
## Supported PostgreSQL authentication modes
3453

3554
Hyperdrive supports the following [authentication modes](https://www.postgresql.org/docs/current/auth-methods.html) for connecting to PostgreSQL databases:

0 commit comments

Comments
 (0)