Hybrid Data Pipeline SSL Certificate Management

When setting up Progress DataDirect Hybrid Data Pipeline, you need to choose whether to provide your own SSL certificate to handle secure traffic for the UI as well as OData/ODBC/JDBC connections. If you use the self-signed certificate during installation, web browsers will report that the HTTPS endpoint isn’t secure and some services, such as Salesforce Connect and Oracle Service Cloud, require publicly trusted SSL certificates to establish a connection.

To prevent these issues and provide for the most secure deployment of Hybrid Data Pipeline (HDP), we recommend provided a publicly trusted SSL certificate when installing your Hybrid Data Pipeline servers.

In the case of a load-balanced solution this certificate will be deployed on your choice of load balancer (for example: HAProxy, F5, Amazon ALB, Azure App GW) and on the Hybrid Data Pipeline servers for proper redistribution files for use with the On-Premises Connector, ODBC, and JDBC drivers.

For standalone Hybrid Data Pipeline deployments (single server), where SSL is terminated directly on the HDP server itself, the certificate serves both the purpose of creating a trusted HTTP endpoint and generating valid redistribution files. 

Documentation on the PEM file can be found here.

When you request a certificate from a public certificate authority (CA), you provide them with your signing request (CSR) from the HDP server. You also will generate a private key at this time. If your private key is encrypted, you will need to decrypt it for HDP.

You can identify whether a private key is encrypted or not by opening the private key (.key or .pem file) using a text editor or command line.

You should see the text ENCRYPTED if the private key is encrypted when viewing the file:

$ cat encrypted_private.key
-----BEGIN ENCRYPTED PRIVATE KEY-----

To decrypt the private key from the terminal:

1. Open terminal
2. Run the open ssl command to decrypt the file
3. $ openssl rsa -in <encrypted_private.key>  -out <decrypted_private.key>
4. Enter pass phrase for encrypted_private.key: <enter the password> writing RSA key
5. Once the private key has been decrypted, open the file and you should not see the text ENCRYPTED anymore.
6. $ cat decrypted_private.key

-----BEGIN RSA PRIVATE KEY-----

Once your private key is decrypted, you can load it to your load balancer if applicable.

If you are terminating SSL directly on your Hybrid Data Pipeline server, the private key will be listed first in the PEM file we are constructing. Start the file by adding the private key to an empty text file, including the tags:

-----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- 

Note, if you are using a load balancer you do not need to include the private key in the PEM file since HTTPS traffic will not be terminating on it. In instances where you do want the connection from the load balancer to HDP servers to be encrypted via SSL, complete this tutorial first, leaving the private key out of the PEM, and then proceed to these docs.

Next, paste the server certificate received from your CA in x509 or PEM format into the file. If you have a pfx, jks, p7b or der formatted file, use OpenSSL to change the format to PEM using these docs.

At this point, you should have a text file which contains your Private Key (if needed) and your server certificate. Finally, we need to add the remained of the trust chain using any intermediate certificates from your certificate authority and the root certificate.

I find using this tool (external site) to validate the full chain useful to avoid errors on installation. You can paste your entire chain, from the server certificate through the root cert to ensure there are no gaps. One caveat is the tool will report a complete chain without the root cert, so make sure you add it since HDP expects it. Your certificate vendor should be able to provide the certificates required to build the chain.

When completed, it should appear like this if including the private key and only needing one intermediate certificate (sometimes multiples are needed):

When installing Hybrid Data Pipeline, you will be asked to enter the hostname of your HDP server.

In an install where you are terminating SSL on the HDP server itself (single-node), this hostname must be the fully qualified domain name matching the public SSL certificate. For example, if you connect to HDP using https://hdp.example.com, your certificate must be for hdp.example.com or *.example.com and the hostname used during the HDP setup should be “hdp.example.com”

If you are using a load balancer, use the actual name of the server which your load balancer will be able to resolve. Do not use the public DNS name as the hostname. You will be prompted later in the installation for the hostname of the load balancer once you select that installation type.

When you are required to replace the certificate on your Hybrid Data Pipeline deployment, the process will vary depending on how it was deployed – SSL terminating directing on the HDP server or on a load balancer.

For deployments terminating SSL directly on the HDP server, you will need to build a new PEM file using the same process described above. If you are using the same certificate authority, you may only need to replace the server certificate in your PEM. Be sure to validate this with your certificate provider.

There are two options to install the new PEM file:

1. You can then run an update installation which will maintaining the existing settings. Provide the path to the new PEM file when prompted. This will also generate new redist files for use with your ODBC, JDBC and On-Premises Connector installations.
2. Follow this procedure to manually replace the certificates and build the required keystore.

If your deployment uses a load balancer to terminate SSL, you will use the same procedure as above, but also need to update the certificate on your load balancer per the vendor’s instructions.

For further details on managing Hybrid Data Pipeline, please refer to the best practices guide here. If you have further questions about this tutorial or Hybrid Data Pipeline in general, please contact us.