Import a private key to a TKS Key Store

If you have a file that includes a signed certificate with a private key, which does not match the private key currently in the ssl.tks Key Store, this procedure explains how to import the file into the existing ssl.tks Key Store for the JACE.

To complete this procedure you will need:

Administrator access to Windows.
The file that contains the certificates, and the private and public keys. This file is most likely a PKCS12-type file. Its file extension may be .p12 or .pfx or .pem.
The password to access this file should be provided with the file from the CA.
A text editor.

This section covers these procedures:

Set up OpenSSL

Download a copy of OpenSSL. When this Engineering Note was released, OpenSSL could be found at this internet location: https://code.google.com/p/openssl-for-windows/.
Extract the zip file to a location on the PC (for example, c:\ProgramFiles\openssl-0.9.8k_x64).
There is no installation file to run.
Update the Windows path variable to include the bin sub-folder of the extracted files from the previous step. (for example, c:\Program Files\openssl-0.9.8k_x64\bin).

If necessary, create a .pem file

The result of this procedure is a .pem file, which is required by the TKS Key Store. If you already have a .pem file, continue with Prepare the .pem file.

Save the Key Store file that contains the public and private keys and certificates to a working folder on your PC (for example, c:\NiagaraCerts\)
Open a Windows command prompt.
If the Key Store file is a PKCS12-type file, use OpenSSL to export the PKCS12 file to a .pem file using the following command:
```
openssl pkcs12 -in PKCS12_file -out PEM_file
```
where PKCS12_file is the name of the source PKCS12-type file, and PEM_file is the resulting file.

OpenSSL prompts you to enter the password for the PKCS12 Key Store and to double-enter a new password for the new .pem file.

Figure 7. Example—export PKCS12 file to a .pem file

Prepare the .pem file

Open the .pem file using a text file editor.
Look for and delete any extra text outside of the BEGIN and END marker lines that demarcate the private key and certificates.

Figure 8. Text to be deleted

In the example above, the first four lines related to the Bag Attributes need to be deleted.

Figure 9. Text to keep

The highlighted text above belongs in the file and should not be deleted. This text indicates that the key is encrypted and identifies the type of encryption used.

If Niagara AX 3.7 is available, you can use it to verify that the .pem file contains no unsupported text.
To test the file using NiagaraAX 3.7 or a newer build, view the file using PEM File View.

If the file contains only valid text, it displays information about the certificate.

Figure 10. Text from a valid .pem file as displayed using NiagaraAX 3.7 PEM File View

If the file contains unsupported text, the above screen is blank. If you see certificate information, your file contains no unsupported text.

Export the .pem file to a PKCS12 file

Using OpenSSL at a command prompt, enter this command:
```
openssl pkcs12 -export -PEM_file -out PKCS12_file
```
where PEM_file is the source file, and PKCS12_file is the name of the resulting PKCS12-type file.

Figure 11. Example—exporting a .pem file to a PKCS12 file

OpenSSL prompts you to enter the password you created for the .pem file in a previous step, or which was provided by the CA (if the .pem file was sent from the CA).
Install the TKS Provider and configure the JRE. For the procedure, see Install the TKS Provider.
Update the Windows path variable to include the bin sub-folder of the JRE installation.
Copy the ssl.tks file from the Workbench security sub-folder (file:!security/ssl.tks) to the working folder on your PC (for example, c:\NiagaraCerts\ssl.tks).

Import, verify and edit the Key Store

To import the source Key Store (PKCS12 file) to the TKS Key Store (ssl.tks file), execute this command at the command prompt:
```
keytool -importkeystore -srckeystore PKS_File -destkeystore TKS_file -srcstoretype src_store_type -deststoretype dest_store_type -srcalias src_alias -destalias dest_alias -deststorepass dest_store_password
```
where:
- PCKS_File is the name of the PKCS12-type file.
- TKS_file is the name of your TKS file, usually ssl.tks.
- src_store_type is PKCS12.
- dest_store_type is TKS.
- src_alias is the digit 1 (one).
- dest_alias is a name that represents the JACE you are configuring.
- dest_store_password is the password for the ssl.tks file. The default password is tridium. If the default password has changed, use the appropriate password.
Figure 12. Example—importing the Key Store
To verify that the key and certificate were imported, execute this command:
```
keytool -list -storetype store_type -keystore store_file -storepass store_password
```
where
- store_type is TKS.
- store_file is the name of your TKS file, usually ssl.tks.
- store_password is the password for the ssl.tks file. The default password is tridium. If the default password has changed, use the appropriate password.
Figure 13. Example—imported Key Store

The example above contains two private key entries. The first entry is the default private key with the alias tridium. This entry is no longer needed.

The second entry is the private key that was imported in this step. Its alias is vykon_jace_j9_v1.
To delete the private key with the tridium alias from the key store, execute this command:
```
keytool -delete -alias key_alias -storetype store_type -keystore store_file -storepass store_password
```
where:
- key_alias is tridium.
- store_type is TKS.
- store_file is ssl.tks.
- store_password is the password for the ssl.tks file. The default password is tridium. If the default password has changed, use the appropriate password..
Figure 14. Example—deleting the extra private key
To ensure security, change the password for the Key Store from tridium, to your own strong password by entering this command:
```
keytool -storepasswd -storetype store_type -keystore store_file -storepass store_password
```
where:
- store_type is TKS.
- store_file is ssl.tks.
- store_password is the password for the ssl.tks file. The default password is tridium. If the default password has changed, use the appropriate password.
The Keytool utility prompts you to double-enter a new password for the Key Store.

Figure 15. Example—changing the password

The key password and store passwords must be the same or you will receive a padding error when trying to start the https web service.
To change the key password to match the store password, execute this command:
```
keytool -keypasswd -alias key_alias -storetype store_type -keystore store_file -storepass store_password
```
where:
- key_alias is the name of your Key Store.
- store_type is TKS.
- store_file is ssl.tks.
- store_password is the password for the ssl.tks file. The default password is tridium. If the default password has changed, use the appropriate password.
Figure 16. Example—changing the key password
Copy the ssl.tks file to the security sub-folder of the desired host (file!security/ssl.tks).
To update the CryptoService properties in the station, see Configure CryptoService.

Make sure that the Key Store Password and Trust Store Password properties are configured with the new password you assigned in a previous step. The Trust Store and Key Store passwords must be the same.

Set up the browser

If the root certificate used to sign the server’s certificate is not from a well known CA whose root certificate is already in the browser’s trust store, you may need to import the root certificate into the browser Trust Store.

If the CA did not provide a copy of the root certificate, this procedure explains how to locate and prepare the certificate, and import it into the browser.

Open the .pem file you created in If necessary, create a .pem file using a text editor.
Locate the root certificate. It should be the last certificate in the chain.

Figure 17. Example of a root certificate
Copy the entire text of the root certificate including the BEGIN and END marker lines.
Create a new text file and paste the copied text into it.
Save the file using a .cer extension (for example, c:\NiagaraCerts\myLocalCaRoot.cer).
Use your browser tools to import this root certificate file into the client browser’s trust store.
Using the browser, make a secure connection to the station (https) and verify that the expected certificate is presented to the browser.

Figure 18. Certificate verified by the browser
If the station will be making SSL connections to other servers that are using certificates signed by the same CA’s root certificate, import the root certificate to the ssl.tks trust store using this command:
```
keytool -importcert -file root_cert_file -storetype store_type -keystore store_file -storepass store_password
```
where:
- root_cert_file is the name of the .cer file you received from the CA or created that contains the root certificate.
- store_type is TKS.
- store_file is ssl.tks.
- store_password is the password you created for the Key Store.
Figure 19. Example—root certificate imported into the TKS Key Store
If you imported the CA’s root certificate into the ssl.tks, copy the updated ssl.tks file to the host’s security sub-folder (file:!security/ssl.tks.