> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate to CockroachDB Self-Hosted Clusters

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Authentication refers to the act of verifying the identity of the other party in communication. CockroachDB requires TLS 1.3 digital certificates for inter-node authentication and accepts TLS 1.2 and TLS 1.3 certificates for client-node authentication. This document discusses how CockroachDB uses digital certificates and what your options are for configuring user authentication for SQL clients and the DB Console UI. It also offers a [conceptual overview](#background-on-public-key-cryptography-and-digital-certificates) of public key cryptography and digital certificates.

* If you are familiar with public key cryptography and digital certificates, then reading the [Using digital certificates with CockroachDB](#using-digital-certificates-with-cockroachdb) section should be enough.
* If you are unfamiliar with public key cryptography and digital certificates, you might want to skip over to the [conceptual overview](#background-on-public-key-cryptography-and-digital-certificates) first and then come back to the [Using digital certificates with CockroachDB](#using-digital-certificates-with-cockroachdb) section.
* If you want to know how to create CockroachDB security certificates, see <InternalLink path="cockroach-cert">Create Security Certificates</InternalLink>.

## Connecting to a CockroachDB cluster

Users may connect with CockroachDB self-hosted clusters in 2 main ways:

* SQL clients connections, including the CockroachDB CLI client and the <InternalLink path="install-client-drivers">various supported drivers and ORMs</InternalLink>, connect directly to CockroachDB clusters using the <InternalLink path="sql-feature-support">CockroachDB SQL interface</InternalLink>.

* A read-only monitoring service, which provides cluster and database details, and information useful for troubleshooting and performance tuning. Each CockroachDB node also acts as an HTTP server, providing both a <InternalLink path="ui-overview">browser UI DB console</InternalLink> and the <InternalLink path="cluster-api">cluster API</InternalLink>, which provides much of the same information as the DB console, but as a rest API suitable for programmatic access.

## Using digital certificates with CockroachDB

Each CockroachDB node in a secure cluster must have a **node certificate**, which is a TLS 1.3 certificate. This certificate is multi-functional; the same certificate is presented irrespective of whether the node is acting as a server or a client. The nodes use these certificates to establish secure connections with clients and with other nodes. Node certificates have the following requirements:

* The hostname or address (IP address or DNS name) used to reach a node, either directly or through a load balancer, must be listed in the **Common Name** or **Subject Alternative Names** fields of the certificate:

  * The values specified in <InternalLink path="cockroach-start#networking">`--listen-addr`</InternalLink> and <InternalLink path="cockroach-start#networking">`--advertise-addr`</InternalLink> flags, or the node hostname and fully qualified hostname if not specified
  * Any host addresses/names used to reach a specific node
  * Any load balancer addresses/names or DNS aliases through which the node could be reached
  * `localhost` and local address if connections are made through the loopback device on the same host

* CockroachDB must be configured to trust the certificate authority that signed the certificate.

Based on your security setup, you can use the <InternalLink path="cockroach-cert">`cockroach cert` commands</InternalLink>, <InternalLink path="create-security-certificates-openssl">`openssl` commands</InternalLink>, or a <InternalLink path="create-security-certificates-custom-ca">custom CA</InternalLink> to generate all the keys and certificates.

A CockroachDB cluster consists of multiple nodes and clients. The nodes can communicate with each other, with the SQL clients, and the DB Console. In client-node SQL communication and client-UI communication, the node acts as a server, but in inter-node communication, a node may act as a server or a client. Hence authentication in CockroachDB involves:

* Node authentication using [TLS 1.3](https://wikipedia.org/wiki/Transport_Layer_Security) digital certificates.
* Client authentication using TLS digital certificates, passwords, or <InternalLink path="gssapi_authentication">GSSAPI authentication</InternalLink> (for Enterprise users).

<Note>
  If you manage your own Certificate Authority (CA) infrastructure, CockroachDB supports mapping between the Subject field of your [X.509 certificates](https://en.wikipedia.org/wiki/X.509) and SQL <InternalLink path="security-reference/authorization#roles">roles</InternalLink>. For more information, see <InternalLink path="certificate-based-authentication-using-the-x509-subject-field">Certificate-based authentication using multiple values from the X.509 Subject field</InternalLink>.
</Note>

### Node authentication

To set up a secure cluster without using an existing certificate authority, you'll need to generate the following files:

* CA certificate
* Node certificate and key
* (Optional) UI certificate and key

### Client authentication

CockroachDB offers the following methods for client authentication:

* **Client certificate and key authentication**, which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication.

  Example:

  ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  $ cockroach sql --certs-dir=certs --user=jpointsman
  ```

* **Password authentication**, which is available to users and roles who you've created passwords for. Password creation is supported only in secure clusters.

  Example:

  ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  $ cockroach sql --certs-dir=certs --user=jpointsman
  ```

  ```
  # Welcome to the CockroachDB SQL shell.
  # All statements must be terminated by a semicolon.
  # To exit, type: \q.
  #
  Enter password:
  ```

  The client still needs the CA certificate to validate the certificate of the node.

<Tip>
  For improved performance, CockroachDB securely caches password authentication information for users. To limit the authentication latency of users logging into a new session, we recommend that you run bulk `ROLE` operations (<InternalLink path="create-role">`CREATE ROLE`</InternalLink>, <InternalLink path="alter-role">`ALTER ROLE`</InternalLink>, <InternalLink path="drop-role">`DROP ROLE`</InternalLink>) inside a transaction, and run any regularly-scheduled `ROLE` operations together, rather than at different times throughout the day.
</Tip>

* **Password authentication without TLS**

  For deployments where transport security is already handled at the infrastructure level (e.g., IPSec with DMZ), and TLS-based transport security is not possible or not desirable, CockroachDB now supports delegating transport security to the infrastructure with the flag `--accept-sql-without-tls` for <InternalLink path="cockroach-start#security">`cockroach start`</InternalLink>. The `--accept-sql-without-tls` flag is in <InternalLink path="cockroachdb-feature-availability">preview</InternalLink>.

  With this flag, SQL clients can establish a session over TCP without a TLS handshake. They still need to present valid authentication credentials, for example a password in the default configuration. Different authentication schemes can be further configured as per `server.host_based_authentication.configuration`.

  Example:

  ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  $ cockroach sql --user=jpointsman --insecure
  ```

  ```
  # Welcome to the CockroachDB SQL shell.
  # All statements must be terminated by a semicolon.
  # To exit, type: \q.
  #
  Enter password:
  ```

* <InternalLink path="sso-db-console">**Single sign-on authentication to DB Console**</InternalLink>. CockroachDB supports OpenID Connect (OIDC) for authenticating users to the DB Console. You can enable <InternalLink path="sso-db-console#manage-auto-provisioned-users">automatic user provisioning</InternalLink> and <InternalLink path="oidc-authorization">automatic role synchronization</InternalLink> based on group memberships from your identity provider.

* <InternalLink path="sso-sql">**JWT authentication for SQL clients**</InternalLink>. CockroachDB supports JSON Web Token (JWT) authentication for SQL client connections. You can enable <InternalLink path="sso-sql#configure-user-provisioning">automatic user provisioning</InternalLink> and <InternalLink path="jwt-authorization">automatic role synchronization</InternalLink> based on group claims in JWT tokens.

* <InternalLink path="gssapi_authentication">**GSSAPI authentication**</InternalLink>.

### Using `cockroach cert` or `openssl` commands

You can use the <InternalLink path="cockroach-cert">`cockroach cert` commands</InternalLink> or <InternalLink path="create-security-certificates-openssl">`openssl` commands</InternalLink> to create the CA certificate and key, and node and client certificates and keys.

Note that the node certificate created using `cockroach cert` or`openssl` is multi-functional, which means that the same certificate is presented irrespective of whether the node is acting as a server or a client. Thus all nodes must have the following:

* `CN=node` for the special user `node` when the node acts as a client.
* All IP addresses and DNS names for the node must be listed in the `Subject Alternative Name` field for when the node acts as a server. CockroachDB also supports [wildcard notation in DNS names](https://wikipedia.org/wiki/Wildcard_certificate).

**Node key and certificates**

A node must have the following files with file names as specified in the table:

| File name  | File usage                                                                                                                                                                                                                                                                                                                                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`   | CA certificate created using the `cockroach cert` command.                                                                                                                                                                                                                                                                                                                       |
| `node.crt` | Server certificate created using the `cockroach cert` command. <br /><br /> `node.crt` must have `CN=node` and the list of IP addresses and DNS names listed in the `Subject Alternative Name` field. CockroachDB also supports [wildcard notation in DNS names](https://wikipedia.org/wiki/Wildcard_certificate). <br /><br />Must be signed by the CA represented by `ca.crt`. |
| `node.key` | Server key created using the `cockroach cert` command.                                                                                                                                                                                                                                                                                                                           |

**Client key and certificates**

A client must have the following files with file names as specified in the table:

| File name          | File usage                                                                                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ca.crt`           | CA certificate created using the `cockroach cert` command.                                                                                                                                                                                 |
| `client.<user.crt` | Client certificate for `<user` (e.g., `client.root.crt` for user `root`). <br /><br />Each `client.<user.crt` must have `CN=<user`  (e.g., `CN=marc` for `client.marc.crt`) <br /><br /> Must be signed by the CA represented by `ca.crt`. |
| `client.<user.key` | Client key created using the `cockroach cert` command.                                                                                                                                                                                     |

Alternatively, you can use [password authentication](#client-authentication). Remember, the client still needs `ca.crt` for node authentication.

### Using a custom CA

In the previous section, we discussed the scenario where the node and client certificates are signed by the CA created using the `cockroach cert` command. But what if you want to use an external CA, like your organizational CA or a public CA? In that case, our certificates might need some modification. Here’s why:

As mentioned earlier, the node certificate is multi-functional, as in the same certificate is presented irrespective of whether the node is acting as a server or client. To make the certificate multi-functional, the `node.crt` must have `CN=node` and the list of IP addresses and DNS names listed in the`Subject Alternative Names` field.

But some CAs will not sign a certificate containing a `CN` that is not an IP address or domain name. Here's why: The TLS client certificates are used to authenticate the client connecting to a server. Because most client certificates authenticate a user instead of a device, the certificates contain usernames instead of hostnames. This makes it difficult for public CAs to verify the client's identity and hence most public CAs will not sign a client certificate.

To get around this issue, we can split the node key and certificate into two:

* `node.crt` and `node.key`: The node certificate to be presented when the node acts as a server and the corresponding key. `node.crt` must have the list of IP addresses and DNS names listed in the `Subject Alternative Names`.
* `client.node.crt` and `client.node.key`: The node certificate to be presented when the node acts as a client for another node, and the corresponding key. `client.node.crt` must have `CN=node`.

**Node key and certificates**

A node must have the following files with file names as specified in the table:

| File name         | File usage                                                                                                                                                                                                                                                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`          | CA certificate issued by the public CA or your organizational CA.                                                                                                                                                                                                                                                                   |
| `node.crt`        | Node certificate for when node acts as server. <br /><br />All IP addresses and DNS names for the node must be listed in the `Subject Alternative Name`. CockroachDB also supports [wildcard notation in DNS names](https://wikipedia.org/wiki/Wildcard_certificate). <br /><br />Must be signed by the CA represented by `ca.crt`. |
| `node.key`        | Server key corresponding to `node.crt`.                                                                                                                                                                                                                                                                                             |
| `client.node.crt` | Node certificate for when node acts as client. <br /><br />Must have `CN=node`. <br /><br /> Must be signed by the CA represented by `ca.crt`.                                                                                                                                                                                      |
| `client.node.key` | Client key corresponding to `client.node.crt`.                                                                                                                                                                                                                                                                                      |

Optionally, if you have a certificate issued by a public CA to securely access the DB Console, you need to place the certificate and key (`ui.crt` and `ui.key` respectively) in the directory specified by the `--certs-dir` flag.

**Client key and certificates**

A client must have the following files with file names as specified in the table:

| File name          | File usage                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`           | CA certificate issued by the public CA or your organizational CA.                                                                                                                                                                                 |
| `client.<user.crt` | Client certificate for `<user` (e.g., `client.root.crt` for user `root`). <br /><br />Each `client.<user.crt` must have `CN=<user`  (for example, `CN=marc` for `client.marc.crt`). <br /><br />Must be signed by the CA represented by `ca.crt`. |
| `client.<user.key` | Client key corresponding to `client.<user.crt`.                                                                                                                                                                                                   |

Alternatively, you can use [password authentication](#client-authentication). Remember, the client still needs `ca.crt` for node authentication.

### Using a public CA certificate to access the DB Console for a secure cluster

One of the limitations of using `cockroach cert` or `openssl` is that the browsers used to access the DB Console do not trust the node certificates presented to them. Web browsers come preloaded with CA certificates from well-established entities (e.g., GlobalSign and DigiTrust). The CA certificate generated using the `cockroach cert` or `openssl` is not preloaded in the browser. Hence on accessing the DB Console for a secure cluster, you get the “Unsafe page” warning. Now you could add the CA certificate to the browser to avoid the warning, but that is not a recommended practice. Instead, you can use the established CAs (for example, Let’s Encrypt), to create a certificate and key to access the DB Console.

Once you have the UI cert and key, add it to the Certificates directory specified by the `--certs-dir` flag in the `cockroach cert` command. The next time the browser tries to access the UI, the node will present the UI cert instead of the node cert, and you’ll not see the “unsafe site” warning anymore.

**Node key and certificates**

A node must have the following files with file names as specified in the table:

| File name  | File usage                                                                                                                                                                                                                                                                                                                                                                       |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`   | CA certificate created using the `cockroach cert` command.                                                                                                                                                                                                                                                                                                                       |
| `node.crt` | Server certificate created using the `cockroach cert` command. <br /><br /> `node.crt` must have `CN=node` and the list of IP addresses and DNS names listed in the `Subject Alternative Name` field. CockroachDB also supports [wildcard notation in DNS names](https://wikipedia.org/wiki/Wildcard_certificate). <br /><br />Must be signed by the CA represented by `ca.crt`. |
| `node.key` | Server key created using the `cockroach cert` command.                                                                                                                                                                                                                                                                                                                           |
| `ui.crt`   | UI certificate signed by the public CA. `ui.crt` must have the IP addresses and DNS names used to reach the DB Console listed in the `Subject Alternative Name`.                                                                                                                                                                                                                 |
| `ui.key`   | UI key corresponding to `ui.crt`.                                                                                                                                                                                                                                                                                                                                                |

**Client key and certificates**

A client must have the following files with file names as specified in the table:

| File name          | File usage                                                                                                                                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`           | CA certificate created using the `cockroach cert` command.                                                                                                                                                                                         |
| `client.<user.crt` | Client certificate for `<user` (e.g., `client.root.crt` for user `root`). <br /><br />Each `client.<user.crt` must have `CN=<user`  (for example, `CN=marc` for `client.marc.crt`). <br /><br /> Must be signed by the CA represented by `ca.crt`. |
| `client.<user.key` | Client key created using the `cockroach cert` command.                                                                                                                                                                                             |

Alternatively, you can use [password authentication](#client-authentication). Remember, the client still needs `ca.crt` for node authentication.

### Using split CA certificates

<Danger>
  We do not recommend you use split CA certificates unless your organizational security practices mandate you to do so.
</Danger>

You might encounter situations where you need separate CAs to sign and verify node and client certificates. In that case, you would need two CAs and their respective certificates and keys: `ca.crt` and `ca-client.crt`.

**Node key and certificates**

A node must have the following files with file names as specified in the table:

| File name         | File usage                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ca.crt`          | CA certificate to verify node certificates.                                                                                                                                                                                                                                                                                          |
| `ca-client.crt`   | CA certificate to verify client certificates.                                                                                                                                                                                                                                                                                        |
| `node.crt`        | Node certificate for when node acts as server. <br /><br />All IP addresses and DNS names for the node must be listed in the `Subject Alternative Name`. CockroachDB also supports [wildcard notation in DNS names](https://wikipedia.org/wiki/Wildcard_certificate). <br /><br /> Must be signed by the CA represented by `ca.crt`. |
| `node.key`        | Server key corresponding to `node.crt`.                                                                                                                                                                                                                                                                                              |
| `client.node.crt` | Node certificate for when node acts as client. This certificate must be signed by the CA represented by `ca-client.crt`.  <br /><br />Must have `CN=node`.                                                                                                                                                                           |
| `client.node.key` | Client key corresponding to `client.node.crt`.                                                                                                                                                                                                                                                                                       |

Optionally, if you have a certificate issued by a public CA to securely access the DB Console, you need to place the certificate and key (`ui.crt` and `ui.key` respectively) in the directory specified by the `--certs-dir` flag.

**Client key and certificates**

A client must have the following files with file names as specified in the table:

| File name          | File usage                                                                                                                                                                                                                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ca.crt`           | CA certificate.                                                                                                                                                                                                                                          |
| `client.<user.crt` | Client certificate for `<user` (e.g., `client.root.crt` for user `root`). <br /><br />Each `client.<user.crt` must have `CN=<user` (for example, `CN=marc` for `client.marc.crt`). <br /><br /> Must be signed by the CA represented by `ca-client.crt`. |
| `client.<user.key` | Client key corresponding to `client.<user.crt`.                                                                                                                                                                                                          |

## Authentication for cloud storage

See <InternalLink path="cloud-storage-authentication">Use Cloud Storage for Bulk Operations</InternalLink>.

## Authentication best practice

As a security best practice, we recommend that you rotate the node, client, or CA certificates in the following scenarios:

* The node, client, or CA certificates are expiring soon.
* Your organization's compliance policy requires periodical certificate rotation.
* The key (for a node, client, or CA) is compromised.
* You need to modify the contents of a certificate, for example, to add another DNS name or the IP address of a load balancer through which a node can be reached. In this case, you would need to rotate only the node certificates.

For details about when and how to change security certificates without restarting nodes, see <InternalLink path="rotate-certificates">Rotate Security Certificates</InternalLink>.

## Background on public key cryptography and digital certificates

<Note>
  CockroachDB supports the [TLS 1.3 and TLS 1.2](https://wikipedia.org/wiki/Transport_Layer_Security) encryption for SQL clients. Starting in CockroachDB v22.2, only cipher suites currently recommended by the IETF ([RFC 8447](https://datatracker.ietf.org/doc/html/rfc8447)) are enabled by default. In v22.2.4 and above, the environment variable `COCKROACH_TLS_ENABLE_OLD_CIPHER_SUITES` can be used to revert to the cipher suite configuration used in version 22.1. This environment variable is not available in v22.2.0-v22.2.3. 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.

  CockroachDB supports the [TLS 1.3 and TLS 1.2](https://wikipedia.org/wiki/Transport_Layer_Security) encryption for SQL clients. Only cipher suites currently recommended by the IETF ([RFC 8447](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4)) 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 v22.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.

  SQL clients, intermediate proxies, or load balancers that do not support any cipher suites that CockroachDB supports will be unable to connect to CockroachDB clusters. For the full list of supported cipher suites, refer to [Supported cipher suites](https://cockroachlabs.com/docs/stable/authentication#supported-cipher-suites).
</Note>

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.

Consider two people: Amy and Rosa, who want to communicate securely over an insecure computer network. The traditional solution is to use symmetric encryption that involves encrypting and decrypting a plaintext message using a shared key. Amy encrypts her message using the key and sends the encrypted message across the insecure channel. Rosa decrypts the message using the same key and reads the message. This seems like a logical solution until you realize that you need a secure communication channel to send the encryption key.

To solve this problem, cryptographers came up with **asymmetric encryption** to set up a secure communication channel over which an encryption key can be shared.

### Asymmetric encryption

Asymmetric encryption involves a pair of keys instead of a single key. The two keys are called the **public key** and the **private key**. The keys consist of very long numbers linked mathematically in a way such that a message encrypted using a public key can only be decrypted using the private key and vice versa. The message cannot be decrypted using the same key that was used to encrypt the message.

So going back to our example, Amy and Rosa both have their own public-private key pairs. They keep their private keys safe with themselves and publicly distribute their public keys. Now when Amy wants to send a message to Rosa, she requests Rosa's public key, encrypts the message using Rosa’s public key, and sends the encrypted message. Rosa uses her own private key to decrypt the message.

But what if a malicious imposter intercepts the communication? The imposter might pose as Rosa and send their public key instead of Rosa’s. There's no way for Amy to know that the public key she received isn’t Rosa’s, so she would end up using the impostor's public key to encrypt the message and send it to the imposter. The imposter can use their own private key and decrypt and read the message, thus compromising the secure communication channel between Amy and Rosa.

To prevent this security risk, Amy needs to be sure that the public key she received was indeed Rosa’s. That’s where the Certificate Authority (CA) comes into the picture.

### Certificate authority

Certificate authorities are established entities with their own public and private key pairs. They act as a root of trust and verify the identities of the communicating parties and validate their public keys. CAs can be public and paid entities (e.g., GeoTrust and Comodo), or public and free CAs (e.g., Let’s Encrypt), or your own organizational CA (e.g., CockroachDB CA). The CAs' public keys are typically widely distributed (e.g., your browser comes preloaded with certs from popular CAs like DigiCert, GeoTrust, and so on).

Think of the CA as the passport authority of a country. When you want to get your passport as your identity proof, you submit an application to your country's passport authority. The application contains important identifying information about you: your name, address, nationality, date of birth, and so on. The passport authority verifies the information they received and validates your identity. They then issue a document - the passport - that can be presented anywhere in the world to verify your identity. For example, the TSA agent at the airport does not know you and has no reason to trust you are who you say you are. However, they trust the passport authority and thus accept your identity as presented on your passport because it has been verified and issued by the passport authority.

Going back to our example and assuming that we trust the CA, Rosa needs to get her public key verified by the CA. She sends a CSR (Certificate Signing Request) to the CA that contains her public key and relevant identifying information. The CA will verify that it is indeed Rosa’s public key and information, *sign* the CSR using the CA's own private key, and generate a digital document called the **digital certificate**. In our passport analogy, this is Rosa's passport containing verified identifying information about her and trusted by everyone who trusts the CA. The next time Rosa wants to establish her identity, she will present her digital certificate.

### Digital certificate

A public key is shared using a digital certificate signed by a CA using the CA's private key. The digital certificate contains:

* The certificate owner’s public key
* Information about the certificate owner
* The CA's digital signature

### Digital signature

The CA's digital signature works as follows: The certificate contents are put through a mathematical function to create a **hash value**. This hash value is encrypted using the CA's private key to generate the **digital signature**. The digital signature is added to the digital certificate. In our example, the CA adds their digital signature to Rosa's certificate validating her identity and her public key.

As discussed [earlier](#certificate-authority), the CA's public key is widely distributed. In our example, Amy already has the CA's public key. Now when Rosa presents her digital certificate containing her public key, Amy uses the CA's public key to decrypt the digital signature on Rosa's certificate and gets the hash value encoded in the digital signature. Amy also generates the hash value for the certificate on her own. If the hash values match, then Amy can be sure that the certificate and hence the public key it contains indeed belongs to Rosa; otherwise, she can determine that the communication channel has been compromised and refuse further contact.

### How it all works together

Let's see how the digital certificate is used in client-server communication: The client (e.g., a web browser) has the CA certificate (containing the CA's public key). When the client receives a server's certificate signed by the same CA, it can use the CA certificate to verify the server's certificate, thus validating the server's identity, and securely connect to the server. The important thing here is that the client needs to have the CA certificate. If you use your own organizational CA instead of a publicly established CA, you need to make sure you distribute the CA certificate to all the clients.

## Supported cipher suites

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 <InternalLink path="cockroach-start">`--tls-cipher-suites`</InternalLink> 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:

* `TLS_AES_128_GCM_SHA256`,
* `TLS_AES_256_GCM_SHA384`,
* `TLS_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`

The following cipher suites are rejected by default because they are not recommended by the IETF ([RFC 8447](https://datatracker.ietf.org/doc/html/rfc8447)):

* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
* `TLS_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_RSA_WITH_AES_128_CBC_SHA`
* `TLS_RSA_WITH_AES_256_CBC_SHA`

## Supported key exchange mechanisms

For information about supported TLS 1.3 key exchange mechanisms, including post-quantum cryptography support, see <InternalLink path="security-reference/transport-layer-security#post-quantum-cryptography-support-in-cockroachdb">Post-quantum cryptography support in CockroachDB</InternalLink>.

## See also

* <InternalLink path="connection-parameters">Client Connection Parameters</InternalLink>
* <InternalLink path="manual-deployment">Manual Deployment</InternalLink>
* <InternalLink path="kubernetes-overview">Orchestrated Deployment</InternalLink>
* <InternalLink path="secure-a-cluster">Local Deployment</InternalLink>
* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="certificate-based-authentication-using-the-x509-subject-field">Certificate-based authentication using multiple values from the X.509 Subject field</InternalLink>
* <InternalLink path="alter-role#set-the-subject-role-option-for-certificate-based-authentication">`ALTER ROLE ... SUBJECT`</InternalLink>
* <InternalLink path="create-role#set-the-subject-role-option-for-certificate-based-authentication">`CREATE ROLE ... SUBJECT`</InternalLink>
* <InternalLink path="cockroach-cert">`cockroach cert`</InternalLink>
* <InternalLink path="cockroach-auth-session">`cockroach auth-session`</InternalLink>
* <InternalLink path="gssapi_authentication">GSSAPI Authentication</InternalLink>
* <InternalLink path="sso-db-console">Single Sign-on (SSO) for DB Console</InternalLink>
* <InternalLink path="sso-sql">Cluster Single Sign-on (SSO) using JWTs</InternalLink>
* <InternalLink path="jwt-authorization">JWT Authorization</InternalLink>
* <InternalLink path="oidc-authorization">OIDC Authorization</InternalLink>
* <InternalLink path="ldap-authorization">LDAP Authorization</InternalLink>
* <InternalLink path="security-reference/authentication">SQL Authentication</InternalLink>
* <InternalLink path="cloud-storage-authentication">Cloud Storage Authentication</InternalLink>