How to create a new self-signed SSL certificate and configure TIBCO Data Virtualization to use the certificate?
Article ID: KB0073533
Updated On:
| Products | Versions |
|---|---|
| TIBCO Data Virtualization | All supported versions |
Description
How to create a new self-signed SSL certificate and configure TIBCO Data Virtualization to use the certificate?
Issue/Introduction
How to create a new self-signed SSL certificate and configure TIBCO Data Virtualization to use it
Resolution
Below are the steps to:
(1) Back up up the TDV server keystore file and server_values.xml file.
Make a copy of these two files:
<TDV_INSTALL>/conf/server/security/cis_server_keystore.jks
<TDV_INSTALL>/conf/server/server_values.xml
This provides the flexibility to roll back changes if required.
(2) Generate a JKS file containing a Private Key for the new certificate.
Below is an example of using the keytool utility to create a file named Test_server_keystore.jks containing a new Private Key whose alias name is spruce.
-------------
C:\apps\tdv84a\jdk\bin\keytool -genkey -keyalg RSA -alias spruce -keystore Test_server_keystore.jks -storepass changeit
-------------
IMPORTANT:
When generating the Key, specify a key algorithm that meets the minimum requirements for TLS 1.3. In the above command, RSA has been specified as the algorithm because otherwise keytool will default to using DSA. DSA is not considered to be secure enough to meet TLS 1.3 requirements. Therefore, if DSA is used, some browsers (e.g. Chrome) will fail to open an SSL connection to the HTTPS url i.e. https://<TDV server host>:<base port +2>
(3) Copy the keystore file (e.g. Test_server_keystore.jks) to <TDV_INSTALL>\conf\server\security
The new keystore file may be stored in any folder on the machine. However, it is recommended to store it in the default TDV location \conf\server\security so that only the keystore filename needs to be updated in the configuration (there is no need to update the keystore folder path).
(4) Change the value of "Keystore File Location (On Server Restart)" to point to the new keystore file.
Change the name of the Keystore file, as shown in the example below.
Change:
Keystore File Location (On Server Restart) = C:/apps/tdv84a/conf/server/security/ cis_server_keystore.jks
To:
Keystore File Location (On Server Restart) = C:/apps/tdv84a/conf/server/security/ Test_server_keystore.jks
(5) Change the value of "Keystore Key Alias (On Server Restart)" to the new alias.
Change the name of the keystore alias, as shown in the example below.
Change:
Keystore Key Alias (On Server Restart) = cis_server
To:
Keystore Key Alias (On Server Restart) = spruce
(6) Restart the TDV server.
Restart the TDV server to reload the changes into memory. There is no need to restart the Postgres Repository, or the Postgres cache.
(7) Check whether the new certificate is in use, by connecting to the HTTPS url using a browser.
Browsers provide a feature to view the certificate sent to them by the site that they are connecting to. This feature is usually a small icon present next to the browser's URL field. Clicking on this icon should result in the new certificate being displayed, as shown below.
8. If there are existing VCS connections, import the certificate into the TDV Studio truststore.
Until the certificate is imported into the Studio truststore, Studio will be unable to display the VCS connections. Instead, when VCS >> Manage Connections is clicked on in Studio, an error dialog will pop up displaying the following message:
Failed to load VCS connections from the server. Please check your SSL certificate.
and the Studio log (cs_studio.log) will contain the following error:
-------------
INFO 2021-04-20 14:20:21.315 -0700 VcsHelper - GetIsVcsEnabled
javax.ws.rs.ProcessingException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
-------------
To import the certificate, a browser may be used to save the certificate as an X.509 file (e.g. ROOT.cer), and the X.509 file subsequently imported into the Studio truststore as shown in the example below:
8.1 Export the certificate as a file named ROOT.cer
8.2 Import the file into the Studio truststore
Use keytool to import the file into the Studio truststore as shown in the example below.
-------------
C:\apps\tdv84\jdk\bin\keytool -import -trustcacerts -alias tdvcert1 -file ROOT.cer -keystore C:\apps\tdv84\conf\studio\security\cis_studio_truststore.jks -storepass changeit
-------------
9. If the "Encrypt" option in the Studio login dialog is being used, import the certificate into the TDV Studio truststore.
Selecting the "Encrypt" checkbox in the Studio login dialog box tells Studio to open an SSL connection to the TDV server. If the new certificate has not been imported into the Studio truststore, Studio will be unable to open an SSL connection to the TDV server. Instead the login attempt will fail, accompanied by an error message " PKIX path building failed" appearing in cs_studio.log. To resolve the error, import the certificate using the instructions in the previous step ( #8).
10. If TDV has been configured to use the Drill Engine, import the certificate into the TDV server truststore.
Drill opens a SSL connection to TDV. In order to open the SSL connection, Drill searches for the certificate in the TDV server truststore. If the certificate is not found, Drill will write the following error to cs_server.log whenever TDV is started:
-------------
ERROR [main] 2021-05-05 06:28:38.498 -0700 DrillEngine -
com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
-------------
Below is an example of importing the certificate into the TDV server truststore.
-------------
C:\apps\tdv84\jdk\bin\keytool -import -trustcacerts -alias tdvcert1 -file ROOT.cer -keystore C:\apps\tdv84\conf\server\security\cis_server_truststore.jks -storepass changeit
-------------------
11. If any other client applications are opening SSL connections to TDV, their truststores need to be updated
Any existing clients (e.g. JDBC clients) that open an SSL connection to TDV will need to have their truststores updated by importing the new certificate into their truststores.
- Create a new self-signed SSL certificate using keytool.
- Configure TIBCO Data Virtualization (TDV) to use the new certificate.
(1) Back up up the TDV server keystore file and server_values.xml file.
Make a copy of these two files:
<TDV_INSTALL>/conf/server/security/cis_server_keystore.jks
<TDV_INSTALL>/conf/server/server_values.xml
This provides the flexibility to roll back changes if required.
(2) Generate a JKS file containing a Private Key for the new certificate.
Below is an example of using the keytool utility to create a file named Test_server_keystore.jks containing a new Private Key whose alias name is spruce.
-------------
C:\apps\tdv84a\jdk\bin\keytool -genkey -keyalg RSA -alias spruce -keystore Test_server_keystore.jks -storepass changeit
-------------
IMPORTANT:
When generating the Key, specify a key algorithm that meets the minimum requirements for TLS 1.3. In the above command, RSA has been specified as the algorithm because otherwise keytool will default to using DSA. DSA is not considered to be secure enough to meet TLS 1.3 requirements. Therefore, if DSA is used, some browsers (e.g. Chrome) will fail to open an SSL connection to the HTTPS url i.e. https://<TDV server host>:<base port +2>
(3) Copy the keystore file (e.g. Test_server_keystore.jks) to <TDV_INSTALL>\conf\server\security
The new keystore file may be stored in any folder on the machine. However, it is recommended to store it in the default TDV location \conf\server\security so that only the keystore filename needs to be updated in the configuration (there is no need to update the keystore folder path).
(4) Change the value of "Keystore File Location (On Server Restart)" to point to the new keystore file.
Change the name of the Keystore file, as shown in the example below.
Change:
Keystore File Location (On Server Restart) = C:/apps/tdv84a/conf/server/security/ cis_server_keystore.jks
To:
Keystore File Location (On Server Restart) = C:/apps/tdv84a/conf/server/security/ Test_server_keystore.jks
(5) Change the value of "Keystore Key Alias (On Server Restart)" to the new alias.
Change the name of the keystore alias, as shown in the example below.
Change:
Keystore Key Alias (On Server Restart) = cis_server
To:
Keystore Key Alias (On Server Restart) = spruce
(6) Restart the TDV server.
Restart the TDV server to reload the changes into memory. There is no need to restart the Postgres Repository, or the Postgres cache.
(7) Check whether the new certificate is in use, by connecting to the HTTPS url using a browser.
Browsers provide a feature to view the certificate sent to them by the site that they are connecting to. This feature is usually a small icon present next to the browser's URL field. Clicking on this icon should result in the new certificate being displayed, as shown below.
8. If there are existing VCS connections, import the certificate into the TDV Studio truststore.
Until the certificate is imported into the Studio truststore, Studio will be unable to display the VCS connections. Instead, when VCS >> Manage Connections is clicked on in Studio, an error dialog will pop up displaying the following message:
Failed to load VCS connections from the server. Please check your SSL certificate.
and the Studio log (cs_studio.log) will contain the following error:
-------------
INFO 2021-04-20 14:20:21.315 -0700 VcsHelper - GetIsVcsEnabled
javax.ws.rs.ProcessingException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
-------------
To import the certificate, a browser may be used to save the certificate as an X.509 file (e.g. ROOT.cer), and the X.509 file subsequently imported into the Studio truststore as shown in the example below:
8.1 Export the certificate as a file named ROOT.cer
8.2 Import the file into the Studio truststore
Use keytool to import the file into the Studio truststore as shown in the example below.
-------------
C:\apps\tdv84\jdk\bin\keytool -import -trustcacerts -alias tdvcert1 -file ROOT.cer -keystore C:\apps\tdv84\conf\studio\security\cis_studio_truststore.jks -storepass changeit
-------------
9. If the "Encrypt" option in the Studio login dialog is being used, import the certificate into the TDV Studio truststore.
Selecting the "Encrypt" checkbox in the Studio login dialog box tells Studio to open an SSL connection to the TDV server. If the new certificate has not been imported into the Studio truststore, Studio will be unable to open an SSL connection to the TDV server. Instead the login attempt will fail, accompanied by an error message " PKIX path building failed" appearing in cs_studio.log. To resolve the error, import the certificate using the instructions in the previous step ( #8).
10. If TDV has been configured to use the Drill Engine, import the certificate into the TDV server truststore.
Drill opens a SSL connection to TDV. In order to open the SSL connection, Drill searches for the certificate in the TDV server truststore. If the certificate is not found, Drill will write the following error to cs_server.log whenever TDV is started:
-------------
ERROR [main] 2021-05-05 06:28:38.498 -0700 DrillEngine -
com.sun.jersey.api.client.ClientHandlerException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
-------------
Below is an example of importing the certificate into the TDV server truststore.
-------------
C:\apps\tdv84\jdk\bin\keytool -import -trustcacerts -alias tdvcert1 -file ROOT.cer -keystore C:\apps\tdv84\conf\server\security\cis_server_truststore.jks -storepass changeit
-------------------
11. If any other client applications are opening SSL connections to TDV, their truststores need to be updated
Any existing clients (e.g. JDBC clients) that open an SSL connection to TDV will need to have their truststores updated by importing the new certificate into their truststores.
Feedback
Yes
No
Powered by
