# Connect to SingleStore Helios using TLS/SSL

> **❗ Important**: If your SQL client connects using the `singlestore_bundle.pem` file with the `--ssl-mode=VERIFY_CA` flag and is unable to establish a connection to SingleStore Helios, download and use the latest `singlestore_bundle.pem` file. To download the file:1) On the Cloud Portal, for your workspace, select **Connect > CLI Client**.
>
> 2) Under **TLS/SSL Certificate**, select **Download**.

## Enable SSL/TLS for a Connection

Most client connections are TLS/SSL-enabled by default, even if no parameters are specified. To ensure a TLS/SSL-enabled connection, use either (or both) of the following options:

* Use a client side flag, such as `--ssl-mode=REQUIRED` in the MySQL/SingleStore clients.
* Use a user created with `REQUIRE SSL`, which enforces SSL on the server side.

## Certificate-Based Authentication

For certificate-based authentication:

1. Configure a CA in the [Cloud Portal](https://portal.singlestore.com):

   1. On the left navigation pane, select **Workspaces**.

   2. Select the three dots for your workspace, and select **Access & Security** from the list.

   3. On the **Security** tab, select **Upload CA Bundle** to upload a CA bundle. The uploaded CA will be used to verify the client certificates when establishing a secure connection.

2. Create a database user with one of the following options in the `CREATE USER` statement to require certificate-based authentication:

   * `REQUIRE X509`: Enables mutual authentication between the client and SingleStore. The user can connect only if the client presents a valid TLS client certificate that is not expired and chains to the CA bundle configured on the server. Connections that do not provide a valid certificate are rejected. For example:
     ```sql
     CREATE USER 's2user'@'%' REQUIRE X509;
     ```
   * `REQUIRE SUBJECT '<subject-dn-string>'`: In addition to extending `REQUIRE X509`, `REQUIRE SUBJECT` checks the subject in the client certificate provided during mTLS connection and enforces that the `Subject DN` in the client certificate must exactly match the configured value. This verifies both trust (via certificate chaining to the CA) and identity (via the `Subject DN` string). For example:
     ```sql
     CREATE USER 's2user'@'%' REQUIRE SUBJECT '/CN=s2user/O=example/C=US';
     ```
     When running `CREATE USER` or `ALTER USER`, specify the `Subject` in [OpenSSL “oneline” format](https://docs.openssl.org/master/man1/openssl-namedisplay-options/). Separate fields, such as `CN`, `O`, `C`, `ST`, and `L`, with a `/`. To generate the `Subject DN` string in OpenSSL "oneline" format, run the following command:
     ```shell
     openssl x509 -in client-cert.pem -noout -subject -nameopt compat
     ```
     If the `openssl` output escapes characters inside a DN value, escape each backslash (`\`) in the output because the value is entered as a SQL string literal. For example, if the `Subject` contains `\+`, replace it with `\\+` in the `CREATE USER` or `ALTER USER` statement. For example:
     ```sql
     CREATE USER 's2user'@'%' REQUIRE SUBJECT '/O=example/CN=Js3g\\+AF\\+/C=US';
     ```
     A `Subject` mismatch can return the same generic certificate verification error as CA-chain issues. To troubleshoot, first verify that the client certificate chains to the CA bundle configured on the server (`REQUIRE X509`), and then verify that the `Subject DN` in the certificate exactly matches the configured `REQUIRE SUBJECT` value.

   Users configured with `REQUIRE X509` or `REQUIRE SUBJECT` can authenticate using their TLS client certificate instead of a database password. This reduces dependency on shared secrets and provides stronger, certificate‑based identity validation. Refer to [CREATE USER](https://docs.singlestore.com/cloud/reference/sql-reference/security-management-commands/create-user.md) for related information.

3. Specify the client certificate and client key while connecting using the `--ssl-cert` and `--ssl-key` client options, respectively.

The `VERIFY_CA` option is not required to use TLS/SSL. However, it can be used to prevent sophisticated man-in-the-middle attacks where a would-be attacker can impersonate a server when SSL is disabled or create a secure connection by impersonating a server using an illegitimate server certificate. If this is a concern, then use offline CA files in any SSL connection (not only SingleStore).

Refer to [SingleStore Helios Endpoints](https://docs.singlestore.com/cloud/connect-to-singlestore/singlestore-helios-endpoints.md) for more information.

Refer to [The SingleStore JDBC Driver](https://docs.singlestore.com/cloud/developer-resources/connect-with-application-development-tools/connect-with-java-jdbc/the-singlestore-jdbc-driver.md) for details on how to connect using JDBC.

## Generate Client Certificates for SingleStore mTLS Connection

Create a client certificate/key pair signed by the CA, and use these files with SingleStore’s `--ssl-cert` and `--ssl-key` options for secure mutual TLS (mTLS) authentication.

The CA certificate (`ca-cert.pem`) must also be trusted by the SingleStore workspace configuration for client authentication. In the Cloud Portal, it must be uploaded in the Security tab of the deployment.

## Prerequisites

Install `OpenSSL`. For example, for Ubuntu/Debian:

```shell
sudo apt-get install openssl -y
```

## Create a Certificate Authority (CA)

If you already have a CA certificate from your organization or another trusted source, skip this step and use the existing CA to sign the client certificate. The generated CA certificates can be used for local testing.

1. Generate a CA private key:
   ```shell
   openssl genrsa -out ca-key.pem 4096
   ```

2. Generate a CA certificate:
   ```shell
   openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 3650 -out ca-cert.pem \ 
   -subj 
   "/C=US/ST=CA/L=SanFrancisco/O=ExampleOrg/OU=IT/CN=Example-CA"
   ```

You now have:

* `ca-key.pem`: The private key for your CA.
* `ca-cert.pem`: The public CA certificate.

Keep the CA key (`ca-key.pem`) private and secure.

Refer to [Certificate-Based Authentication - step 1](https://docs.singlestore.com/#section-id235464539444521.md) for information on how to configure a CA for your workspace.

## Create the Client Certificate and Key

1. Generate the client private key and certificate signing request (CSR) as follows:
   ```shell
   openssl req -newkey rsa:2048 -nodes -keyout client-key.pem -out client-req.pem \ 
   -subj 
   "/C=US/ST=CA/L=SanFrancisco/O=ExampleOrg/OU=Client/CN=client.example.com"
   ```

2. Create a client certificate signed by the CA. The following command uses the CA’s certificate and key to sign the client’s certificate.
   ```shell
   openssl x509 -req -in client-req.pem -CA ca-cert.pem -CAkey ca-key.pem \  
   -CAcreateserial -out client-cert.pem -days 365 -sha256
   ```

You now have:

* `client-key.pem`: Client private key.
* `client-cert.pem`: Client certificate signed by the CA.

## Verify the Certificates

Run the following command to verify that the client certificate is properly signed by the CA:

```shell
openssl verify -CAfile ca-cert.pem client-cert.pem
```

An output similar to the following that the client certificate is properly signed by the CA:

```shell
client-cert.pem: OK
```

## Use the Certificates

When connecting to SingleStore with mTLS, specify the client certificate and key. For example:

```shell
singlestore -u user \	
--ssl-ca=/path/to/ca.pem \	
--tls-version=TLSv1.2 \	
--ssl-cert=/path/to/client-cert.pem \    	
--ssl-key=/path/to/client-key.pem
```

Ensure the SingleStore server is configured with server certificate and key before running this command.

## Configure the SingleStore Helios Connection

Perform the following tasks to configure the MySQL command-line client to connect to SingleStore Helios with a secure connection. SQL clients other than MySQL’s will likely require a different configuration.

1. Download the `singlestore_bundle.pem` [certificate file](https://portal.singlestore.com/organizations/org-id/singlestore-ca-cert) and save it to your MySQL client machine.

2. When connecting to SingleStore Helios, include:

   1. The hostname displayed under the **Endpoint** for your workspace in the [Cloud Portal](https://portal.singlestore.com).

   2. Port, default is `3306`.

   3. The `--default-auth=mysql_native_password` option.

   4. The `--ssl-ca` option, including the path to the `singlestore_bundle.pem` file. This can be done via command-line option, as in `--ssl-ca=/path/singlestore_bundle.pem`, or by setting the appropriate option in the [configuration files for the MySQL command-line client](http://dev.mysql.com/doc/refman/5.7/en/option-files.html). Include the `--ssl-mode=REQUIRED` when using older versions of the MySQL client, even when the `--ssl-ca` option is specified.

   5. The `--ssl-mode=VERIFY_CA` option to verify the certificate.

3. Test the connection to SingleStore Helios. The MySQL client will abort with an error if a secure connection cannot be established. While this is most likely due to a misconfiguration, it can also be due to a would-be attacker manipulating the secure connection to SingleStore Helios.
   ```shell
   mysql -u admin -p -h <endpoint-host> -P <port> \
   --default-auth=mysql_native_password \
   --ssl-ca=./singlestore_bundle.pem \
   --ssl-mode=VERIFY_CA

   ```

4. Verify that a secure connection has been established to SingleStore Helios via the `status` command.
   ```shell
   mysql -u admin -p -h <endpoint-host> -P 3306 \
   --default-auth=mysql_native_password \
   --ssl-ca=./singlestore_bundle.pem -e 'status' \
   --ssl-mode=VERIFY_CA

   ```
   ```output

   mysql  Ver 14.14 Distrib 5.6.19, for osx10.9 (x86_64) using  EditLine wrapper

   Connection id:        13
   Current database:
   Current user:         s2user@yyy.yyy.yyy.yyy
   SSL:                  Cipher in use is AES256-SHA
   Current pager:        stdout
   Using outfile:        ''
   Using delimiter:      ;
   Server version:       5.5.8 MemSQL source distribution (compatible; MySQL Enterprise & MySQL Commercial)
   Protocol version:     10
   Connection:           xxx.xxx.xxx.xxx via TCP/IP
   Server characterset:  utf8
   Db     characterset:  utf8
   Client characterset:  utf8
   Conn.  characterset:  utf8
   TCP port:             3306

   ```

***

Modified at: June 12, 2026

Source: [/cloud/connect-to-singlestore/connect-with-mysql/connect-with-mysql-client/connect-to-singlestore-helios-using-tls-ssl/](https://docs.singlestore.com/cloud/connect-to-singlestore/connect-with-mysql/connect-with-mysql-client/connect-to-singlestore-helios-using-tls-ssl/)

(An index of the documentation is available at /llms.txt)