SSL encryption¶

NebulaGraph supports SSL encrypted transfers. SSL and TLS are both security protocols used for network communication, with SSL being the predecessor to TLS. While mTLS is an enhanced version of TLS/SSL that employs mutual authentication to provide an even more secure communication method. This topic describes how to set up TLS and mTLS for SSL.

Precaution¶

Enabling SSL encryption will slightly affect the performance, such as causing operation latency.

Certificate modes¶

To use SSL encryption, SSL certificates are required. NebulaGraph supports two certificate modes.

Self-signed certificate mode

A certificate that is generated by the server itself and signed by itself. In the self-signed certificate mode, the server needs to generate its own SSL certificate and key, and then use its own private key to sign the certificate. It is suitable for building secure communications for systems and applications within a LAN.

CA-signed certificate mode

A certificate granted by a trusted third-party Certificate Authority (CA). In the CA signed certificate mode, the server needs to apply for an SSL certificate from a trusted CA and ensure the authenticity and trustworthiness of the certificate through the auditing and signing of the certificate authority center. It is suitable for public network environment, especially for websites, e-commerce and other occasions that need to protect user information security.

Authentication policies¶

Scenes	TLS	mTLS
External device access Graph	Modify the Graph configuration file to add the following parameters: `--enable_graph_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx`	Modify the Graph configuration file to add the following parameters: `--enable_graph_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx` `--ca_client_path=xxxxxx`
Graph access Meta	In the Graph/Meta configuration file, add the following parameters: `--enable_meta_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx`	In the Graph/Meta configuration file, add the following parameters: `--enable_meta_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx` `--ca_client_path=xxxxxx`
Graph access Storage Meta access Storage	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_storage_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx`	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_storage_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx` `--ca_client_path=xxxxxx`
Graph access Meta/Storage Meta access Storage Storage access Meta	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_meta_ssl = true` `--enable_storage_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx`	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_meta_ssl = true` `--enable_storage_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx` `--ca_client_path=xxxxxx`
External device access to Graph Graph access Meta/Storage Meta access Storage Storage access Meta	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx`	In the Graph/Meta/Storage configuration file, add the following parameters: `--enable_ssl = true` `--ca_path=xxxxxx` `--cert_path=xxxxxx` `--key_path=xxxxxx` `--ca_client_path=xxxxxx`

Note

When mTLS is required for external clients to connect to the Graph service, the user needs to set the relevant SSL parameters (especially ca_path) depending on the client. See below for examples of authentication.

The parameters are described below.

Parameter	Default value	Description
`cert_path`	-	The path to the SSL public key certificate. This certificate is usually a `.pem` or `.crt` file, which is used to prove the identity of the server side, and contains information such as the public key, certificate owner, digital signature, and so on.
`key_path`	-	The path to the SSL key. The SSL key is usually a `.key` file.
`password_path`	-	(Optional) The path to the password file for the SSL key. Some SSL keys are encrypted and require a corresponding password to decrypt. We need to store the password in a separate file and use this parameter to specify the path to the password file.
`ca_path`	-	The path to the SSL root certificate. The root certificate is a special SSL certificate that is considered the highest level in the SSL trust chain and is used to validate and authorize other SSL certificates.
`ca_client_path`	-	The path to the client SSL root certificate. It is mTLS when this parameter is used. For mTLS, the server needs to store the root certificate that generates the client SSL certificate, which is used to validate the client public key certificate.
`enable_ssl`	`false`	Whether to enable SSL encryption in all services. only.
`enable_graph_ssl`	`false`	Whether to enable SSL encryption in the Graph service only.
`enable_meta_ssl`	`false`	Whether to enable SSL encryption in the Meta service only.
`enable_storage_ssl`	`false`	Whether to enable SSL encryption in the Storage service only.

Example of TLS¶

For example, using self-signed certificates and TLS for data transfers between the client NebulaGraph Python, the Graph service, the Meta service, and the Storage service. You need to set up all three Graph/Meta/Storage configuration files as follows:
```
--enable_ssl=true
--ca_path=xxxxxx
--cert_path=xxxxxx
--key_path=xxxxxx
```
When the changes are complete, restart these services to make the configuration take effect.
To connect to the Graph service using NebulaGraph Python, you need to set up a secure socket and add a trusted CA. For code examples, see nebula-test-run.py.

Example of mTLS¶

For example, using CA-signed certificates and mTLS for data transfers between the client NebulaGraph Console and the Graph service. You need to set up the Graph configuration file as follows:
```
--enable_graph_ssl=true
--ca_path=xxxxxx
--cert_path=xxxxxx
--key_path=xxxxxx
--ca_client_path=xxxxxx
```
When the changes are complete, restart the Graph service to make the configuration take effect.

Use the NebulaGraph Console to connect to the Graph service with the following command:

./nebula-console  -addr 192.168.8.100 -port 9669 -u root  -p nebula -enable_ssl -ssl_root_ca_path /home/xxx/cert/root.crt -ssl_cert_path /home/xxx/cert/client.crt -ssl_private_key_path /home/xxx/cert/client.key

Automatic monitoring of SSL certificate updates¶

NebulaGraph supports monitoring SSL certificates for updates, automatically triggering reloading of certificates and re-authentication when an update is detected.

NebulaGraph monitors the file specified by the cert_path parameter by default and triggers a re-authentication if the file changes.

Note

Since changing the files specified by cert_path triggers re-authentication, when updating a certificate, you should update the key_path, ca_path, and other files first, and then update the cert_path files last.

If you want to use symbol links, you can add the parameter ssl_watch_path to each configuration file where cert_path is added to specify the parent directory of the symbol link where the SSL file is stored, e.g., if the symbol link path is /home/xxx/share/current, the ssl_watch_path needs to be set to /home/xxx/share. Users can use ln -snf <source folder path> current to modify the source folder path of current as they wish.

Last update: September 21, 2023