PQC readiness docs

src/current/cockroachcloud/cmek.md

@@ -16,11 +16,7 @@ You can manage your CMEK keys using one or more of the following services:
 
 To learn more, visit [Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB {{ site.data.products.advanced }}]({% link cockroachcloud/managing-cmek.md %}).
 
-CockroachDB {{ site.data.products.advanced }} includes support for referring to CMEK keys in [HashiCorp Vault Secrets Manager](https://www.vaultproject.io/docs/secrets/key-management), which can distribute keys stored in multiple KMS systems, as long as the actual keys are stored in AWS KMS, GCP KMS, or Azure Key Vault.
-
-{{site.data.alerts.callout_success}}
-You can learn more about the [supported integrations between CockroachDB and HashiCorp Vault]({% link {{site.current_cloud_version}}/hashicorp-integration.md %}).
-{{site.data.alerts.end}}
+CockroachDB {{ site.data.products.advanced }} includes support for referring to CMEK keys in [HashiCorp Vault Secrets Manager](https://www.vaultproject.io/docs/secrets/key-management), which can distribute keys stored in multiple KMS systems, as long as the actual keys are stored in AWS KMS, GCP KMS, or Azure Key Vault. Learn more about the [supported integrations between CockroachDB and HashiCorp Vault]({% link {{site.current_cloud_version}}/hashicorp-integration.md %}).
 
 CockroachDB {{ site.data.products.cloud }} communicates with the KMS platform using the KMS platform's API, and you manage CockroachDB {{ site.data.products.cloud }}'s access to the CMEK key using the KMS platform's identity and access management (IAM) system. The CMEK key is never present in a cluster and CockroachDB {{ site.data.products.cloud }} never has direct access to the CMEK key material. When CMEK is enabled, the CMEK key must be available before the cluster can start and the cluster's newly-written data at rest can be accessed.
 
@@ -170,6 +166,10 @@ CMEK has the following limitations:
 - If you add a new region to a cluster with CMEK enabled, you must configure a CMEK for the new region to protect its data.
 - If the CMEK is not available due to a misconfiguration or a KMS outage, a cluster's managed backups will begin to fail, but no customer notification is sent from CockroachDB {{ site.data.products.cloud }} via email. However, Cockroach Labs support is notified if such a failure occurs.
 
+The following is a limitation associated with Azure Key Vault:
+
+- Azure Key Vault currently uses the RSA-OAEP-256 encryption algorithm for key wrapping, which is not quantum-resistant. Microsoft's Quantum Safe Program includes Azure Key Vault in its roadmap for post-quantum cryptography (PQC) adoption, but no specific timeline has been published.
+
 ## See also
 
 - [Managing Customer-Managed Encryption Keys (CMEK) for CockroachDB {{ site.data.products.advanced }}]({% link cockroachcloud/managing-cmek.md %})

src/current/v26.2/authentication.md

@@ -324,6 +324,16 @@ The following cipher suites are rejected by default because they are not recomme
 
 {% include common/tls-cipher-suites.md list='disabled' %}
 
+## Supported key exchange mechanisms
+
+CockroachDB supports all elliptic curves provided by Go 1.25. 
+
+{% include_cached new-in.html version="v26.2" %} For TLS 1.3 connections specifically, CockroachDB supports `X25519MLKEM768`. This is a hybrid post-quantum cryptography (PQC) algorithm that combines `X25519` (an elliptic curve Diffie-Hellman algorithm) and `ML-KEM-768` (a quantum-resistant key encapsulation mechanism standardized as [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final)).
+
+The hybrid PQC key exchange is enabled by default for TLS 1.3 connections and requires no configuration. During TLS negotiation, the client proposes a preference list of supported curves, which is matched against the server's supported curves. The highest-preference match between client and server is selected.
+
+For more information, refer to [Post-quantum cryptography support in CockroachDB]({% link {{ page.version.version }}/security-reference/transport-layer-security.md %}#post-quantum-cryptography-support-in-cockroachdb).
+
 ## See also
 
 - [Client Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %})

src/current/v26.2/cockroachdb-feature-availability.md

@@ -281,6 +281,10 @@ Buffered Writes enhance transaction throughput and reduce operational cost by mi
 
 For more information, refer to [Buffered writes]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#buffered-writes).
 
+### Post-quantum cryptography support
+
+[Post-quantum cryptography (PQC)]({% link {{ page.version.version }}/security-reference/transport-layer-security.md %}#post-quantum-cryptography-support-in-cockroachdb) support is in preview. For TLS 1.3 connections, CockroachDB uses `X25519MLKEM768` by default, a hybrid PQC algorithm that combines `X25519` (an elliptic curve Diffie-Hellman algorithm) and `ML-KEM-768` (a quantum-resistant key encapsulation mechanism).
+
 ## See Also
 
 - [`SHOW {session variable}`]({% link {{ page.version.version }}/show-vars.md %})

src/current/v26.2/encryption.md

@@ -9,7 +9,7 @@ This page outlines several procedures necessary for managing encryption in Cockr
 
 ## Generating store key files
 
-Cockroach determines which encryption algorithm to use based on the size of the key file. The key file must contain random data making up the key ID (32 bytes) and the actual key (16, 24, or 32 bytes depending on the encryption algorithm).
+Cockroach determines which encryption algorithm to use based on the size of the key file. The key file must contain random data making up the key ID (32 bytes) and the actual key (16, 24, or 32 bytes depending on the encryption algorithm). Review the recommendations for [Encryption at Rest]({% link {{ page.version.version }}/security-reference/encryption.md %}#cockroachdb-self-hosted-clusters) when deciding which algorithm to use.
 
 | Algorithm | Key size | Key file size |
 |-|-|-|

src/current/v26.2/security-reference/encryption.md

@@ -97,6 +97,7 @@ A few other recommendations apply for best security practices:
 - Do not switch from encrypted to plaintext, this leaks data keys. When plaintext is selected, all previously encrypted data must be considered reachable.
 - Do not copy the encrypted files, as the data keys are not easily available.
 - If encryption is desired, start a node with it enabled from the first run, without ever running in plaintext.
+- To maximize post-quantum security, use AES-256 to encrypt data.
 
 {{site.data.alerts.callout_danger}}
 Note that backups taken with the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) statement **are not encrypted** even if Encryption at Rest is enabled. Encryption at Rest only applies to the CockroachDB node's data on the local disk. If you want encrypted backups, you will need to encrypt your backup files using your preferred encryption method.

src/current/v26.2/security-reference/security-overview.md

@@ -98,13 +98,20 @@ docs_area: reference.security
       <td><a href="https://wikipedia.org/wiki/Online_Certificate_Status_Protocol">OCSP</a> certificate revocation protocol</td>
     </tr>
     <tr>
-      <td rowspan="5" ><a href="encryption.html">Encryption</a></td>
+      <td rowspan="6" ><a href="encryption.html">Encryption</a></td>
       <td>✓</td>
       <td>✓</td>
       <td>✓</td>
       <td>✓</td>
       <td>Encryption in transit using TLS 1.3</td>
     </tr>
+    <tr>
+      <td>✓</td>
+      <td>✓</td>
+      <td>✓</td>
+      <td>✓</td>
+      <td><a href="{% link {{ page.version.version }}/security-reference/transport-layer-security.md %}#post-quantum-cryptography-support-in-cockroachdb">Post-quantum cryptography (PQC)</a> key exchange for TLS 1.3</td>
+    </tr>
     <tr>
       <td>✓</td>
       <td>✓</td>

src/current/v26.2/security-reference/transport-layer-security.md

@@ -193,6 +193,27 @@ CockroachDB can be operated entirely without TLS. If a CockroachDB cluster is st
 
 Note that client connections must also be made insecurely, or the connection request will fail. Do this by using `cockroach sql --insecure` on the CLI, or by setting `sslmode=off` in the database connection string.
 
+## Post-quantum cryptography support in CockroachDB
+
+{{site.data.alerts.callout_info}}
+{% include feature-phases/preview.md %}
+{{site.data.alerts.end}}
+
+{% include_cached new-in.html version="v26.2" %} CockroachDB supports post-quantum cryptography (PQC) to protect against threats from quantum computers.
+
+### Key exchange
+
+CockroachDB supports the following key exchange mechanisms for TLS 1.3 connections:
+
+- `X25519MLKEM768` (default): A hybrid PQC algorithm that combines `X25519` (an elliptic curve Diffie-Hellman algorithm) and `ML-KEM-768` (a quantum-resistant key encapsulation mechanism standardized as [FIPS 203](https://csrc.nist.gov/pubs/fips/203/final)).
+- `X25519`: A standalone elliptic curve Diffie-Hellman algorithm.
+
+The hybrid PQC key exchange is enabled by default and requires no configuration. During TLS negotiation, the client proposes a preference list of supported curves, which is matched against the server's supported curves. The highest-preference match between client and server is selected.
+
+### Encryption
+
+To maximize security against quantum attackers, Cockroach Labs recommends that all data in-flight is sent via a TLS 1.3 connection and encrypted with AES-256. This includes the encryption of any [client connections](#tls-in-cockroachdb-sql-client-connections) as well as [data transferred between CockroachDB nodes](#tls-between-cockroachdb-nodes).
+
 ## The CockroachDB certificate Trust Store
 
 A node's [**trust store**](#public-and-private-pkis) is the set of CA public certificates contained in the directory specified by the `--certs-dir` argument when the node is started using [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}). For each CA public certificate in the trust store, the node will accept **all valid certificates signed by the CA or any CA subordinate to it**.

src/current/v26.2/take-and-restore-encrypted-backups.md

@@ -22,6 +22,10 @@ During the [backup process]({% link {{ page.version.version }}/backup-architectu
 
 Note that the encryption algorithm for the random key is determined by the specific cloud provider. [AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks) and [GCP](https://cloud.google.com/kms/docs/algorithms#symmetric_encryption_algorithms) use symmetric encryption with [AES-GCM-256](https://en.wikipedia.org/wiki/Galois/Counter_Mode). [Azure](https://learn.microsoft.com/en-us/azure/security/fundamentals/encryption-atrest) uses asymmetric encryption with RSA-OAEP-256.
 
+{{site.data.alerts.callout_danger}}
+Azure's encryption algorithm, RSA-OAEP-256, is not quantum-resistant. Microsoft's Quantum Safe Program includes Azure Key Vault in its roadmap for post-quantum cryptography (PQC) adoption, but no specific timeline has been published.
+{{site.data.alerts.end}}
+
 During a restore job, CockroachDB retrieves the encrypted random key from the backup metadata and attempts to decrypt it using the KMS URI specified in the [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) statement. Once successfully decrypted, CockroachDB uses this key to decrypt the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) manifest and data files. Similarly, the same KMS URI is required for decrypting the files when listing the backup contents using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}).
 
 When incremental backups are in use, the `kms` option is applied to all backup file URLs. Therefore, each incremental backup must include at least one of the KMS URIs used during the full backup. This subset can consist of any combination of the original URIs, but you cannot introduce new KMS URIs. Likewise, when taking [locality-aware backups](#locality-aware-backup-with-kms-encryption), the specified KMS URI is applied to files across all localities.