Installing a Truststore Certificate
This topic describes how to check for and install a certificate in a truststore.
To check for and if necessary install the certificate in the truststore
|
1.
|
In a browser, type the HTTPS URL of the TDV server. |
|
2.
|
Click the browser’s lock icon to view the certificate. |
This icon is usually to the left of the URL field in the browser header.
|
3.
|
Click the link to Certificate Information or View Certificate to see details. |
|
4.
|
Note the name of the party that the certificate is issued to. |
|
5.
|
Check the certification path to see how many certificates are in the chain. |
|
6.
|
In Studio, go to Administration > Configuration to open the configuration window. |
|
7.
|
Navigate to Server > Communications and find the following values: |
|
—
|
Truststore File Location (Current) |
|
—
|
Keystore Key Alias (Current) |
|
8.
|
Navigate to the location of the keytool utility: |
cd <TDV_install_dir>\jdk\bin
|
9.
|
Example of adding a certificate to the TDV Server truststore |
Windows: open cmd.exe as Administrator privilege. <TDV_install_dir>\jdk\bin\keytool.exe -list -keystore <TDV_install_dir>\conf\server\security\<truststore_file_name> | findstr <certificate_alias>
UNIX: <TDV_install_dir>/jdk/bin/keytool -list -keystore <TDV_install_dir>/conf/server/security/<truststore_file_name> | grep <certificate_alias>
note: example provided is for installing a certificate to the TDV Server truststore. path for -keystore would need to change for doing this operation for TDV BD, Studio, JBDC, ODBC or ADO.NET clients.
|
10.
|
Type the keystore password. |
The result should be a line with the name of the certificate, the date it was installed, and “trustedCertEntry.”
The string “trustedCertEntry” confirms that the certificate is a trusted root in the truststore. If that string is not present, continue with the next steps to copy the certificate chain to the truststore.
|
11.
|
Save the certificate chain (which you found in an earlier step) by copying it to a CAR file. |
|
12.
|
Use the browser’s utility (for example, its certificate export wizard) to save the file in a directory location where you can retrieve it later. |
|
—
|
DER-encoded binary X.509 (.CER) is a recommended format. |
|
13.
|
Example of importing the certificate chain into the TDV Server truststore |
Windows: open cmd.exe with Administrator privilege. <TDV_install_dir>\jdk\bin\keytool.exe -keystore <TDV_install_dir>\conf\server\security\<truststore_file_name> -import -alias <certificate_alias> -trustcacerts -file <CER_file>
UNIX: <TDV_install_dir>/jdk/bin/keytool -keystore <TDV_install_dir>/conf/server/security/<truststore_file_name> -import -alias <certificate_alias> -trustcacerts -file <CER_file>
Troubleshooting
You might encounter situations where you cannot make an SSL connection to the TDV server. This topic discusses a few of them.
|
•
|
If you repeatedly receive an error like “PKIX path building failed” or “Unable to find valid certification path to requested target,” go back to Installing a Truststore Certificate and repeat the steps in which you use keytool to see whether the certificate is present in the truststore file. |
|
•
|
If the certificate entry in the truststore file is marked “trustedCertEntry” but you are still receiving certificate errors, probably your browser has not exported the complete certificate chain into C:\temp\mycertificate.cer. |
|
•
|
If the existing truststore contains too many certificate entries, you may want to remove it and create a new one. For the procedure, refer to Creating a New Truststore File. |
Creating a New Truststore File
Under certain circumstances you can remove the truststore and create a new one.
To create a new truststore file
|
14.
|
If you want to remove an existing truststore file, back it up first and then remove it. |
|
15.
|
Use keytool to create the new truststore file: |
<TDV_install_dir>\jdk\bin\keytool
-genkey
-alias <alias_for_your_truststore_file>
-keystore <TDV_install_dir>\conf\studio\security\<truststore_file_name>
note: example provided is for TDV Studio.
|
16.
|
Check the contents of the new file: |
<TDV_install_dir>\jdk\bin\keytool
-list
-keystore <TDV_install_dir>\conf\studio\security\<truststore_file_name>
The new file should contain one entry:
cis_studio, May 7, 2016, PrivateKeyEntry,
Certificate fingerprint (MD5): 01:12:23:34:45:56:67:78:89:9A:AB:BC:CD:DE:EF:FE
note: example provided is for TDV Studio.