Skip to content

Commit 251e671

Browse files
thomasgauvinthomasgauvin
committed
corrections
1 parent 67de962 commit 251e671

File tree

4 files changed

+158
-130
lines changed

4 files changed

+158
-130
lines changed

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

Lines changed: 0 additions & 112 deletions
This file was deleted.

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

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
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+
verification of server certificates for TLS (SSL) encryption for increased security. Hyperdrive also supports
14+
using client certificates to authenticate itself to your database for stricter authentication beyond username/password.
15+
16+
:::note
17+
18+
Support for server certificates and client certificates is not available for MySQL (beta).
19+
20+
:::
21+
22+
## Server certificates (TLS/SSL modes)
23+
24+
Hyperdrive supports 3 common encryption [TLS/SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html) to connect to your database:
25+
26+
- `require` (default): TLS is required for encrypted connectivity and server certificates are validated (based on WebPKI).
27+
- `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.
28+
- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate.
29+
30+
By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires
31+
that your database is configured to accept encrypted connections (with SSL/TLS).
32+
33+
You can configure Hyperdrive to use
34+
`verify-ca` and `verify-full` for a more stringent security configuration, which
35+
provide additional verification checks of the server's certificates. This
36+
helps guard against man-in-the-middle attacks.
37+
38+
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
39+
has been used to sign the certificate of your database.
40+
41+
### Step 1: Upload your the root certificate authority (CA) certificate
42+
43+
Using Wrangler, you can upload your root certificate authority (CA) certificate:
44+
45+
```bash
46+
npx wrangler cert upload certificate-authority --ca-cert \<ROUTE_TO_CA_PEM_FILE\>.pem --name \<CUSTOM_NAME_FOR_CA_CERT\>
47+
48+
---
49+
50+
Uploading CA Certificate tmp-cert...
51+
Success! Uploaded CA Certificate \<CUSTOM_NAME_FOR_CA_CERT\>
52+
ID: \<YOUR_ID_FOR_THE_CA_CERTIFICATE\>
53+
...
54+
```
55+
56+
### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode
57+
58+
Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created
59+
certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use.
60+
61+
Using Wrangler, enter the following command in your terminal:
62+
63+
UPDATE WRANGLER
64+
65+
```bash
66+
npx wrangler hyperdrive create \<NAME_OF_HYPERDRIVE_CONFIG\> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id \<YOUR_CA_CERT_ID\>
67+
```
68+
69+
When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the
70+
provided credentials. If the command provides successful results, you have properly configured your Hyperdrive
71+
configuration to verify the certificates provided by your database server.
72+
73+
:::note
74+
75+
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.
76+
77+
:::
78+
79+
## Client certificates
80+
81+
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
82+
as an additional factor to authenticate clients (in addition to the username and password).
83+
84+
For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate
85+
file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`).
86+
87+
### Step 1: Upload your client certificates (mTLS certificates)
88+
89+
Upload your client certificates to be used by Hyperdrive using Wrangler:
90+
91+
```bash
92+
npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
93+
94+
---
95+
96+
Uploading client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>...
97+
Success! Uploaded client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
98+
ID: <YOUR_ID_FOR_THE_CLIENT_CERTIFICATE_PAIR>
99+
...
100+
```
101+
102+
### Step 2: Create a Hyperdrive configuration
103+
104+
You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler.
105+
Using Wrangler, run the following command:
106+
107+
```bash
108+
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --certificate-authority-id <YOUR_CA_CERT_ID> --mtls-certificate-uuid <YOUR_CLIENT_CERT_PAIR_ID>
109+
```

‎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/reference/supported-databases.mdx‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
pcx_content_type: concept
3+
title: Supported databases
4+
sidebar:
5+
order: 2
6+
---
7+
8+
## Database support
9+
10+
Details on which database engines and/or specific database providers are supported are detailed in the following table.
11+
12+
| Database Engine | Supported | Known supported versions | Details |
13+
| --------------- | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
14+
| PostgreSQL | ✅ | `9.0` to `16.x` | Both self-hosted and managed (AWS, Google Cloud, Oracle) instances are supported. |
15+
| Neon | ✅ | All | Neon currently runs Postgres 15.x |
16+
| Supabase | ✅ | All | Supabase currently runs Postgres 15.x |
17+
| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/timescale/) to connect. |
18+
| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/materialize/) to connect. |
19+
| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/cockroachdb/) guide to connect. |
20+
| MySQL | Coming soon | | |
21+
| SQL Server | Not currently supported. | | |
22+
| MongoDB | Not currently supported. | | |
23+
24+
## Supported PostgreSQL authentication modes
25+
26+
Hyperdrive supports the following [authentication modes](https://www.postgresql.org/docs/current/auth-methods.html) for connecting to PostgreSQL databases:
27+
28+
- Password Authentication (`md5`)
29+
- Password Authentication (`password`) (clear-text password)
30+
- SASL Authentication (`SCRAM-SHA-256`)
31+
32+
## Supported TLS (SSL) modes
33+
34+
Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database:
35+
36+
| Mode | Supported | Details |
37+
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
38+
| `none` | No | Hyperdrive does not support insecure plain text connections. |
39+
| `prefer` | No (use `require`) | Hyperdrive will always use TLS. |
40+
| `require` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). |
41+
| `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. |
42+
| `verify-full` | Yes | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. |
43+
44+
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.
45+
:::note
46+
47+
Hyperdrive support for `verify-ca` and `verify-full` is not available for MySQL (beta).
48+
49+
:::

0 commit comments

Comments
 (0)