Configure Transport Layer Security (TLS)
ZDM Proxy supports proxy-to-cluster and application-to-proxy TLS encryption.
The TLS configuration is an optional part of the initial ZDM Proxy configuration. See the information here in this topic, and then refer to the ZDM Proxy Automation topics that cover:
Introduction
-
All TLS configuration is optional. Enable TLS between the ZDM Proxy and any cluster that requires it, and/or between your client application and the ZDM Proxy if required.
-
Proxy-to-cluster TLS can be configured between the ZDM Proxy and either or both the origin and target clusters, as desired. Each set of configurations is independent of the other. When using proxy-to-cluster TLS, the ZDM Proxy acts as the TLS client and the cluster as the TLS server. One-way TLS and Mutual TLS are both supported and can be enabled depending on each cluster’s requirements.
-
When using application-to-proxy TLS, your client application is the TLS client and the ZDM Proxy is the TLS server. One-way TLS and Mutual TLS are both supported.
-
When the ZDM Proxy connects to Astra DB, it always implicitly uses Mutual TLS. This is done through the Secure Connect Bundle (SCB) and does not require any extra configuration.
Retrieving files from a JKS keystore
If you are already using TLS between your client application and the origin cluster, then the files needed to configure TLS will already be used in the client application’s configuration (TLS client files) and the origin’s configuration (TLS Server files). In some cases, these files may be contained in a JKS keystore.
The ZDM Proxy does not accept a JKS keystore, requiring the raw files instead.
To view the files contained in a JKS keystore and their aliases:
keytool -list -keystore <path_to_keystore.jks>To extract a file from a JKS keystore:
keytool -exportcert -keystore <path_to_jks_store> -alias <file_alias> -file <path_to_destination_file> -rfc
Please note the -rfc option, which extracts the files in non-binary PEM format.
For more details, see the keytool syntax documentation.
Proxy to self-managed cluster TLS
Here’s how to configure TLS between the ZDM Proxy and a self-managed cluster (Apache Cassandra or DSE). In this case the ZDM Proxy acts as the TLS client and the cluster acts as the TLS server.
The files required to configure proxy-to-cluster TLS are:
-
Server CA: needed for one-way and Mutual TLS
-
Client certificate: only needed for Mutual TLS
-
Client key: only needed for Mutual TLS
|
If your origin cluster requires TLS, your client application will already be using these files in its configuration to connect to it. |
|
All files must be in plain-text, non-binary format. |
Prepare the TLS files and copy them to the Ansible Control Host container
For each self-managed origin or target cluster that requires TLS, do the following:
-
If your TLS files are in a JKS keystore, extract them as plain text (see Retrieving files from a JKS keystore).
-
Upload the following files to the jumphost:
-
For one-way TLS, uploda only the server CA.
-
For Mutual TLS, upload the server CA, the client cert, and the client key.
-
-
From a shell on the jumphost, copy the files to the relevant TLS directory into the Ansible Control Host container:
-
For origin clusters, run:
docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/origin_tls_files -
For target clusters, run:
docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/target_tls_files
-
Configure TLS
There are separate TLS configuration variables for origin and target clusters so that you can configure these independently, if needed.
-
Open a shell to the container:
docker exec -it zdm-ansible-container bash -
Find the custom TLS configuration file at
zdm-proxy-automation/ansible/vars/zdm_proxy_custom_tls_config.yml. -
Uncomment and set the following variables in the custom TLS configuration file for the proxy-to-origin TLS configuration:
-
origin_tls_user_dir_path: uncomment and leave to its preset value of/home/ubuntu/origin_tls_files. -
origin_tls_server_ca_filename: filename (without path) of the Server CA. -
origin_tls_client_cert_filename: filename (without path) of the Client cert. This is for Mutual TLS only, leave unset otherwise. -
origin_tls_client_key_filename: filename (without path) of the Client key. For Mutual TLS only, leave unset otherwise.
-
-
Uncomment and set the variables for the proxy-to-target TLS configuration:
-
target_tls_user_dir_path: uncomment and leave to its preset value of/home/ubuntu/target_tls_files. -
target_tls_server_ca_filename: filename (without path) of the Server CA. -
target_tls_client_cert_filename: filename (without path) of the Client cert. This is for Mutual TLS only, leave unset otherwise. -
target_tls_client_key_filename: filename (without path) of the Client key. For Mutual TLS only, leave unset otherwise.
-
Application-to-proxy TLS
Here are the steps to enable TLS between your client application and the ZDM Proxy if required. Please bear in mind that in this case your client application is the TLS client and the ZDM Proxy is the TLS server.
The files required by the proxy to configure application-to-proxy TLS are:
-
Server CA
-
Server certificate
-
Server key
All these files are required for one-way and Mutual TLS.
|
If your origin cluster currently requires TLS, it will already be using these files for its own TLS configuration. All files must be in plain-text, non-binary format. |
Here are the steps to configure application-to-proxy TLS:
-
If your TLS files are in a JKS keystore, extract them as plain text (see Retrieving files from a JKS keystore).
-
Upload the required files to the jumphost: Server CA, Server certificate and Server key.
-
From a shell on the jumphost, copy the files to the
zdm_proxy_tls_filesTLS directory into the Ansible Control Host container:docker cp <your_tls_files> zdm-ansible-container:/home/ubuntu/zdm_proxy_tls_files. -
Ensure that you have a shell open to the container. If you do not, you can open it with
docker exec -it zdm-ansible-container bash. -
From this shell, edit the file
zdm-proxy-automation/ansible/vars/zdm_proxy_custom_tls_config.yml, uncommenting and populating the relevant configuration variables. These are in the bottom section ofvars/proxy_custom_tls_config_input.ymland are all prefixed withzdm_proxy:-
zdm_proxy_tls_user_dir_path_name: uncomment and leave to its preset value of/home/ubuntu/zdm_proxy_tls_files. -
zdm_proxy_tls_server_ca_filename: filename (without path) of the server CA that the proxy must use. Always required. -
zdm_proxy_tls_server_cert_filenameandzdm_proxy_tls_server_key_filename: filenames (without path) of the server certificate and server key that the proxy must use. Both always required. -
zdm_proxy_tls_require_client_auth: whether you want to enable Mutual TLS between the application and the proxy. Optional: defaults tofalse( = one-way TLS ), can be set totrueto enable Mutual TLS.
-
|
Remember that in this case, the ZDM Proxy is the TLS server; thus the word |
Apply the configuration
This is all that is needed at this point. As part of its normal execution, the proxy deployment playbook will automatically distribute all TLS files and apply the TLS configuration to all ZDM Proxy instances.
Just go back to Optional advanced configuration to finalize the ZDM Proxy configuration and then execute the deployment playbook.
