---
title: "Encrypting Connections"
component: "tigergraph-server"
version: "4.3"
module: "security"
html_url: "/tigergraph-server/4.3/security/encrypting-connections"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/security/encrypting-connections"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/security/encrypting-connections.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/security/encrypting-connections)

# Encrypting Connections

TigerGraph supports secure data-in-transit communication using the SSL/TLS encryption protocol. This applies to all outward-facing interfaces, including GSQL clients, RESTPP endpoints, and the GraphStudio web interface.

As of TigerGraph 4.3.0, **Mutual TLS (mTLS)** authentication is also supported. mTLS enhances security by ensuring that both the client and server authenticate each other using certificates.

You can configure either server-only SSL/TLS or mutual authentication (mTLS), depending on your security requirements:

* **Server-only SSL/TLS**: Only the server presents a certificate, and clients verify the server's identity.
* **Mutual TLS (mTLS)**: Both the server and client present certificates, and each is authenticated.

## Prerequisites

Before you begin, ensure you have a basic understanding of these concepts:

* What SSL certificates and keys are used for
* How SSL certificate chains work
* What a Distinguished Name (DN) and Subject Alternative Name (SAN) are

Learn more: [SSL/TLS Strong Encryption: An Introduction](https://httpd.apache.org/docs/2.4/ssl/ssl%5Fintro.html)

## Nginx-Based

TigerGraph uses the Nginx web server, so SSL/TLS configuration relies on Nginx's built-in HTTPS support.

For additional reference, see the official Nginx documentation:[Configuring HTTPS Servers (Nginx)](http://nginx.org/en/docs/http/configuring%5Fhttps%5Fservers.html).

## Step 1: Obtain and Install Certificates

You need certificates for your server (always) and for each client (only for mTLS).

### Option A: Use a Certificate from a Trusted Authority

Obtain a certificate from a trusted Certificate Authority (CA). CA vendors provide guidance for requesting and installing certificates.

Configure in TigerGraph:

```console
gadmin config entry ssl
```

### Option B: Create a Self-Signed Certificate

For testing or internal use, you can generate your own certificate:

```console
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout <PRIVATE_KEY_PATH> -out <CERTIFICATE_PATH>
```

Replace `<PRIVATE_KEY_PATH>` with the path to your private key and `<CERTIFICATE_PATH>` with the path to your public certificate.

You will be prompted for certificate fields such as country, locality, organization, and hostname (Common Name).

> [!NOTE]
> The self-signed process below uses the root certificate as the HTTPS server certificate. This is suitable for testing—not for production.

> [!NOTE]
> The Common Name should be your server's hostname, since certificates are bound to domain names.

### Change Certificate Permissions

Secure your certificate files:

```console
chmod 600 <CERTIFICATE_PATH> <PRIVATE_KEY_PATH>
```

## Step 2: Configure SSL with gadmin

After you have your certificates, enable SSL/TLS in TigerGraph:

```console
gadmin config entry ssl
Nginx.SSL.Enable: true
Nginx.SSL.Key: <PRIVATE_KEY_PATH>
Nginx.SSL.Cert: <CERTIFICATE_PATH>
```

TigerGraph accepts only PEM-encoded certificates. If needed, convert using[SSL Converter](https://www.sslshopper.com/ssl-converter.html).

Apply the configuration:

```console
gadmin config apply -y
```

Then restart services:

```console
gadmin restart gsql nginx gui -y
```

## Step 3: Set Up Mutual TLS (mTLS)

Mutual TLS (mTLS) adds two-way authentication, where both the client and server verify each other's identities. To enable mTLS, first complete the server-side SSL/TLS setup (above), then follow these steps.

### Required Parameters

Enable client certificate verification (mTLS):

```console
gadmin config set Nginx.SSL.Client.Verify true
```

### Upload or Specify Client CA Certificates

Provide a list of Certificate Authorities (CAs) trusted to authenticate client certificates.

You can do this in one of two ways:

**Admin Portal Method:**Upload client CA certificates through the Admin Portal. See [Admin Portal: Nginx Configuration](https://www.tigergraph.com/docs/gui/4.3/admin-portal/components/nginx.md).

**gadmin Method:**

```console
gadmin config set Nginx.SSL.Client.Cert <CLIENT_CA_CERT_PATH>
```

Replace `<CLIENT_CA_CERT_PATH>` with the full path to your PEM-encoded client CA certificate file, for example:`/etc/tigergraph/client_ca_cert.pem`.

### Optional Parameters

The following parameters are optional and add deeper verification checks on client certificates. Even if you skip them, mTLS will still validate the client certificate's signature.

**DN Attribute Validation**

```console
gadmin config set Nginx.SSL.Client.DN.Verify true
gadmin config set Nginx.SSL.Client.DN.Country '["US", "UK"]'
gadmin config set Nginx.SSL.Client.DN.Organization '["MyOrg"]'
gadmin config set Nginx.SSL.Client.DN.CommonName '["client1.example.com"]'
```

**SAN Attribute Validation**

```console
gadmin config set Nginx.SSL.Client.SAN.Verify true
gadmin config set Nginx.SSL.Client.SAN.DNS '["clientdomain.com"]'
gadmin config set Nginx.SSL.Client.SAN.Email '["user@email.com"]'
gadmin config set Nginx.SSL.Client.SAN.URI '["spiffe://client/uri"]'
gadmin config set Nginx.SSL.Client.SAN.IP '["192.168.1.1"]'
gadmin config set Nginx.SSL.Client.SAN.RID '["1.2.3.4.5"]'
```

**OCSP (Certificate Revocation) Verification**

```console
gadmin config set Nginx.SSL.Client.OCSP.Verify true
gadmin config set Nginx.SSL.Client.OCSP.Resolver "8.8.8.8,8.8.4.4"
gadmin config set Nginx.SSL.Client.OCSP.Responder "http://ocsp.myca.com"
```

> [!NOTE]
> Each of the above parameters provides an extra layer of verification. For basic testing, you can leave them unset and rely only on the client certificate signature.

## Testing Your Connection

To test SSL/TLS or mTLS:

**Server-only TLS**: You only need a CA certificate to verify the server.

```console
curl --cacert <CERTIFICATE_PATH> https://localhost:14240
```

**Mutual TLS (mTLS)**: You need both server and client certificates.

```console
curl --cert <CLIENT_CERT_PATH> --key <CLIENT_KEY_PATH> --cacert <CLIENT_CA_CERT_PATH> https://localhost:14240
```

Replace placeholders:

* `<CERTIFICATE_PATH>` — server's public certificate
* `<CLIENT_CERT_PATH>` — client's certificate
* `<CLIENT_KEY_PATH>` — client's private key
* `<CLIENT_CA_CERT_PATH>` — client CA certificate (PEM)

If the validation fails, you will receive a `403 Forbidden` response.

## Troubleshooting

| Issue | Description | Resolution |
| --- | --- | --- |
| **403 Forbidden** | DN or SAN mismatch | Ensure the client certificate attributes match the configured validation rules. |
| **Missing client certificate** | Client did not present a certificate | Ensure the client provides a valid certificate and key. |
| **OCSP verification failure** | Cannot validate certificate status | Check OCSP configuration or disable temporarily for testing. |

Check logs:

* Nginx logs record HTTP 403 errors.
* TigerGraph logs provide detailed handshake error information.

## Limitations

If you use mTLS, note these limitations in TigerGraph 4.3.0:

1. Internal clients on the same TigerGraph server node may connect without mTLS.
2. **pyTigerGraph** does not support mTLS.

## Quick Reference: mTLS Parameters

| Parameter | Purpose |
| --- | --- |
| Nginx.SSL.Client.Verify | Enable client certificate verification (mTLS) |
| Nginx.SSL.Client.Cert | Path to trusted CA file for client certificates |
| Nginx.SSL.Client.DN.\* | DN attribute checks (Country, Organization, CommonName) |
| Nginx.SSL.Client.SAN.\* | SAN attribute checks (DNS, Email, URI, IP, RID) |
| Nginx.SSL.Client.OCSP.Verify | Enable OCSP for real-time revocation checking |
| Nginx.SSL.Client.OCSP.Resolver | DNS resolvers for OCSP queries |
| Nginx.SSL.Client.OCSP.Responder | Custom OCSP responder URL |

## Configuring TLS for Internal Kafka

This feature introduces SSL/TLS encryption for TigerGraph's internal Kafka. It addresses the lack of native encryption and authentication for data in transit within the TigerGraph cluster.

### Basic Setup Workflow

1. set certificate-chain in PEM format  
```bash  
gadmin config set Kafka.Security.SSL.Certificate @/path/to/cert.pem  
```
2. set private-key in PEM format  
```bash  
gadmin config set Kafka.Security.SSL.PrivateKey @/path/to/prikey.pem  
```
3. set passphrase for private key. Java keystore requires passphrase.  
```bash  
gadmin config set Kafka.Security.SSL.Passphrase @/path/to/passphrase  
```
4. Enable SSL for Kafka to ensure encrypted communication.  
```bash  
gadmin config set Kafka.Security.SSL.Enable true  
```
5. Apply the updated Kafka security configurations to the system.  
```bash  
gadmin config apply -y  
```
6. Restart Kafka and the corresponding client services.  
```bash  
gadmin restart all -y  
```

### Configuration Reference

| Parameter | Description | Default Value |
| --- | --- | --- |
| Kafka.Security.SSL.Certificate | Kafka broker certificate in PEM format |  |
| Kafka.Security.SSL.Enable | Enable Kafka TLS encryption | false |
| Kafka.Security.SSL.ExternalListener.ClientAuth | Enable SSL client authentication for external listeners, the root certificate of Kafka.Security.SSL.Certificate will be used to trust client certificate. | false |
| Kafka.Security.SSL.Passphrase | Kafka broker private key passphrase. Should not be empty. |  |
| Kafka.Security.SSL.Port | Kafka SSL listening port | 30001 |
| Kafka.Security.SSL.PrivateKey | Kafka broker private key in PEM format |  |
| Kafka.Security.ClientConf.ProtocolForAllClients | If specified, all clients must use the specified protocol. Legal values include: empty-string (not specified), ssl, plaintext. If it's not specified, clients can choose a preferred protocol |  |
| Kafka.Security.ClientConf.EngineProtocol | It is the protocol for engine-kafka communication. The value can be an empty-string or "plaintext", "ssl". It's overridden by Kafka.Security.ClientConf.ProtocolForAllClients. |  |
| Kafka.Security.ClientConf.InfraProtocol | It is the protocol for infra-kafka communication. The value can be an empty-string or "plaintext", "ssl". It's overridden by Kafka.Security.ClientConf.ProtocolForAllClients. |  |
| Kafka.Security.ClientConf.InterBrokerProtocol | It is the protocol for inter-broker communication. The value can be an empty-string or "plaintext", "ssl". It's overridden by Kafka.Security.ClientConf.ProtocolForAllClients. |  |

## TLS Versions and Cipher Suites

TigerGraph's Nginx supports TLS 1.2 and TLS 1.3\. By default, TLS 1.3 is used for both client-facing and internal cluster communication, offering stronger security and faster connection establishment.

### TLS 1.2 Cipher Suites (configured in template)

* `ECDHE-ECDSA-AES128-GCM-SHA256`
* `ECDHE-RSA-AES128-GCM-SHA256`
* `ECDHE-ECDSA-AES256-GCM-SHA384`
* `ECDHE-RSA-AES256-GCM-SHA384`
* `ECDHE-ECDSA-CHACHA20-POLY1305`
* `ECDHE-RSA-CHACHA20-POLY1305`

### TLS 1.3 Cipher Suites

TLS 1.3 cipher suites are not explicitly configured and use OpenSSL's built-in defaults:

* `TLS_AES_256_GCM_SHA384`
* `TLS_CHACHA20_POLY1305_SHA256`
* `TLS_AES_128_GCM_SHA256`

### Post-Quantum Hybrid TLS Key Exchange

In 4.3, when SSL is enabled, TigerGraph's Nginx supports the TLS 1.3 hybrid post-quantum key exchange group `X25519MLKEM768`. This group combines classical X25519 with ML-KEM-768 (NIST FIPS 203). It is enabled by default and requires no configuration.

This applies to all HTTPS endpoints served by TigerGraph's Nginx, including the RESTPP API, GSQL HTTP endpoints, GraphStudio, Admin Portal, and other web applications on the Nginx ports (by default, `14240` and `9000`).

#### Requirements

* SSL must be enabled (`Nginx.SSL.Enable=true`).
* The client must support `X25519MLKEM768` over TLS 1.3\. For example, OpenSSL 3.5 or later, or Chrome and Edge 131 or later.
* TigerGraph bundles OpenSSL 3.5 inside Nginx, so this behavior does not depend on the OpenSSL version installed on the host.

#### Negotiation behavior

| Client | Key exchange used |
| --- | --- |
| TLS 1.3 client that supports `X25519MLKEM768` | Hybrid post-quantum (`X25519MLKEM768`) |
| TLS 1.3 client without post-quantum support | Classical (for example, X25519). The connection works as before. |
| TLS 1.2 client | Classical ECDHE. The connection works as before. |

#### Verify post-quantum key exchange

Run the following command from a machine with an OpenSSL 3.5 or later client:

```console
openssl s_client -connect <host>:14240 -tls1_3 -groups X25519MLKEM768 </dev/null 2>/dev/null | grep "Negotiated TLS1.3 group"
```

If hybrid key exchange is negotiated, the output is:

```console
Negotiated TLS1.3 group: X25519MLKEM768
```

#### Limitations

* Post-quantum key exchange applies only to the HTTPS endpoints served by Nginx. TigerGraph's Java-based clients, such as the `gsql` command-line client and the JDBC driver, and other communication paths, such as Kafka, cross-region replication, LDAP and SSO, and intra-cluster traffic, do not currently use post-quantum key exchange.
* Clients that offer only NIST-curve hybrid groups (`SecP256r1MLKEM768` or `SecP384r1MLKEM1024`), which is typical of FIPS-mode clients, do not negotiate a hybrid group with the default configuration. The connection still succeeds, using classical P-256 key exchange.
* If you replaced the Nginx configuration template (`Nginx.ConfigTemplate`) and restricted `ssl_protocols` to TLS 1.2, or set `ssl_ecdh_curve`, post-quantum key exchange might not be negotiated.
* Server certificates and signatures are unchanged and continue to use classical RSA or ECDSA.

### Customizing TLS Versions and Cipher Suites

TLS versions and cipher suites can be customized by modifying the `Nginx.ConfigTemplate`. These settings control which protocols and encryption standards are used for secure communication.

Changes apply to both client-facing and internal cluster communication and should be handled carefully to avoid unintended access or compatibility issues.

Common customization options include:

* **Disable TLS 1.2**  
If modern protocols are required, TLS 1.2 can be disabled by updating the `ssl_protocols` directive to allow only TLS 1.3.  
Current configuration  
```nginx  
ssl_protocols TLSv1.2 TLSv1.3;  
```  
Updated configuration  
```nginx  
ssl_protocols TLSv1.3;  
```
* **Restrict TLS 1.2 cipher suites**  
TLS 1.2 connections can be limited to a specific set of cipher suites by modifying the `ssl_ciphers` directive. This helps ensure that only approved and secure ciphers are used.  
```nginx  
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256;  
```
* **Restrict TLS 1.3 cipher suites**  
TLS 1.3 cipher suites are not explicitly configured by default. They can be defined by adding an `ssl_conf_command` directive. This allows control over which cipher suites are negotiated for TLS 1.3 connections.  
```nginx  
ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256;  
```

### Steps to Apply Changes

```bash
# 1. Export the current Nginx configuration template
gadmin config get Nginx.ConfigTemplate > nginx_conf_new

# 2. Edit the file:
#    - Locate the ssl_protocols directive to customize TLS versions
#    - Modify ssl_ciphers to restrict TLS 1.2 cipher suites
#    - Add ssl_conf_command to customize TLS 1.3 cipher suites

# 3. Apply the updated configuration
gadmin config set Nginx.ConfigTemplate @nginx_conf_new
gadmin config apply -y && gadmin restart NGINX -y
```

Cipher suite selection is fully customizable, the configurations defined in the Nginx template are applied exactly as specified.

> [!NOTE]
> Changes to `Nginx.ConfigTemplate` do not persist across upgrades. The template is backed up and reset during the upgrade process to incorporate version-specific changes. You must manually reapply your modifications to the new template version and resolve any conflicts as needed.

### Verifying Active Cipher Suites

Use `openssl s_client` to verify the negotiated TLS version and cipher suites at runtime. For this purpose, `openssl` serves as the recommended external tool.

Example

```bash
openssl s_client -connect <host>:<port> -tls1_3
```
