This article was imported from Niagara Central Community.
Chain of Trust
This document will focus on setting up the 'Chain of trust' in a PEM file and then importing that PEM in the Niagara ‘User Key Store’, thus completing the certificate signing process. This ‘Chain of Trust’ has nothing to do with the Niagara framework. We have provided some tools to try to help users configure SSL/TLS, but they must follow the SSL/TLS rules when setting things up. A PEM file contains the key and certificate(s) that build this chain of trust. This document is going to repeat several times the order of the 'Chain of trust' and also stress that you typically need to construct a master ‘.pem’ text file to be imported into the station’s Key Store.
You are creating a master PEM file that contains all the pieces that result in a signed, trusted certificate. You want to make sure that the '.pem' has the 'Chain of trust' correctly laid out in the file.
The chain of trust is below. You can search the web on that topic, but the typical order in the master PEM file to be imported into Niagara is-
This document will focus on setting up the 'Chain of trust' in a PEM file and then importing that PEM in the Niagara ‘User Key Store’, thus completing the certificate signing process. This ‘Chain of Trust’ has nothing to do with the Niagara framework. We have provided some tools to try to help users configure SSL/TLS, but they must follow the SSL/TLS rules when setting things up. A PEM file contains the key and certificate(s) that build this chain of trust. This document is going to repeat several times the order of the 'Chain of trust' and also stress that you typically need to construct a master ‘.pem’ text file to be imported into the station’s Key Store.
You are creating a master PEM file that contains all the pieces that result in a signed, trusted certificate. You want to make sure that the '.pem' has the 'Chain of trust' correctly laid out in the file.
The chain of trust is below. You can search the web on that topic, but the typical order in the master PEM file to be imported into Niagara is-
- Private Key
- You export the private key from the certificate you created using the Workbench Certificate Manager tool. Make sure to export the key in an unencrypted format.
- The private key is the first entry of the master PEM file you are creating.
- The private key is optional when importing a certificate created by the Niagara Certificate Manager and signed using Workbench Certificate Signer Tool.
- Primary Certificate
- This is the signed certificate that was signed using Workbench Signer Tool or received back from the signing authority. You have either signed your certificate with a CA created using Workbench Certificate Manager, or you have a signed certificate that was signed by a signing authority using the signing request sent to them.
- Intermediate Certificate
- If using intermediate certificates.
- If using a signing authority that has intermediate certificates, they would send them with the primary certificate that they signed.
- Root Certificate
- This was used to sign the Primary Certificate
- Note that you may need to export the Signing Authority CA from the Workbench Trust Store and include that CA as the last certificate in the master PEM. This can be the case if you are using a customer’s certificate and nothing was generated using Niagara and all is being supplied from an external source.
- If you sent a signing request to a signing authority the resulting PEM they returned usually contains everything needed except your private key. You would receive back a PEM that contained the signed certificate, any intermediate certificates and the Signing Authority’s root CA. Add your private key at the top of this file and import into Niagara User Key Store.
N4 and AX versions to use
When configuring SSL/TLS you should be using the most recent version of N4 (N4.8 and above is recommended) and AX 3.7.106 or higher (3.8.401 or above recommended). These builds contain the most current SSL/TLS support that supports Foxs and secure platform connections.
Note that versions of AX 3.6 and below only support HTTPS and do not have Foxs and secure platform connections.
Editing and viewing PEM and CERTs
Remember that you can use Workbench to view certs and pem files. Just go to 'My host' and locate the files, then right click and use the 'Pem file' view to see the contents of the file. But if they are building up the pem file, then view the files using the text editor view.
The root certificate (CA) is imported into the 'System Trust store'.
The '.pem' you construct is imported into the 'User Key Store'.
What to do with a .CER file received back from the Signing Authority
Often the file sent by the Signing Authority is in a binary format (‘.der’ or ‘.cer’).
In the case of a binary file, the extension will be ‘.der’ or ‘.cer’. These files need to be converted to the ‘.pem’ text format. There are several websites (found with a browser search engine) that provide this file conversion as a free service. You use those at your own risk. We have had good luck using https://www.rapidsslonline.com/ssl-tools/ssl-converter.php, but Tridium DOES NOT ENDORSE ANY WEBSITE CONVERSION TOOL. Again, use at your own risk.
Also check with the signing authority to see if a PEM formatted file is available.
You can also perform the file conversion using the ‘OpenSSL’ tool.
Problem
Convert standard format certificate (x.509 .der or .cer) into PEM format
Solution
OpenSSL can be used to convert a standard format certificate (X.509) into a PEM format certificate.
The command line to use is:
openssl x509 -in certFileName.cer -outform PEM -out convertedCertFileName.pem
To download OpenSSL, go to http://www.openssl.org/
Once you have the binary version of your certificate, you are going to be importing a master PEM file into your station, using that station’s Certificate Manager. You create a master PEM file by combining the certificate info from the Signing Authority file, along with text from any other '.pem' files you previously created using Workbench Certificate Manager, such as any intermediate certificates and the key. Also keeping in mind to keep the text from each file in the correct order.
The ‘.pem’ file is just a text file containing the signing authority certificate, your certificate and the key. To combine the various certs, and the key, you would open the different files using Workbench in a text editor, not a pem editor, so you can copy out the whole certificate for pasting to the master pem file. If you just want to read the certificate, to verify contents, then open using the pem editor. To copy the certificate, so you can then paste it into some master pem you are building up, open the certs in the text editor. In a text editor you will see the 'BEGIN' and 'END' with all the garbage in between. That is what goes into the master '.pem'.
There are many companies that provide digital certificates and signing. You can visit their websites and typically they have helpful information about creating ‘.pem’ files. You can visit DigiCert©, Verisign© and Entrust© websites (to name a few) to search for more information. Tridium does not endorse any signing authority.
MASTER PEM FILE-
In a nut shell, you just copy the Private Key, Primary certificate, any intermediate certificates and the root certificate into the same text file. This master file would have a ‘.PEM’ extension. Import this file into the Niagara User Key Store.
Example PEM file
Below is a text editor view of a master '.pem' files. You must include the BEGIN and END statements when you copy the text to build up a master PEM file. You could also copy in the key as well. Note that this PEM contains the private key at the top, next the signed certificate and finally the Root CA. This example only contains the text received back from the signing authority and the private key that was exported using Workbench Certificate Manager. There were no intermediate certificates.
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEA0RnGr8nSCBDoX/v5OB6VMWmp+uokLlu0Jz41ro9ryUcY6QCZ
YsdzzKWsZZfwYlON/9VlGV4t93xXkn26Nq7t+5yZeJ3BowwI4iE3XMspHnqiIY2+
6yS6bQ/56/7Wq9lnxRZC8IrEc/IJ+wQaM+jVNMsOChd5twXhlwTeojj3roc6rv+h
Vx8tedELkaGIT6IuEWtHZiugS7y7/koA2OTtSobE4dGKbra2AOWtCsYk5NBeivzz
xF1IMjWN2gWKixSH943G3t2Bv90F61CgtO/K+l2auNroXlpDzArfcSjIJY7llNpm
dAblEjveWXaP32ysKgalp2Ax4OGQq4FRrNOg0cblncHQAqKNAo0NeIBs/b6A+hPC
+Y88a6tg606ATqzegMB/yuOlp0S4Lz81NgCJN1kM8BNdlgfx9Idg7cK2uih9vpKq
rgOw8LOSFFB9C/q+6H9+gwwOadL06bAKMLb+rxMCgYBcHfFxIIYdnGRZaR9o4Q6j
SnT4AUPmKHQaatI8P+coRRiXyj1XDhzGmyjPuGmdTxG3ADQYAFrRT9eeyxRZIYcW
b9hRMRGt+Na0+RTJqaTnq1oLm1fQYFP44LuayijQYnFRLvSnj8uPk/IPmx+GYygj
1f/nAoGAFjDIGSApiGtg8NOr7nM1fiRMZMnmZkeSHshWoJABBRLrVaVuALv2RCSf
XgI+cA9b732Tx0PiC8aZnIe8cS9RjGj44cu8q4pksCy6fgzBgQSCu5ud0v4Hv6N8
KKdOFB6YM3ji/nt9KsH8CjN9q2867aAo5WQztAf7nEGISEqiAJY=
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIID9jCCAt6gAwIBAgIMSVQFjgsqLXywMzESMA0GCSqGSIb3DQEBCwUAMGkxFjAU
BgNVBAMMDTE3Mi4xNi4xMC4yNDExEDAOBgNVBAsMB1N1cHBvcnQxEDAOBgNVBAoM
B1RyaWRpdW0xETAPBgNVBAcMCFJpY2htb25kMQswCQYDVQQIDAJWQTELMAkGA1UE
BhMCVVMwHhcNMTkxMTEyMTkxNTUxWhcNMjAxMTExMTkxNTUxWjBpMRYwFAYDVQQD
BQrtnYdkbWcJi9ahIdnxrT2ibgYPnwYcG9yP2CwQR9i94NMulESp6VqSHq4U+NlL
bngtTlBNNi0wMDAwLTE0QTItOUE3ODANBgkqhkiG9w0BAQsFAAOCAQEAMF9D4wI6
KyQLm+ccLzX4GElQhjUA1PEradONF3YG93MrCEOeUUAyyF7yBr/9faduPW2mHHay
zKLFOLLlv2Pnha/zPWqy+cWtP2J5pPfHctkE6VUlBgqd8Hkvl/+LeWdQj3ZDnAc5
fMXmXH9lWRqNpReIxuWI3ACexYwJnO3f0DOWFXyqJus0GA+O2vidRStVDZDu+UGx
t8JZk40+a28G3AgwmtRetvsR4EUGD5qOYMZ5YuDrsQjpdz/48yWrzwMmZJxm15/V
C31PvxBHkI1LWAaFTTxi2Vy+v34VtaOB/0vwrLItTuzKrFJiICPsj6uhQVLW6esY
0uDHOQxlw/ybwQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDgTCCAmmgAwIBAgIMSFgFm9NKiIW5uwtWMA0GCSqGSIb3DQEBCwUAMDIxETAP
BgNVBAMMCE5pYWdhcmE0MRAwDgYDVQQKDAdUcmlkaXVtMQswCQYDVQQGEwJVUzAe
Fw0xOTA5MDUxMzAxMDNaFw0yMDA5MDUxMzAxMDNaMDIxETAPBgNVBAMMCE5pYWdh
BgNVHQ4EFgQU83fA8BGg6zDsgtt6JNQHWg5n1zEwHQYDVR0lBBYwFAYIKwYBBQUH
OTANBgkqhkiG9w0BAQsFAAOCAQEAIaKTt8To5tfB1CVV+5AWBoDHovrjRCP2yiz/
z+U8qYSj+LmFFKwv0qMUATGwtPIPlLZBWm95CtDJzRSZQ0DadQtbCy4Wq6NCRqs0
T35ECqVZMJgX/Zgfgg0K+GR1iuN6bdD7FEfUD2L9MfkV9xcW9c+DQwovs9XInqwc
AR4iMLLHNlLWAOvn1XxY6s3loDvYbDDUGW/VEVJS1tPCX/3mNVd50TaYKWkV9Qih
0C41ZQVEvLCz/zYuqbsYkhwUTgK6/qjy3gt+VddLrCY+1UD/4pFYwY8nJ7nGkioM
5jnnwCKnyzMURiT9hvUNt6eYCiPFTUrQ9mGWhKFh0p0DsQXBDg==
-----END CERTIFICATE-----
NOTE:
Each JACE within a Niagara network requires its own unique private key and signed server certificate, which is stored in its Key Store.
Each client within a Niagara network requires a copy of the CA (root) certificate used to sign the server’s certificate for any servers to communicate securely within the network. These certificates reside in the client Trust Store. One certificate may be used to secure Fox station communication, Web Service and Niagarad or each service may have its own server certificate and pair of keys.
The number of certificates you need depends on the number of platforms in your network and the type of communication you need to secure.
You could use one certificate and import into all hosts (a wildcard certificate), but this is not as secure. If one host becomes compromised, they are all compromised.
Creating a signed certificate using Niagara Workbench-
In the example below Workbench is being used to generate server certificates, a Root CA and to sign all the certificates using the Root CA. In setting up SSL, you create a root CA (you can also create intermediate CA’s), then use either the root or intermediate CA to sign all of the server certificates you create for each Jace and the Supervisor.
Steps/notes-
When configuring SSL/TLS you should be using the most recent version of N4 (N4.8 and above is recommended) and AX 3.7.106 or higher (3.8.401 or above recommended). These builds contain the most current SSL/TLS support that supports Foxs and secure platform connections.
Note that versions of AX 3.6 and below only support HTTPS and do not have Foxs and secure platform connections.
Editing and viewing PEM and CERTs
Remember that you can use Workbench to view certs and pem files. Just go to 'My host' and locate the files, then right click and use the 'Pem file' view to see the contents of the file. But if they are building up the pem file, then view the files using the text editor view.
The root certificate (CA) is imported into the 'System Trust store'.
The '.pem' you construct is imported into the 'User Key Store'.
What to do with a .CER file received back from the Signing Authority
Often the file sent by the Signing Authority is in a binary format (‘.der’ or ‘.cer’).
In the case of a binary file, the extension will be ‘.der’ or ‘.cer’. These files need to be converted to the ‘.pem’ text format. There are several websites (found with a browser search engine) that provide this file conversion as a free service. You use those at your own risk. We have had good luck using https://www.rapidsslonline.com/ssl-tools/ssl-converter.php, but Tridium DOES NOT ENDORSE ANY WEBSITE CONVERSION TOOL. Again, use at your own risk.
Also check with the signing authority to see if a PEM formatted file is available.
You can also perform the file conversion using the ‘OpenSSL’ tool.
Problem
Convert standard format certificate (x.509 .der or .cer) into PEM format
Solution
OpenSSL can be used to convert a standard format certificate (X.509) into a PEM format certificate.
The command line to use is:
openssl x509 -in certFileName.cer -outform PEM -out convertedCertFileName.pem
To download OpenSSL, go to http://www.openssl.org/
Once you have the binary version of your certificate, you are going to be importing a master PEM file into your station, using that station’s Certificate Manager. You create a master PEM file by combining the certificate info from the Signing Authority file, along with text from any other '.pem' files you previously created using Workbench Certificate Manager, such as any intermediate certificates and the key. Also keeping in mind to keep the text from each file in the correct order.
The ‘.pem’ file is just a text file containing the signing authority certificate, your certificate and the key. To combine the various certs, and the key, you would open the different files using Workbench in a text editor, not a pem editor, so you can copy out the whole certificate for pasting to the master pem file. If you just want to read the certificate, to verify contents, then open using the pem editor. To copy the certificate, so you can then paste it into some master pem you are building up, open the certs in the text editor. In a text editor you will see the 'BEGIN' and 'END' with all the garbage in between. That is what goes into the master '.pem'.
There are many companies that provide digital certificates and signing. You can visit their websites and typically they have helpful information about creating ‘.pem’ files. You can visit DigiCert©, Verisign© and Entrust© websites (to name a few) to search for more information. Tridium does not endorse any signing authority.
MASTER PEM FILE-
In a nut shell, you just copy the Private Key, Primary certificate, any intermediate certificates and the root certificate into the same text file. This master file would have a ‘.PEM’ extension. Import this file into the Niagara User Key Store.
Example PEM file
Below is a text editor view of a master '.pem' files. You must include the BEGIN and END statements when you copy the text to build up a master PEM file. You could also copy in the key as well. Note that this PEM contains the private key at the top, next the signed certificate and finally the Root CA. This example only contains the text received back from the signing authority and the private key that was exported using Workbench Certificate Manager. There were no intermediate certificates.
-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEA0RnGr8nSCBDoX/v5OB6VMWmp+uokLlu0Jz41ro9ryUcY6QCZ
YsdzzKWsZZfwYlON/9VlGV4t93xXkn26Nq7t+5yZeJ3BowwI4iE3XMspHnqiIY2+
6yS6bQ/56/7Wq9lnxRZC8IrEc/IJ+wQaM+jVNMsOChd5twXhlwTeojj3roc6rv+h
Vx8tedELkaGIT6IuEWtHZiugS7y7/koA2OTtSobE4dGKbra2AOWtCsYk5NBeivzz
xF1IMjWN2gWKixSH943G3t2Bv90F61CgtO/K+l2auNroXlpDzArfcSjIJY7llNpm
dAblEjveWXaP32ysKgalp2Ax4OGQq4FRrNOg0cblncHQAqKNAo0NeIBs/b6A+hPC
+Y88a6tg606ATqzegMB/yuOlp0S4Lz81NgCJN1kM8BNdlgfx9Idg7cK2uih9vpKq
rgOw8LOSFFB9C/q+6H9+gwwOadL06bAKMLb+rxMCgYBcHfFxIIYdnGRZaR9o4Q6j
SnT4AUPmKHQaatI8P+coRRiXyj1XDhzGmyjPuGmdTxG3ADQYAFrRT9eeyxRZIYcW
b9hRMRGt+Na0+RTJqaTnq1oLm1fQYFP44LuayijQYnFRLvSnj8uPk/IPmx+GYygj
1f/nAoGAFjDIGSApiGtg8NOr7nM1fiRMZMnmZkeSHshWoJABBRLrVaVuALv2RCSf
XgI+cA9b732Tx0PiC8aZnIe8cS9RjGj44cu8q4pksCy6fgzBgQSCu5ud0v4Hv6N8
KKdOFB6YM3ji/nt9KsH8CjN9q2867aAo5WQztAf7nEGISEqiAJY=
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIID9jCCAt6gAwIBAgIMSVQFjgsqLXywMzESMA0GCSqGSIb3DQEBCwUAMGkxFjAU
BgNVBAMMDTE3Mi4xNi4xMC4yNDExEDAOBgNVBAsMB1N1cHBvcnQxEDAOBgNVBAoM
B1RyaWRpdW0xETAPBgNVBAcMCFJpY2htb25kMQswCQYDVQQIDAJWQTELMAkGA1UE
BhMCVVMwHhcNMTkxMTEyMTkxNTUxWhcNMjAxMTExMTkxNTUxWjBpMRYwFAYDVQQD
BQrtnYdkbWcJi9ahIdnxrT2ibgYPnwYcG9yP2CwQR9i94NMulESp6VqSHq4U+NlL
bngtTlBNNi0wMDAwLTE0QTItOUE3ODANBgkqhkiG9w0BAQsFAAOCAQEAMF9D4wI6
KyQLm+ccLzX4GElQhjUA1PEradONF3YG93MrCEOeUUAyyF7yBr/9faduPW2mHHay
zKLFOLLlv2Pnha/zPWqy+cWtP2J5pPfHctkE6VUlBgqd8Hkvl/+LeWdQj3ZDnAc5
fMXmXH9lWRqNpReIxuWI3ACexYwJnO3f0DOWFXyqJus0GA+O2vidRStVDZDu+UGx
t8JZk40+a28G3AgwmtRetvsR4EUGD5qOYMZ5YuDrsQjpdz/48yWrzwMmZJxm15/V
C31PvxBHkI1LWAaFTTxi2Vy+v34VtaOB/0vwrLItTuzKrFJiICPsj6uhQVLW6esY
0uDHOQxlw/ybwQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDgTCCAmmgAwIBAgIMSFgFm9NKiIW5uwtWMA0GCSqGSIb3DQEBCwUAMDIxETAP
BgNVBAMMCE5pYWdhcmE0MRAwDgYDVQQKDAdUcmlkaXVtMQswCQYDVQQGEwJVUzAe
Fw0xOTA5MDUxMzAxMDNaFw0yMDA5MDUxMzAxMDNaMDIxETAPBgNVBAMMCE5pYWdh
BgNVHQ4EFgQU83fA8BGg6zDsgtt6JNQHWg5n1zEwHQYDVR0lBBYwFAYIKwYBBQUH
OTANBgkqhkiG9w0BAQsFAAOCAQEAIaKTt8To5tfB1CVV+5AWBoDHovrjRCP2yiz/
z+U8qYSj+LmFFKwv0qMUATGwtPIPlLZBWm95CtDJzRSZQ0DadQtbCy4Wq6NCRqs0
T35ECqVZMJgX/Zgfgg0K+GR1iuN6bdD7FEfUD2L9MfkV9xcW9c+DQwovs9XInqwc
AR4iMLLHNlLWAOvn1XxY6s3loDvYbDDUGW/VEVJS1tPCX/3mNVd50TaYKWkV9Qih
0C41ZQVEvLCz/zYuqbsYkhwUTgK6/qjy3gt+VddLrCY+1UD/4pFYwY8nJ7nGkioM
5jnnwCKnyzMURiT9hvUNt6eYCiPFTUrQ9mGWhKFh0p0DsQXBDg==
-----END CERTIFICATE-----
NOTE:
Each JACE within a Niagara network requires its own unique private key and signed server certificate, which is stored in its Key Store.
Each client within a Niagara network requires a copy of the CA (root) certificate used to sign the server’s certificate for any servers to communicate securely within the network. These certificates reside in the client Trust Store. One certificate may be used to secure Fox station communication, Web Service and Niagarad or each service may have its own server certificate and pair of keys.
The number of certificates you need depends on the number of platforms in your network and the type of communication you need to secure.
You could use one certificate and import into all hosts (a wildcard certificate), but this is not as secure. If one host becomes compromised, they are all compromised.
Creating a signed certificate using Niagara Workbench-
In the example below Workbench is being used to generate server certificates, a Root CA and to sign all the certificates using the Root CA. In setting up SSL, you create a root CA (you can also create intermediate CA’s), then use either the root or intermediate CA to sign all of the server certificates you create for each Jace and the Supervisor.
Steps/notes-
- Create the Root CA. the ‘Alias’ can be anything and typically named so you know it is the Root CA (example- MyJobRootCA). The common name can also be the Alias name.
- Create an intermediate CA if you want to use an intermediate to sign all the server certificates. This is optional.
- Make sure all of the CA’s reside in a folder separate from the server certificates you will create next. Makes it easier to find the server certificates when you go so sign a server certificate with the Signing Tool.
- Now create a server certificate for each Jace and the supervisor. Save these files into folders for each station (I name the folder the station name).
- The alias can be any name. Name these server certs a name that lets you know it is a server cert. Maybe name it the station name and append ‘ServerCert’ to the end.
- The CN can be the LAN domain.
- The SAN can be the station’s IP address.
- Fill in all other required fields.
- Request a CSR for each of these server certificates.
- Easiest work flow to do this just after creating the server cert. As you create the CSR, save it in the same folder you created for each Jace or supervisor. Makes it easier to find the files for each station you are working with.
- Now use the signing tool to sign the server certificates.
- Use the newly signed PEM file to import back into the User Key Store to complete the signing process of the certificate(s).
- After you have signed the server cert for a station, make sure to go into the foxService and webService property sheets of that station and select the correct server certificate in the drop down.
- Make sure to set Foxs to ‘enabled’ for the Fox service and also in the client of each Niagara Station under the Niagara Network.
- Make sure that HTTPS is enabled in the webservice.
- Make sure to IMPORT the root certificate that was used to sign the certificates into every Jace and supervisor Trust store.
- You might need to disable, then re-enable Fox so that it can perform the SSL handshake. This makes sure that Fox has restarted using the new certificate, disconnecting and reconnecting.
HOW TO SIGN YOUR CERTIFICATE USING A SIGNING AUTHORITY
If you are using a signing authority such as Digicert you will be sending them the Certificate Signing Request that you generated using Workbench Certificate Manager. Then Digicert will sign your certificate and send back the signed certificate in a file usually having a .CER extension. You can either convert that .CER file into a PEM format, or you can visit their website and download the PEM format version of the same file. The final file must be in PEM format. This PEM file will contain your signed certificate and their ROOT CA that was used to sign the certificate. It is almost ready to import into Niagara. The only thing missing from this PEM is the private key from your original certificate that you generated using Workbench. The final step in creating the master PEM for import is to add the unencrypted private key to the beginning of master PEM, then import the PEM into Niagara User Key Store. If all is correct your certificate will change from a yellow to green check mark.
WHAT IF THE CUSTOMER HAS THEIR OWN CERTIFICATE?
What if the customer has their own signed certificate from some signing authority and doesn’t want to generate one using the Niagara Certificate Manager. The steps for importing a PEM into the User Key Store will still apply. What is a bit different is they will need a PEM that contains the complete chain of trust for their certificate, and it must have the private key at the top. Normally the private key is optional, but that is when you have created the certificate on the Jace (or Supervisor), so the private key is already there. In the case of their own certificate, the Jace is not going to know the private key until it is imported via the PEM.
As with all other certificates, you will need to import the CA related to the certificate into the System Trust Store. If they had used Verisign©, the Verisign© CA needs to be in the Trust Store (and it probably already is there).
Finally, you will need to export that same CA (from the Signing Authority) from the Workbench System Trust Store and include that as the last certificate in the master PEM you are building.
The order of the master PEM would be-
- Private Key from Signing Authority
- Primary Certificate from Signing Authority
- Intermediate Certificate (if supplied) from Signing Authority
- Exported CA from Workbench System Trust Store of that Signing Authority
EXAMPLE PEM FILE EDIT AND EXPLANATION-
The main thing that you want to look at is the “IssuerDN” and “SubjectDN” lines. The “Issuer” is the entity that signed the certificate, whereas the “Subject” is the entity represented by the certificate.
So, if the “IssuerDN” and “SubjectDN” match up, that means it’s a self-signed cert, and it’s the root. If they don’t match up, it’s either the server certificate, or an intermediate CA. To know which of those it is, you can look towards the bottom of the certificate – there will be a line in the “Extensions” section that says something along the lines of “BasicConstraints: isCA (true)” if it’s a CA. If it’s not, I think that line just isn’t there at all.
You want the order in the cert file to be:
- Private Key
- Server cert at the top
- Intermediate CAs in the middle
- Root CA at the bottom
If there are multiple intermediate CAs, you need to make sure that each cert is signed by the cert that comes directly below it. So, if I have:
- Private Key
- Signed server cert from signing authority
- IntermediateCA1
- IntermediateCA2
- RootCA (See Root Certificate in Glossary)
I would want to make sure that:
- IntermediateCA2’s “IssuerDN” is the same as RootCA’s “SubjectDN”
- IntermediateCA1’s “IssuerDN” is the same as IntermediateCA2’s “SubjectDN”.
GLOSSARY
Alias (in Server Certificate)-
All keystore entries are accessed via unique aliases. Aliases are case-insensitive, meaning the aliases Hugo and hugo would refer to the same keystore. The alias name does not matter as long as they are all unique inside the keystore.
Common Name (AKA CN) –
Represents the server name protected by the SSL certificate. The certificate is valid only if the request hostname matches the certificate common name. Most web browsers display a warning message when connecting to an address that does not match the common name in the certificate. Usually you make the common name match the fully qualified domain name.
CSR –
A certificate signing request (also CSR or certification request) is a message sent from an applicant to a certificate authority in order to apply for a digital identity certificate.
In Niagara this is a file generated when you make a ‘Cert Request’ in the Certificate Manager. You send the CSR to the signing authority and they generate the signed certificate. Or you use the CSR when signing the certificates yourself using Workbench tools or openSSL.
Intermediate Certificate –
There are two types of certificate authorities (CAs), root CAs and intermediate CAs. In order for a certificate to be trusted, and often for a secure connection to be established at all, that certificate must have been issued by a CA that is included in the trusted store of the device that is connecting. You can view the Workbench Trust Store using the Certificate Manager.
If the certificate was not issued by a trusted CA, the connecting device (e.g., a web browser) will then check to see if the certificate of the issuing CA was issued by a trusted CA, and so on until either a trusted CA is found (at which point a trusted, secure connection will be established) or no trusted CA can be found (at which point the device will usually display an error).
Private Key –
In cryptography, a private or secret key is an encryption/decryption key known only to the party or parties that exchange secret messages. In traditional secret key cryptography, a key would be shared by the communicators so that each could encrypt and decrypt messages.
In Niagara you will be exporting the unencrypted private key of your certificate and using it in the master PEM file you create that contains the signed certificate and private key. The master PEM is imported into the User Key Store to complete the signing of your certificate.
Root Certificate (CA) –
In cryptography and computer security, a root certificate is an unsigned or a self-signed public key certificate that identifies the Root Certificate Authority. Digital certificates are verified using a chain of trust. The trust anchor for the digital certificate is the Root Certificate Authority (CA).
The Root Certificate is what is used to sign the server certificate.
If you are signing your own certificates you would create your own Root CA.
If you are using a signing authority to sign the server certificates you need to have that authority’s CA in the Workbench and Browser trust store (they are typically already there). You would also include the Root CA as the last entry of your master PEM to be imported.
Server Certificate –
Certificate servers validate, or certify, keys as part of a Public key infrastructure. Keys are strings of text generated from a series of encryption algorithms that allow you to secure communication for a group of users. You create the server certificate and then generate a CSR for that certificate which is sent to the authority for signing.
Subject Alternative Name (SAN)-
The Subject Alternative Name field lets you specify additional host names (sites, IP addresses, common names, etc) to be protected by a single SSL certificate. We have discovered that when a signing authority encounters an IP address in the SAN it converts that IP to some URL that will not work. We think this is due to the fact an IP address cannot be validated. If you are signing the certificates using Workbench Signer Tool then an IP address should work.
THIS NEXT SECTION CONTAINS ERRORS THAT CAN BE ENCOUNTERED DURING PEM IMPORT-
This error was encountered importing signed cert. This exception happens when the alias doesn’t match the cert request and signed cert.
java.security.UnrecoverableKeyException: unable to recover key
at com.tridium.platcrypto.fox.BCryptoChannel.keyStoreGetKey(BCryptoChannel.java:537)
at com.tridium.platcrypto.fox.ChannelKeyStore.getKey(ChannelKeyStore.java:124)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:223)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:398)
at javax.baja.ui.Command.doInvoke(Command.java:313)
at javax.baja.ui.Command.invoke(Command.java:283)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:556)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1201)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:305)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:279)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:115)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:88)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:548)
at java.awt.Component.processEvent(Unknown Source)
at java.awt.Container.processEvent(Unknown Source)
at java.awt.Component.dispatchEventImpl(Unknown Source)
at java.awt.Container.dispatchEventImpl(Unknown Source)
at java.awt.Component.dispatchEvent(Unknown Source)
This Error was encountered when attempting to import the pem file into the key store.
This can happen when the order of the certificates inside the pem are in the wrong order.
java.lang.Exception: Trust anchor for certification path not found.
at com.tridium.platcrypto.daemon.BPlatKeyStore.setKeyEntry(BPlatKeyStore.java:227)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:241)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:484)
at javax.baja.ui.Command.doInvoke(Command.java:313)
at javax.baja.ui.Command.invoke(Command.java:283)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:556)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1237)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:305)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:279)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:115)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:88)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:484)
at java.awt.Component.processEvent(Component.java:6270)
at java.awt.Container.processEvent(Container.java:2229)
at java.awt.Component.dispatchEventImpl(Component.java:4861)
at java.awt.Container.dispatchEventImpl(Container.java:2287)
at java.awt.Component.dispatchEvent(Component.java:4687)
at java.awt.EventQueue.dispatchEventImpl(EventQueue.java:735)
The exception below is due to the customer having the wrong root and intermediate certs. They had pulled these from the browser rather than requesting them from the signing authority.
org.bouncycastle.jce.exception.ExtCertPathValidatorException: Could not validate certificate signature.
at org.bouncycastle.jce.provider.RFC3280CertPathUtilities.processCertA(Unknown Source)
at org.bouncycastle.jce.provider.PKIXCertPathValidatorSpi.engineValidate(Unknown Source)
at java.security.cert.CertPathValidator.validate(CertPathValidator.java:292)
at com.tridium.crypto.core.cert.CertUtils.validateCertChain(CertUtils.java:401)
at com.tridium.crypto.core.io.CoreKeyStore.setKeyEntry(CoreKeyStore.java:153)
at com.tridium.platcrypto.fox.BCryptoChannel.keyStoreSetKeyEntry1(BCryptoChannel.java:814)
at com.tridium.platcrypto.fox.BCryptoChannel.process(BCryptoChannel.java:149)
at com.tridium.fox.sys.BFoxConnection.process(BFoxConnection.java:378)
at com.tridium.fox.session.SessionDispatcher.dispatch(SessionDispatcher.java:81)
at com.tridium.fox.session.SessionDispatcher.run(SessionDispatcher.java:60)
at java.lang.Thread.run(Thread.java:745)
Caused by: java.security.SignatureException: certificate does not verify with supplied key
at org.bouncycastle.jcajce.provider.asymmetric.x509.X509CertificateObject.checkSignature(Unknown Source)
at org.bouncycastle.jcajce.provider.asymmetric.x509.X509CertificateObject.verify(Unknown Source)
at org.bouncycastle.jce.provider.CertPathValidatorUtilities.verifyX509Certificate(Unknown Source)
... 11 more
The exception below is due to the Chain Of Trust being incomplete. The fix was to export the signing authority’s CA from the Workbench ‘Trust Store’ and include that as the last certificate (Root Certificate) in the master PEM file to be imported.
java.lang.Exception: the trustAnchors parameter must be non-empty
at com.tridium.platcrypto.daemon.BPlatKeyStore.setKeyEntry(BPlatKeyStore.java:239)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:239)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:492)
at javax.baja.ui.Command.doInvoke(Command.java:311)
at javax.baja.ui.Command.invoke(Command.java:281)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:554)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1239)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:309)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:283)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:119)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:92)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:487)
at com.tridium.ui.swing.BSwingWidget$GlassMouseListener.redispatchMouseEvent(BSwingWidget.java:588)
at com.tridium.ui.swing.BSwingWidget$GlassMouseListener.mouseReleased(BSwingWidget.java:481)
at java.awt.Component.processMouseEvent(Component.java:6533)
at javax.swing.JComponent.processMouseEvent(JComponent.java:3324)
at java.awt.Component.processEvent(Component.java:6298)
at java.awt.Container.processEvent(Container.java:2236)
"java.io.IOException: unsupported object type: org.bouncycastle.asn1.pkcs.PrivateKeyInfo ".
The above exception is generated while in the 'Import Command' method. It is just importing stuff from the PEM and encounters something it doesn't understand.
First it sets up a variable to parse the PEM file. Then it starts reading in the file, checking each object.
Each object checked in this order:
Is it instanceof X509Certificate
Is it X509CertificateHolder
is it Private Key
is it Key Pair
is it Pem Encrypted Key Pair
else throw IOException "unsupported object type" because it could not determine what type object was being imported from the PEM file.
Solution is to correct the PEM.
“WARNING [10:27:15 12-Nov-19 EST][web] unable to obtain certificate 'master5' (mismatched public and private key, failed test signature verification), trying default”
The above error can show up in the Application Director when attempting to connect securely to a station and the private key does not match the public key. This can happen if you have exported the private key from your certificate in an encrypted format and then copied that private key to your master PEM file for import back into Niagara User Key Store.
To remedy this error you need to start over, creating a new certificate, exporting the private key not encrypted. Generate a new Certificate Signing Request. Get the signed certificate back from the signing authority. Add your unencrypted private key to this new signed PEM file and import into the Niagara User Key Store.
This error was encountered importing signed cert. This exception happens when the alias doesn’t match the cert request and signed cert.
java.security.UnrecoverableKeyException: unable to recover key
at com.tridium.platcrypto.fox.BCryptoChannel.keyStoreGetKey(BCryptoChannel.java:537)
at com.tridium.platcrypto.fox.ChannelKeyStore.getKey(ChannelKeyStore.java:124)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:223)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:398)
at javax.baja.ui.Command.doInvoke(Command.java:313)
at javax.baja.ui.Command.invoke(Command.java:283)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:556)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1201)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:305)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:279)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:115)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:88)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:548)
at java.awt.Component.processEvent(Unknown Source)
at java.awt.Container.processEvent(Unknown Source)
at java.awt.Component.dispatchEventImpl(Unknown Source)
at java.awt.Container.dispatchEventImpl(Unknown Source)
at java.awt.Component.dispatchEvent(Unknown Source)
This Error was encountered when attempting to import the pem file into the key store.
This can happen when the order of the certificates inside the pem are in the wrong order.
java.lang.Exception: Trust anchor for certification path not found.
at com.tridium.platcrypto.daemon.BPlatKeyStore.setKeyEntry(BPlatKeyStore.java:227)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:241)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:484)
at javax.baja.ui.Command.doInvoke(Command.java:313)
at javax.baja.ui.Command.invoke(Command.java:283)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:556)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1237)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:305)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:279)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:115)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:88)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:484)
at java.awt.Component.processEvent(Component.java:6270)
at java.awt.Container.processEvent(Container.java:2229)
at java.awt.Component.dispatchEventImpl(Component.java:4861)
at java.awt.Container.dispatchEventImpl(Container.java:2287)
at java.awt.Component.dispatchEvent(Component.java:4687)
at java.awt.EventQueue.dispatchEventImpl(EventQueue.java:735)
The exception below is due to the customer having the wrong root and intermediate certs. They had pulled these from the browser rather than requesting them from the signing authority.
org.bouncycastle.jce.exception.ExtCertPathValidatorException: Could not validate certificate signature.
at org.bouncycastle.jce.provider.RFC3280CertPathUtilities.processCertA(Unknown Source)
at org.bouncycastle.jce.provider.PKIXCertPathValidatorSpi.engineValidate(Unknown Source)
at java.security.cert.CertPathValidator.validate(CertPathValidator.java:292)
at com.tridium.crypto.core.cert.CertUtils.validateCertChain(CertUtils.java:401)
at com.tridium.crypto.core.io.CoreKeyStore.setKeyEntry(CoreKeyStore.java:153)
at com.tridium.platcrypto.fox.BCryptoChannel.keyStoreSetKeyEntry1(BCryptoChannel.java:814)
at com.tridium.platcrypto.fox.BCryptoChannel.process(BCryptoChannel.java:149)
at com.tridium.fox.sys.BFoxConnection.process(BFoxConnection.java:378)
at com.tridium.fox.session.SessionDispatcher.dispatch(SessionDispatcher.java:81)
at com.tridium.fox.session.SessionDispatcher.run(SessionDispatcher.java:60)
at java.lang.Thread.run(Thread.java:745)
Caused by: java.security.SignatureException: certificate does not verify with supplied key
at org.bouncycastle.jcajce.provider.asymmetric.x509.X509CertificateObject.checkSignature(Unknown Source)
at org.bouncycastle.jcajce.provider.asymmetric.x509.X509CertificateObject.verify(Unknown Source)
at org.bouncycastle.jce.provider.CertPathValidatorUtilities.verifyX509Certificate(Unknown Source)
... 11 more
The exception below is due to the Chain Of Trust being incomplete. The fix was to export the signing authority’s CA from the Workbench ‘Trust Store’ and include that as the last certificate (Root Certificate) in the master PEM file to be imported.
java.lang.Exception: the trustAnchors parameter must be non-empty
at com.tridium.platcrypto.daemon.BPlatKeyStore.setKeyEntry(BPlatKeyStore.java:239)
at com.tridium.platcrypto.ui.BLocalCertsTable$LocalImportCommand.importCertData(BLocalCertsTable.java:239)
at com.tridium.platcrypto.ui.BCertsTable$ImportCommand.doInvoke(BCertsTable.java:492)
at javax.baja.ui.Command.doInvoke(Command.java:311)
at javax.baja.ui.Command.invoke(Command.java:281)
at javax.baja.ui.BButton.doInvokeAction(BButton.java:149)
at javax.baja.ui.BAbstractButton.mouseReleased(BAbstractButton.java:554)
at javax.baja.ui.BWidget.fireMouseEvent(BWidget.java:1239)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:309)
at com.tridium.ui.awt.MouseManager.fire(MouseManager.java:283)
at com.tridium.ui.awt.MouseManager.released(MouseManager.java:119)
at com.tridium.ui.awt.MouseManager.process(MouseManager.java:92)
at com.tridium.ui.awt.AwtShellManager.processMouseEvent(AwtShellManager.java:487)
at com.tridium.ui.swing.BSwingWidget$GlassMouseListener.redispatchMouseEvent(BSwingWidget.java:588)
at com.tridium.ui.swing.BSwingWidget$GlassMouseListener.mouseReleased(BSwingWidget.java:481)
at java.awt.Component.processMouseEvent(Component.java:6533)
at javax.swing.JComponent.processMouseEvent(JComponent.java:3324)
at java.awt.Component.processEvent(Component.java:6298)
at java.awt.Container.processEvent(Container.java:2236)
"java.io.IOException: unsupported object type: org.bouncycastle.asn1.pkcs.PrivateKeyInfo ".
The above exception is generated while in the 'Import Command' method. It is just importing stuff from the PEM and encounters something it doesn't understand.
First it sets up a variable to parse the PEM file. Then it starts reading in the file, checking each object.
Each object checked in this order:
Is it instanceof X509Certificate
Is it X509CertificateHolder
is it Private Key
is it Key Pair
is it Pem Encrypted Key Pair
else throw IOException "unsupported object type" because it could not determine what type object was being imported from the PEM file.
Solution is to correct the PEM.
“WARNING [10:27:15 12-Nov-19 EST][web] unable to obtain certificate 'master5' (mismatched public and private key, failed test signature verification), trying default”
The above error can show up in the Application Director when attempting to connect securely to a station and the private key does not match the public key. This can happen if you have exported the private key from your certificate in an encrypted format and then copied that private key to your master PEM file for import back into Niagara User Key Store.
To remedy this error you need to start over, creating a new certificate, exporting the private key not encrypted. Generate a new Certificate Signing Request. Get the signed certificate back from the signing authority. Add your unencrypted private key to this new signed PEM file and import into the Niagara User Key Store.