From 0883287bdc43c2fe2f39bf06ad3dc94f9b09e8e7 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 9 May 2025 00:22:26 -0400 Subject: [PATCH 1/3] Add coverage of tls-cipher-suites flag for cockroach start --- src/current/v25.2/authentication.md | 5 +++++ src/current/v25.2/cockroach-start.md | 1 + 2 files changed, 6 insertions(+) diff --git a/src/current/v25.2/authentication.md b/src/current/v25.2/authentication.md index 7155114d1d7..3c482770b2a 100644 --- a/src/current/v25.2/authentication.md +++ b/src/current/v25.2/authentication.md @@ -309,6 +309,11 @@ Let's see how the digital certificate is used in client-server communication: Th CockroachDB supports the [TLS 1.3 and TLS 1.2](https://wikipedia.org/wiki/Transport_Layer_Security) encryption for SQL clients. However, only cipher suites currently recommended by the IETF ([RFC 8447](https://datatracker.ietf.org/doc/html/rfc8447)) are enabled by default. The environment variable `COCKROACH_TLS_ENABLE_OLD_CIPHER_SUITES` can be used to revert to the cipher suite configuration used prior to version 22.2. You should set this environment variable only if you cannot use one of the default cipher suites, but you can use one of the disabled ones. +By default, CockroachDB negotiates TLS 1.3 for client connections when supported by the client. If the client does not support TLS 1.3, the connection will fall back to TLS 1.2. + +To restrict your cluster to only allow connections using specific cipher suites, use the [`--tls-cipher-suites`]({% link {{ page.version.version }}/cockroach-start.md %}#tls-cipher-suites) startup flag with the `cockroach start` command. This setting applies to all incoming SQL, RPC, and HTTP connections. + + The following cipher suites are enabled by default: {% include common/tls-cipher-suites.md list='enabled' %} diff --git a/src/current/v25.2/cockroach-start.md b/src/current/v25.2/cockroach-start.md index 35bbeea853b..a6bfd969984 100644 --- a/src/current/v25.2/cockroach-start.md +++ b/src/current/v25.2/cockroach-start.md @@ -108,6 +108,7 @@ Flag | Description `--external-io-disable-implicit-credentials` | This optional flag disables the use of implicit credentials when accessing external cloud storage services for bulk operations (e.g, [`BACKUP`]({% link {{ page.version.version }}/backup.md %})). `--node-cert-distinguished-name` | A string with a comma separated list of distinguished name (DN) mappings in `{attribute-type}={attribute-value}` format in accordance with [RFC4514](https://www.rfc-editor.org/rfc/rfc4514) for the [`node` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#node-user). If this flag is set, this needs to be an exact match with the DN subject in the client certificate provided for the `node` user. By exact match, we mean that the order of attributes in the argument to this flag must match the order of attributes in the DN subject in the certificate. For more information, see [Certificate-based authentication using multiple values from the X.509 Subject field]({% link {{ page.version.version }}/certificate-based-authentication-using-the-x509-subject-field.md %}). `--root-cert-distinguished-name` | A string with a comma separated list of distinguished name (DN) mappings in `{attribute-type}={attribute-value}` format in accordance with [RFC4514](https://www.rfc-editor.org/rfc/rfc4514) for the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user). If this flag is set, this needs to be an exact match with the DN subject in the client certificate provided for the `root` user. By exact match, we mean that the order of attributes in the argument to this flag must match the order of attributes in the DN subject in the certificate. For more information, see [Certificate-based authentication using multiple values from the X.509 Subject field]({% link {{ page.version.version }}/certificate-based-authentication-using-the-x509-subject-field.md %}). +`--tls-cipher-suites` | A comma-separated list of TLS cipher suites to allow for SQL, RPC, and HTTP connections, limited to those [supported by CockroachDB]({% link {{ page.version.version }}/authentication.md %}#supported-cipher-suites). Connections using disallowed cipher suites will be rejected during the TLS handshake and logged to `cockroach.log`. Example usage: `--tls-cipher-suites=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_128_GCM_SHA256`. ### Locality From 9c6905d29babd438e42ee85bb5d0914652332e80 Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 9 May 2025 00:47:22 -0400 Subject: [PATCH 2/3] Minor clarification --- src/current/v25.2/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v25.2/authentication.md b/src/current/v25.2/authentication.md index 3c482770b2a..fe0a4d4b192 100644 --- a/src/current/v25.2/authentication.md +++ b/src/current/v25.2/authentication.md @@ -261,7 +261,7 @@ For details about when and how to change security certificates without restartin {% include common/tls-bad-cipher-warning.md %} -Authentication refers to the act of verifying the identity of the other party in communication. CockroachDB uses TLS 1.3 digital certificates for inter-node authentication, and your choice of TLS 1.2 and TLS 1.3 certificates for client-node authentication. These authentication methods require a certificate authority (CA) as well as keys and certificates for nodes, clients, and, optionally, the [DB Console](#using-a-public-ca-certificate-to-access-the-db-console-for-a-secure-cluster). +Authentication refers to the act of verifying the identity of the other party in communication. CockroachDB uses TLS 1.3 digital certificates for inter-node authentication, and your choice of TLS 1.2 and TLS 1.3 certificates for client-node authentication (defaulting to TLS 1.3, if supported by the client). These authentication methods require a certificate authority (CA) as well as keys and certificates for nodes, clients, and, optionally, the [DB Console](#using-a-public-ca-certificate-to-access-the-db-console-for-a-secure-cluster). To understand how CockroachDB uses digital certificates, let's first understand what each of these terms means. From 684d7f1f115ca0d8f848426556865dd953d1073b Mon Sep 17 00:00:00 2001 From: mikeCRL Date: Fri, 9 May 2025 01:00:47 -0400 Subject: [PATCH 3/3] Add detail about logs --- src/current/v25.2/cockroach-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v25.2/cockroach-start.md b/src/current/v25.2/cockroach-start.md index a6bfd969984..c7c16cfde01 100644 --- a/src/current/v25.2/cockroach-start.md +++ b/src/current/v25.2/cockroach-start.md @@ -108,7 +108,7 @@ Flag | Description `--external-io-disable-implicit-credentials` | This optional flag disables the use of implicit credentials when accessing external cloud storage services for bulk operations (e.g, [`BACKUP`]({% link {{ page.version.version }}/backup.md %})). `--node-cert-distinguished-name` | A string with a comma separated list of distinguished name (DN) mappings in `{attribute-type}={attribute-value}` format in accordance with [RFC4514](https://www.rfc-editor.org/rfc/rfc4514) for the [`node` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#node-user). If this flag is set, this needs to be an exact match with the DN subject in the client certificate provided for the `node` user. By exact match, we mean that the order of attributes in the argument to this flag must match the order of attributes in the DN subject in the certificate. For more information, see [Certificate-based authentication using multiple values from the X.509 Subject field]({% link {{ page.version.version }}/certificate-based-authentication-using-the-x509-subject-field.md %}). `--root-cert-distinguished-name` | A string with a comma separated list of distinguished name (DN) mappings in `{attribute-type}={attribute-value}` format in accordance with [RFC4514](https://www.rfc-editor.org/rfc/rfc4514) for the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user). If this flag is set, this needs to be an exact match with the DN subject in the client certificate provided for the `root` user. By exact match, we mean that the order of attributes in the argument to this flag must match the order of attributes in the DN subject in the certificate. For more information, see [Certificate-based authentication using multiple values from the X.509 Subject field]({% link {{ page.version.version }}/certificate-based-authentication-using-the-x509-subject-field.md %}). -`--tls-cipher-suites` | A comma-separated list of TLS cipher suites to allow for SQL, RPC, and HTTP connections, limited to those [supported by CockroachDB]({% link {{ page.version.version }}/authentication.md %}#supported-cipher-suites). Connections using disallowed cipher suites will be rejected during the TLS handshake and logged to `cockroach.log`. Example usage: `--tls-cipher-suites=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_128_GCM_SHA256`. +`--tls-cipher-suites` | A comma-separated list of TLS cipher suites to allow for SQL, RPC, and HTTP connections, limited to those [supported by CockroachDB]({% link {{ page.version.version }}/authentication.md %}#supported-cipher-suites). Connections using disallowed cipher suites will be rejected during the TLS handshake and logged to `cockroach.log`. Look for log messages containing: `presented cipher ... not in allowed cipher suite list`.
Example usage: `--tls-cipher-suites=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_AES_128_GCM_SHA256`. ### Locality