[Hyperdrive] drafting custom cert support for Hyperdrive

Author: thomasgauvin

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

@@ -0,0 +1,112 @@
+---
+pcx_content_type: concept
+title: Custom CA and client certificates
+sidebar:
+  order: 6
+  badge:
+    text: Beta
+---
+
+import { TabItem, Tabs, Render, WranglerConfig } from "~/components";
+
+By default, all Hyperdrive configurations are encrypted with SSL/TLS (`sslmode=require`). Databases commonly support 2 additional [SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html),
+(`verify-ca` and `verify-full`) which allow for a more stringent security between Hyperdrive and the database server.
+
+When using `verify-ca`, Hyperdrive will verify the server certificate when creating a connection, also known as [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES).
+This will configure Hyperdrive to verify that the certificate provided by the database server in the SSL/TLS handshake matches the certificate authority (CA) root certificate.
+This provides an additional security check to prevent man-in-the-middle attacks.
+
+You can also configure Hyperdrive to use `verify-full`.
+In this case, Hyperdrive will do the [client verification of server certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES) and
+provide certificates during the SSL/TLS handshake to allow [server verification of client certificates](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
+This is a feature of databases that allow them to use client certificates as an additional factor to authenticate clients (in addition to the username and password).
+
+The table below explains the various SSL modes of SQL databases:
+
+| SSL Mode      | Password authentication | Encrypted connections | Server certificate verification[^1]  | Client certificates verification[^2]  |
+| ------------- | ----------------------- | ----------------------- | ------------------------------------------ | ------------------------------------------ |
+| `require` (default)     | ✅                      | ✅                      | ❌                                         | ❌                                         |
+| `verify-ca`   | ✅                      | ✅                      | ✅                                         | ❌                                         |
+| `verify-full` | ✅                      |  ✅                      | ✅                                         | ✅                                         |
+
+[^1]: Hyperdrive will verify that the certificates provided by the server have been signed by a certificate authority. This can help prevent man-in-the-middle attacks.
+[^2]: The database is configured to verify both the username/password of Hyperdrive and a client certificate. This provides a second factor for authentication.
+
+## Prerequisites
+
+- An external database with SSL/TLS enabled.
+- The root certificate authority (CA) certificate with which the SSL/TLS certificate of the database has been signed with (for `verify-ca` and `verify-full`).
+- If using `verify-full`, you will need client certificates that have been signed by the same certificate authority (CA) as expected by the database server.
+
+## Client verification of server certificates
+
+Client verification of server certificates means that Hyperdrive will verify that the
+certificate provided by the database server in the [SSL/TLS handshake](https://www.postgresql.org/docs/current/ssl-tcp.html)
+matches the root certificate authority (CA) certificate.
+
+To do this, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an immediate certificate which
+has been used to sign the certificate of your database.
+
+### Step 1: Upload your the root certificate authority (CA) certificate
+
+Using Wrangler, you can upload your root certificate authority (CA) certificate:
+
+```bash
+npx wrangler cert upload certificate-authority --ca-cert \<ROUTE_TO_CA_PEM_FILE\>.pem --name \<CUSTOM_NAME_FOR_CA_CERT\>
+
+---
+
+Uploading CA Certificate tmp-cert...
+Success! Uploaded CA Certificate \<CUSTOM_NAME_FOR_CA_CERT\>
+ID: \<YOUR_ID_FOR_THE_CA_CERTIFICATE\>
+...
+```
+
+### Step 2: Create your Hyperdrive configuration using the CA certificate
+
+Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created
+certificates using either the dashboard or Wrangler.
+Using Wrangler, enter the following command in your terminal:
+
+```bash
+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\>
+```
+
+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.
+
+:::note
+
+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.
+
+:::
+
+## Server verification of client certificates
+
+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`).
+
+### Step 1: Upload your client certificates (mTLS certificates)
+
+Upload your client certificates to be used by Hyperdrive using Wrangler:
+
+```bash
+npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
+
+---
+
+Uploading client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>...
+Success! Uploaded client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
+ID: <YOUR_ID_FOR_THE_CLIENT_CERTIFICATE_PAIR>
+...
+```
+
+### Step 2: Create a Hyperdrive configuration
+
+You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler.
+Using Wrangler, run the following command:
+
+```bash
+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>
+```