Install a signed certificate

When a station that contains CryptoService boots, the software creates a self-signed certificate, which can be used to encrypt https data. To strengthen system security, it is better to use an actual signed certificate for each server (JACE). In addition to encryption, signed certificates provide identity verification.

Certificates may be signed by a third-party Certificate Authority (CA) or you may serve as your own CA by creating a self-signed root certificate and using it to sign your server certificates.

The procedures that follow use the Oracle® Keytool utility to create server certificates, generate Certificate Signing Requests (CSRs) and import signed certificates. To actually sign your own certificates, you need OpenSSL, the Niagara AX 3.7 SSL Toolkit, or some other third-party application.

Serving as your own CA will provide secure communications if and only if you physically guard the root certificate’s private key. Consider storing the computer used to sign server certificates in a vault or other secure location. Never send the root certificate’s private key as an email attachment and be careful to exclude the private key when exporting a root certificate to a thumb drive or other storage device.

This section covers these procedures and sections:

For a summary of the most likely Keytool options, see Keytool options. Comprehensive help for using Keytool is available on Oracle’s web site (at current writing: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html). For more information about how CryptoService works, see How it works.

Generate the key pair for the certificate request

A “key pair” refers to a set of private and public software keys used to encrypt data and to verify identity

Open a command prompt and make sure that jre/bin is in your PATH.
Change directories to the security directory for your Niagara installation.
As a backup, rename the existing ssl.tks file to ssl.tks.orig.
Run the keytool utility with the following command:
```
keytool -genkey -alias tridium -keystore ssl.tks -storepass
tridium -storetype TKS -keyalg RSA -keysize 2048
```
It may be necessary to adjust the -keyalg and -keysize arguments based on the requirements of your Certificate Authority.
When prompted for your first and last name, enter the base domain name of the dns entry for your server, for example, tridium.com.
Answer the remaining questions as accurately as possible.
When prompted to enter a password for the key pair, press Enter to use the Key Store password.
As a backup, make a copy of the new ssl.tks, naming it ssl.tks.new.

Generate the certificate request

Create the Certificate Signing Request (CSR) using this command:
```
keytool -certreq -alias tridium -keystore ssl.tks -storepass
tridium -file certreq.cer -storetype TKS
```
This creates a new file called certreq.cer.
Submit this CSR file to your Certificate Authority (CA) along with any other information they require.

When the CA completes the signing process, you will receive an email or a file that looks something like this:

Figure 6. Certificate chain
Save this certificate chain to a file and give it a name, such as certchain.cer.

Import the signed certificate

Run the following command on the same Key Store that you used to generate the initial CSR.

keytool -importcert -trustcacerts -file certchain.cer -keystore
ssl.tks -storepass tridium -storetype TKS -alias tridium

If a message indicates that this certificate is not trusted, “Install reply anyway?” click Yes.

Check the Key Store

Dump the contents of the Key Store with the following command:

keytool -list -alias tridium -keystore ssl.tks -storepass
tridium -storytype TKS -V

The first few lines should read something like:

Alias name: tridium
Creation date: July 31, 2014
Entry type: PrivateKeyEntry

Verify that the third line reads, PrivateKeyEntry.
Look for the Owner and Issuer lines in the first certificate. For example:
```
Certificate[1]:
Owner: CN=foo.com, OU=engineering, O=tridium,
L=richmond, ST=virginia, C=us
Issuer: C=us, ST=virginia, L=richmond, O=tridium,
OU=engineering, CN=intermediateca
```
Quick reference to the acronyms:
- CN = Common Name is the domain name for which the certificate will be used including the subdomain. This is a required field.
- OU = Organizational Unit name is the full name of the organization or department.
- O = Organization name is the full name of the organization.
- L = Locality name is the geographical city or town where you or your organization resides.
- ST = The full name of the state or province for you or your organization.
- C = the capitalized, two-letter country code for you or your organization.
Verify that the owner is the end certificate that you signed.

Look through each subsequent certificate to make sure that the Owner is the same as the Issuer on the previous certificate. For example:

Certificate[2]:
Owner: C=us, ST=virginia, L=richmond, O=tridium,
OU=engineering, CN=intermediateca
Issuer: c=us, ST=virginia, L=richmond, O=tridium,
OU=engineering, CN=rootca

Verify that the last certificate is a self-signed certificate where the owner and issuer are the same. For example:
```
Certificate[3]:
Owner: C=us, ST=virginia, L=richmond, O=tridium,
OU=engineering, CN=rootca
Issuer: C=us, ST=virginia, L=richmond, O=tridium,
OU=engineering, CN=rootca
```
Your ssl.tks now contains a signed certificate.
Additional information:
- The signed certificate you installed only validates correctly the domain for which you created it. Do not attempt to use this certificate on another domain.
- Your Certificate Authority may have other requirements and instructions, and should be able to assist you with any trouble.
- The certificate chain must be installed into the Key Store that contains the matching private key entry.