Setting up one-way TLS authentication for the Data Receiver

Complete the steps in this section to set up one-way TLS authentication for the Data Receiver.

Before you begin

Data Receiver works as the server side. When you configure TLS authentication, either a self-signed certificate or a CA signed certificate is supported.

The CA signed certificate for the Data Receiver can be in one of the following formats:

Table 1. CA signed certificates format and required files
CA signed certificate format	Required file
CA signed certificate that applied in distributed systems	server.crt (CA signed certificate chain)
CA signed certificate that applied in distributed systems	server.key (private key)
CA signed certificate that applied in distributed systems with password protected private key	server.crt (CA signed certificate chain)
	server.key (passphrase protected private key)

Important: The CA signed certificate file server.crt should be a certificate chain, also known as the certification path, which is a list of certificates used to authenticate an entity. The chain, or path, begins with the certificate of that entity, and each certificate in the chain is signed by the entity identified by the next certificate in the chain. The chain terminates with the root CA certificate.

Procedure

For each Data Receiver that must use secure communications with the Data Streamer, complete the following steps on the Data Receiver system. The Data Receiver works as the server side, you can follow the guidance to configure it to use TLS with self-signed or CA signed certificates.

Install and configure the Data Receiver.
Set the following environment variables:
- For Linux® systems
```
export JAVA_HOME=/java_installation_directory
export CDPDR_HOME=/dr_working_directory
export CDPDR_PATH=/dr_output_directory
```
- For Windows systems
```
set JAVA_HOME=/java_installation_directory
set CDPDR_HOME=/dr_working_directory
set CDPDR_PATH=/dr_output_directory
```
JAVA_HOME

The Java™ installation directory on the Data Receiver system.

CDPDR_HOME

The Data Receiver working directory that is described in Setting up a working directory and an output directory for the Data Receiver.

CDPDR_PATH

The Data Receiver output directory that is described in Setting up a working directory and an output directory for the Data Receiver.
Change to directory CDPDR_HOME and run the script setupDataReceiverTLS.sh or setupDataReceiverTLS.bat, as shown in the following command.
This script configures the Data Receiver to use TLS to communicate with the Data Streamer. Running this script requires Java Runtime Environment (JRE) 8 or later.
- For Linux systems, go to the Data Receiver working directory CDPDR_HOME and run the following command:
```
cd CDPDR_HOME
./setupDataReceiverTLS.sh
```
- For Windows systems, go to the Data Receiver working directory CDPDR_HOME and run the following command:
```
cd CDPDR_HOME
setupDataReceiverTLS.bat
```
The script will prompt the following questions：

You would like to create a self-signed certificate?(type "yes" or "no")

If you want to configure the Data Receiver to use a self-signed certificate, enter 'yes' to go to option (1) To generate a self-signed certificate; otherwise, enter 'no' to go to option (2) To import a CA signed certificate.
Tip: The script supports self-signed and CA signed certificate. If you want to import CA signed certificates or generate multiple self-signed certificates, just run the script setupDataReceiverTLS.sh or setupDataReceiverTLS.bat multiple times and select the option you want to execute.
- (1) To generate a self-signed certificate (by entering 'yes')
  Enter 'yes' in the above prompt to generate a self-signed certificate. Province values for the following questions for the self-signed certificate:
  
  What is the name of the alias you prefer to use?
  
  The alias name for the self-signed certificate of the Data Receiver. The alias name is used as part of the self-signed certificate name and the naming rule is cdp_alias.cert.
  Important: Make sure to provide a unique alias; otherwise, the previous self-signed certificate will be overwritten by the newly created one.
  
  What is the hostname of your machine?
  
  The fully qualified host name of the system where the Data Receiver is deployed.
  
  What is the ip address of your machine?
  
  The IP address of the system where the Data Receiver is deployed.
  
  What is the password you would like to use for truststore and keystore?
  
  To initialize the password that will used for the Data receiver keystore (cdp.jks) and truststore (cdp_truststore.jks) file.
  Note: This question only occurs when you initialize the Data Receiver TLS settings for the first time.
  
  What is the Fully Qualified Domain Name?
  
  The fully qualified domain name, short for CN.
  The value can be customized or left empty with the default value.
  
  What is the name of your organizational unit?
  
  The organization unit name, short for OU.
  The value can be customized or left empty with the default value.
  
  What is the name of your organization?
  
  The organization name, short for O.
  The value can be customized or left empty with the default value.
  
  What is the name of your City or Locality?
  
  The organization name, short for L.
  The value can be customized or left empty with the default value.
  
  What is the name of your State or Province?
  
  The state or province name, short for ST.
  The value can be customized or left empty with the default value.
  
  What is the two-letter country code for this unit?
  
  The two-letter country code, short for C.
  The value can be customized or left empty with the default value.
  
  Is CN=***, OU=***, O=***, L=***, ST=***, C=*** correct?
  
  The summary of the parameters required for the self-signed certificate process. Check carefully to make sure the value is correct. If all the values are correct, enter 'yes'; otherwise, enter 'no' to reenter the value.
  
  After you complete the above steps, the TLS one-way setup process for generating a self-signed certificate is completed. The following files are created in the CDPDR_HOME directory:
  
  passStore
  
  Contains a secret key for password encryption.
  
  cdp.properties
  
  Contains the encrypted password for the Data Receiver keystore.
  
  cdp.jks
  
  Keystore that contains the private entry for the Data Receiver.
  Tip: The files passStore, cdp.properties, and cdp.jks are only generated if they are not in the Data Receiver home directory (CDPDR_HOME); otherwise, you can just refresh cdp.jks to import the CA signed certificate or generate a self-signed certificate.
  
  cdp_alias.cert
  
  The Data Receiver's self-signed certificate, which should be imported to the Data Streamer's truststore.
  Tip: Generating multiple self-signed certificates is supported by the Data Receiver's TLS settings. You just need to run the script one more time to generate another self-signed certificate, and the key entry will be contained in the cdp.jks file.
- (2) To import a CA signed certificate (by entering 'no')
  Enter "no" in the first prompt if you would like to import a CA signed certificate to the Data Receiver's keystore, and the script will prompt the CA signed certificate option.
  You would like to import the CA certificate to DataReceiver keystore?(type "yes" or "no")
  
  If you want to configure the Data Receiver to use a CA signed certificate, enter 'yes'.; otherwise, the script will be canceled. The following parameters are required for a CA signed certificate:
  
  What is your Data Receiver CA signed certificate path?
  
  The file path of the CA-signed public certificate of the Data Receiver.
  
  What is your Data Receiver DER format CA server private key path?
  
  The file path of DER format CA private key of the Data Receiver.
  Tip: You can run the following command to check the format of the CA private key:
  cat server.key
  If the content displays as the following format, the private key is in the PEM format and you should use the openssl command to transfer the private key from PEM to DER format.
  -----BEGIN PRIVATE KEY----- Base64_decode (DER binary) -----END PRIVATE KEY-----
  To transfer the private key to DER format, run the following command:
  openssl pkcs8 -topk8 -inform PEM -outform DER -in server.key -out server_der.key -nocrypt
  
  Is your CA private key password protected?(type ''yes'' or ''no'')
  
  If your private key is protected by password, enter 'yes'. The system will prompt you to enter the password of the private key file to decrypt the file; otherwise, enter 'no'. The system will import private key and certificate into the Data Receiver's keystore file.
  
  What is the DER format CA private key password?
  
  Enter the password for your private key file.
  After you complete the above steps, the following files are created in the CDPDR_HOME directory:
  passStore
  
  Contains a secret key for password encryption.
  
  cdp.properties
  
  Contains the encrypted password for the Data Receiver keystore.
  
  cdp.jks
  
  Keystore that contains the private entry for the Data Receiver.
To enable the Data Receiver with one-way TLS communication, you need to update the cdpdr.properties sample file in the Data Receiver working directory: CDPDR_HOME.
Update the variable SSL from the default value 'n' to 'y' to enable the Data Receiver to start with TLS authentication.
Transfer the public certificate files from the Data Receiver server to the Data Streamer system. Give each certificate file a unique name. The certificates must be imported into the Data Streamer's truststore file.
- For self-signed certificate:
  Transfer the cdp_alias.cert file to the Data Streamer's working directory.
- For CA signed certificate:
  Transfer the ca_root.crt to the Data Streamer's working directory.
- Transfer format:
  Use BINARY mode to transfer the certificate to the Data Streamer's working directory.
  Important: When you transfer the Data Receiver server's self-signed certificate or CA signed certificate to the working directory of the Data Streamer, be sure to use the BINARY mode.