Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sync-sc-to-v3.6.0-ent #2242

Merged
merged 1 commit into from
Aug 24, 2023
Merged

sync-sc-to-v3.6.0-ent #2242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 94 additions & 32 deletions docs-2.0/7.data-security/4.ssl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,126 @@
# SSL encryption

NebulaGraph supports data transmission with SSL encryption between clients, the Graph service, the Meta service, and the Storage service. This topic describes how to enable 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.

## Precaution
{{ent.ent_begin}}
!!! enterpriseonly

Enabling SSL encryption will slightly affect the performance, such as causing operation latency.
Nebula Graph's enterprise edition includes support for mTLS, which enhances the security of TLS/SSL by requiring mutual authentication between the client and server, in addition to encrypting the transmission of data. Similar to TLS, setting up mTLS involves generating and configuring mutually authenticated SSL certificates for servers and clients.
{{ent.ent_end}}

## Parameters
This topic describes how to set up SSL encryption for NebulaGraph.

## Precaution

| Parameter | Default value | Description |
| ------------------ | ------- | ------------------------------|
| `cert_path` | - | The path to the PEM certification. |
| `key_path` | - | The path to the key certification. |
| `password_path` | - | The path to the password file certification. |
| `ca_path` | - | The path to the trusted CA file. |
| `enable_ssl` | `false` | Whether to enable SSL encryption. |
| `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. |
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

In this mode, users need to make the signed certificate by themselves and set `cert_path`, `key_path`, and `password_path` in the corresponding file according to encryption policies.
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

In this mode, users need to apply for the signed certificate from a certificate authority and set `cert_path`, `key_path`, and `password_path` in the corresponding file according to encryption policies.
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.

## Encryption policies
## Authentication policies

NebulaGraph supports three encryption policies. For details, see [Usage explanation](https://github.com/vesoft-inc/nebula/blob/a67d166b284cae1b534bf8d19c936ee38bf12e29/docs/rfcs/0001-ssl-transportation.md#usage-explanation).
- Policies for the NebulaGraph community edition.

- Encrypt the data transmission between clients, the Graph service, the Meta service, and the Storage service.
|-| External device access to Graph | Graph access Meta/Storage |External device access to Graph</br>Graph access Meta/Storage|
|:---|:---|:---|:---|
|TLS| Modify the Graph configuration file to add the following parameters:</br>`--enable_graph_ssl = true`</br> `--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`|In the Graph/Meta/Storage configuration file, add the following parameters:</br>`--enable_meta_ssl = true`</br>`--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`|In the Graph/Meta/Storage configuration file, add the following parameters:</br>`--enable_ssl = true`</br>`--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`|

Add `enable_ssl = true` to the configuration files of `nebula-graphd.conf`, `nebula-metad.conf`, and `nebula-storaged.conf`.
The parameters are described below.

- Encrypt the data transmission between clients and the Graph service.

This policy applies to the case that the clusters are set in the same server room. Only the port of the Graph service is open to the outside because other services can communicate over the internal network without encryption. Add `enable_graph_ssl = true` to the configuration file of `nebula-graphd.conf`.
| 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. |
| `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. |

- Encrypt the data transmission related to the Meta service in the cluster.
{{ent.ent_begin}}

- Policies for the NebulaGraph enterprise edition.

This policy applies to transporting classified information to the Meta service. Add `enable_meta_ssl = true` to the configuration files of `nebula-graphd.conf`, `nebula-metad.conf`, and `nebula-storaged.conf`.
|-| External device access to Graph | Graph access Meta/Storage |External device access to Graph</br>Graph access Meta/Storage|
|:---|:---|:---|:---|
|mTLS|Modify the Graph configuration file to add the following parameters:</br>`--enable_graph_ssl = true`</br> `--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`</br>`--ca_client_path=xxxxxx`|In the Graph/Meta/Storage configuration file, add the following parameters:</br>`--enable_meta_ssl = true`</br> `--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`</br>`--ca_client_path=xxxxxx`|In the Graph/Meta/Storage configuration file, add the following parameters:</br>`--enable_ssl = true`</br> `--ca_path=xxxxxx`</br>`--cert_path=xxxxxx`</br>`--key_path=xxxxxx`</br>`--ca_client_path=xxxxxx`|

!!! note

## Steps
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](../14.client/1.nebula-client.md). See below for examples of authentication.

1. Ensure the certificate mode and the encryption policy.
The parameters are described below.

2. Add the certificate configuration and the policy configuration in corresponding files.
| 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. |

For example, the three configuration files need to be set as follows when using a self-signed certificate and encrypt data transmission between clients, the Graph service, the Meta service, and the Storage service.
{{ent.ent_end}}



## Example of TLS

1. 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:

```bash
--cert_path=xxxxxx
--key_path=xxxxx
--password_path=xxxxxx
--enable_ssl=true
--ca_path=xxxxxx
--cert_path=xxxxxx
--key_path=xxxxxx
```

2. When the changes are complete, restart these services to make the configuration take effect.

3. 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](https://github.com/vesoft-inc/nebula/blob/{{nebula.branch}}/tests/nebula-test-run.py).

{{ent.ent_begin}}
## Example of mTLS

1. 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:

```bash
--enable_graph_ssl=true
--ca_path=xxxxxx
--cert_path=xxxxxx
--key_path=xxxxxx
--ca_client_path=xxxxxx
```

2. When the changes are complete, restart the Graph service to make the configuration take effect.

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

```bash
./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
```

3. Set the SSL and the trusted CA in clients. For code examples, see [nebula-test-run.py](https://github.com/vesoft-inc/nebula/blob/{{nebula.branch}}/tests/nebula-test-run.py).
## 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.

{{ent.ent_end}}
Loading