Encrypt Wire Communications
ScalarDB can encrypt wire communications by using Transport Layer Security (TLS). This document explains the configurations for wire encryption in ScalarDB.
The wire encryption feature encrypts:
- The communications between the ScalarDB Cluster node and clients.
- The communications between all the ScalarDB Cluster nodes (the cluster's internal communications).
- The communications between the Transaction Coordinator and clients.
- The communications between the Transaction Coordinator and the ScalarDB Clusters that it drives two-phase commit against.
- The communications between all the Transaction Coordinator nodes.
This feature uses TLS support in gRPC. For details, see the official gRPC Security Policy.
Enabling wire encryption between the ScalarDB Cluster nodes and the underlying databases in production environments is strongly recommended. For instructions on how to enable wire encryption between the ScalarDB Cluster nodes and the underlying databases, please refer to the product documentation for your underlying databases.
Configurations​
This section describes the available configurations for wire encryption.
ScalarDB Cluster node configurations​
To enable wire encryption in the ScalarDB Cluster nodes, you need to set scalar.db.cluster.tls.enabled to true.
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.enabled | Whether wire encryption (TLS) is enabled. | false |
You also need to set the following configurations:
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.ca_root_cert_pem | The custom CA root certificate (PEM data) for TLS communication. | |
scalar.db.cluster.tls.ca_root_cert_path | The custom CA root certificate (file path) for TLS communication. | |
scalar.db.cluster.tls.override_authority | The custom authority for TLS communication. This doesn't change what host is actually connected. This is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set for scalar.db.cluster.node.tls.cert_chain_path. | |
scalar.db.cluster.node.tls.cert_chain_path | The certificate chain file used for TLS communication. | |
scalar.db.cluster.node.tls.private_key_path | The private key file used for TLS communication. |
To specify the certificate authority (CA) root certificate, you should set either scalar.db.cluster.tls.ca_root_cert_pem or scalar.db.cluster.tls.ca_root_cert_path. If you set both, scalar.db.cluster.tls.ca_root_cert_pem will be used.
Transaction Coordinator configurations​
To enable wire encryption in the Transaction Coordinator, you need to set scalar.db.cluster.tls.enabled to true.
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.enabled | Whether wire encryption (TLS) is enabled. | false |
You also need to set the following configurations:
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.ca_root_cert_pem | The custom CA root certificate (PEM data) for TLS communication. | |
scalar.db.cluster.tls.ca_root_cert_path | The custom CA root certificate (file path) for TLS communication. | |
scalar.db.cluster.tls.override_authority | The custom authority for TLS communication. This doesn't change what host is actually connected. This is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set for scalar.db.cluster.transaction_coordinator.tls.cert_chain_path. | |
scalar.db.cluster.transaction_coordinator.tls.cert_chain_path | The certificate chain file used for TLS communication. | |
scalar.db.cluster.transaction_coordinator.tls.private_key_path | The private key file used for TLS communication. |
To specify the CA root certificate, you should set either scalar.db.cluster.tls.ca_root_cert_pem or scalar.db.cluster.tls.ca_root_cert_path. If you set both, scalar.db.cluster.tls.ca_root_cert_pem will be used.
The configurations above are applied to all the connections of the Transaction Coordinator. If the target clusters present server certificates that are signed by different certificate authorities, or that require different values for scalar.db.cluster.tls.override_authority, you can override a configuration for a single target cluster by using scalar.db.cluster.transaction_coordinator.clusters.<CLUSTER_ID>.<PROPERTY_NAME>. For example, you can specify the CA root certificate for the target cluster cluster1 only, as follows:
scalar.db.cluster.transaction_coordinator.clusters.cluster1.tls.ca_root_cert_path=/path/to/cluster1-ca.pem
Client configurations​
To enable wire encryption on the client side by using the ScalarDB Cluster Java client SDK, you need to set scalar.db.cluster.tls.enabled to true.
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.enabled | Whether wire encryption (TLS) is enabled. | false |
You also need to set the following configurations:
| Name | Description | Default |
|---|---|---|
scalar.db.cluster.tls.ca_root_cert_pem | The custom CA root certificate (PEM data) for TLS communication. | |
scalar.db.cluster.tls.ca_root_cert_path | The custom CA root certificate (file path) for TLS communication. | |
scalar.db.cluster.tls.override_authority | The custom authority for TLS communication. This doesn't change what host is actually connected. This is intended for testing, but may safely be used outside of tests as an alternative to DNS overrides. For example, you can specify the hostname presented in the certificate chain file that you set for scalar.db.cluster.node.tls.cert_chain_path. |
To specify the CA root certificate, you should set either scalar.db.cluster.tls.ca_root_cert_pem or scalar.db.cluster.tls.ca_root_cert_path. If you set both, scalar.db.cluster.tls.ca_root_cert_pem will be used.
If your application connects to both a ScalarDB Cluster and the Transaction Coordinator, the configurations above are applied to both connections. If the Transaction Coordinator presents a server certificate that is signed by a different certificate authority than the cluster, you can override a configuration for the connection to the Transaction Coordinator only by using scalar.db.cluster.client.transaction_coordinator.<PROPERTY_NAME>. For example, you can specify the CA root certificate for the Transaction Coordinator connection only, as follows:
scalar.db.cluster.client.transaction_coordinator.tls.ca_root_cert_path=/path/to/transaction-coordinator-ca.pem