OpenADR Security Certificate Installation and Verification Guide

Many OpenADR VEN and VTN developers have had difficulty getting their devices communicating over a secure transport using the OpenADR required X.509 certificates provided by NetworkFX. This document will guide developers through the certificate installation and verification process with a focus on getting test certificates installed so that they will interoperate with the OpenADR Test Harness. This document is not intended as a tutorial on the Public Key Infrastructure nor the inner working of the Java Secure Sockets Extensions (JSSE) which will be utilized for the examples in this document. The OpenADR conformance rules require the following security configuration for certification: • TLS Version 1.2 is used for the exchange of X.509 certificates • VTNs must have both SHA256 ECC and RSA certificates • VENs may support either SHA256 ECC and RSA certificates, and may support both • Both VTNs and VENs must be configured to request client certificates if they are going to play the role of a transport server (i.e. responding to requests from the other party) • Both VTNs and VENs must provide a client certificate when requested by the other party as part of the TLS negotiation process Note: Based on economic reasons, the OpenADR Alliance decided not to make TLS 1.0 certificates available. The use of TLS 1.2 is strongly recommended by most security guidelines. Test certificates provided by Network FX will be contained in a ZIP file and will be specific to the OpenADR role (VEN or VTN), release (typically release 2), and the encryption type (RSA or ECC). The following files are provided: • Root Certificate • Intermediate Root Certificate • Device Certificate • Private Key In general, the Private Key is used to encrypt payloads sent by a VEN or VTN. The Device Certificate is a set of unique identifying information about a VEN or VTN that has been created by a Certificate Authority and encrypted using the Private Key. The Root and Intermediate Certificates are used to decrypt the Device Certificate and validate that the Device Certificate came from a trusted authority.

OpenADR Security Certificate Installation and Verification Guide Many OpenADR VEN and VTN developers have had difficulty getting their devices communicating over a secure transport using the OpenADR required X.509 certificates provided by NetworkFX This document will guide developers through the certificate installation and verification process with a focus on getting test certificates installed so that they will interoperate with the OpenADR Test Harness This document is not intended as a tutorial on the Public Key Infrastructure nor the inner working of the Java Secure Sockets Extensions (JSSE) which will be utilized for the examples in this document The OpenADR conformance rules require the following security configuration for certification: • • • • • TLS Version 1.2 is used for the exchange of X.509 certificates VTN's must have both SHA256 ECC and RSA certificates VENs may support either SHA256 ECC and RSA certificates, and may support both Both VTNs and VENs must be configured to request client certificates if they are going to play the role of a transport server (i.e responding to requests from the other party) Both VTNs and VENs must provide a client certificate when requested by the other party as part of the TLS negotiation process Note: Based on economic reasons, the OpenADR Alliance decided not to make TLS 1.0 certificates available The use of TLS 1.2 is strongly recommended by most security guidelines Test certificates provided by Network FX will be contained in a ZIP file and will be specific to the OpenADR role (VEN or VTN), release (typically release 2), and the encryption type (RSA or ECC) The following files are provided: • • • • Root Certificate Intermediate Root Certificate Device Certificate Private Key In general, the Private Key is used to encrypt payloads sent by a VEN or VTN The Device Certificate is a set of unique identifying information about a VEN or VTN that has been created by a Certificate Authority and encrypted using the Private Key The Root and Intermediate Certificates are used to decrypt the Device Certificate and validate that the Device Certificate came from a trusted authority The following files names are used for each of these file types when requesting test certificates in a PEM format The files are shown in Root, Intermediate, Device, Private Key order: • • • • VTN ECC o TEST OpenADR ECC Root CA3_cert.pem o TEST OpenADR ECC SHA256 VTN Int CA3_cert.pem o TEST_ECC_VTN_141019190232_cert.pem o TEST_ECC_VTN_141019190232_privkey.pem VEN ECC o TEST OpenADR ECC Root CA3_cert.pem o TEST OpenADR ECC SHA256 VEN Int CA4_cert.pem o TEST_ECC_VEN_141019190718_cert.pem o TEST_ECC_VEN_141019190718_privkey.pem VTN RSA o TEST_OpenADR_RSA_RCA0002_Cert.pem o TEST_OpenADR_RSA_SPCA0002_Cert.pem o TEST_RSA_VTN_141019190212_cert.pem o TEST_RSA_VTN_141019190212_privkey.pem VEN RSA o TEST_OpenADR_RSA_RCA0002_Cert.pem o TEST_OpenADR_RSA_MCA0002_Cer.pem o TEST_RSA_VEN_141019190706_cert.cpem o TEST_RSA_VEN_141019190706_privkey.pem In a Java environment that utilizes JSSE, there are two certificate stores One is called a Trust Store and is typically used to hold the Root Certificate of the other entity you are communicating with The second is called a Key Store and is used to store the device and intermediate certificate in a chain, as well as the private key However, due to some challenges with the Openfire XMPP server, the OpenADR test harness Trust Store and Key Store files are configured as follows: • • • • The Trust Stores used by the test harness and the XMPP server contain both root and intermediate certificates for both RSA and ECC The Key Store used by the test harness for HTTP communication contain the device certificate and private key The Key Store used by the XMPP server contain the device certificate and private key The Key Store used by the Test harness for communicating with the XMPP server contains a full certificate chain including root, Intermediate, and device certificate, as well as the private key VEN or VTN implementations attempting to communicate with the test harness should be configured as follows using the file names from above (RSA example shown): • • • • VTN Trust Store o TEST_OpenADR_RSA_RCA0002_Cert.pem (Root Cert) o TEST_OpenADR_RSA_MCA0002_Cert.pem (VEN Intermediate Cert) VTN Key Store o TEST_RSA_VTN_141019190212_cert.pem (Device Cert) o TEST_RSA_VTN_141019190212_privkey.pem (Private Key) VEN Trust Store o TEST_OpenADR_RSA_RCA0001_Cert.pem (Root Cert) o TEST_OpenADR_RSA_SPCA0002_Cert.pem (VTN Intermediate Cert) o VEN Key Store o TEST_RSA_VEN_141019190706_cert.pem (Device cert) o TEST_RSA_VEN_141019190706_privkey.pem (Private Key) The key thing to note above is that the intermediate certificates for the VEN must be installed in the VTN Trust Store, and the intermediate certificates for the VTN must be installed in the VEN Trust Store to interoperate with the test harness If your device supports ECC certificates as well, they can be grouped together in the same Trust Store and Key Store as the equivalent RSA certificates Note that the cipher negotiated as part of the TLS exchange will determine whether the ECC or RSA certificates are used if both are present in the Key Stores When using an XMPP transport, the VEN is communicating with the XMPP server and NOT directly with the VTN So the configuration of the certificates in the XMPP server MUST match the ones shown above for the VTN The communication between the VTN itself and the XMPP server is transparent to the VEN and is essentially a private link Nevertheless, some vendors use a set of VEN certs in the VTN when communicating with the XMPP server If you are using OpenFire as your XMPP server, there is another constraint that you must consider OpenFire requires that the CN name used in the client device certificates match the devices XMPP username configured on the XMPP server This can result in some odd client names as a MAC like address is used for the CN name on the VEN certificates (Part of the OpenADR Security Requirements) Creating the Trust Store and Key Stores requires two tools: Keytool and OpenSSL Keytool is part of the Java SDK and OpenSLL is available at www.OpenSSL.org Appendix A contains a batch file listing that illustrates how the root, intermediate, device, and private key files can be converted to Java Key Store and Trust Store "jks" files Refer to remarks in the batch file for detail explanations Once you have created Trust and Key Store files and installed them in the VEN and VTN (assuming both are Java implementations), usually the devices will interoperate However, if they not, it is sometimes helpful to demonstrate that the device certificate validates against the root and intermediate certificates independent of the VEN and VTN code Appendix B contains a batch file which can accomplish this objective, independently confirming that certificates stored in the VEN and VTN will validate Finally, most VENs and VTNs when playing the role of a transport client will attempt to validate that the CN field of the certificate provided by the transport server has a CN name that matches the host name of the entity that provided the certificate This may be another source if interoperability problems when exchanging certificates Host Name Verification can typically be disabled programmatically to isolate these kinds of issues and is disabled by default by the OpenADR Test Harness Appendix A - Create Trust Store and Key Store The following batch file can be used to create Trust Store and Key Store files The example shown is for setting up Trust and KeyStore Files for a VEN using RSA test certificates One prompt may appear in the console when running the batch file which should be responded to with the "y" key The various "set" commands should be updated to reflect the actual file names received from NetworkFX and the Alias names you plan to use (typically incorporating the CN name in the cert) Remember that to interoperate with the test harness, you need to place the VTN intermediate file in the VEN's trust store, and the VEN intermediate file in the VTNs Trust Store, The batch file can be modified to build certificates for ECC or include both ECC and RSA certificates in the same store files set set set set set REM set set set set set TRUSTSTORE=VEN_truststore.jks KEYSTORE=VEN_keystore.jks PASSWORD=password ROOT_CERT=TEST_OpenADR_RSA_RCA0002_Cert.pem ROOT_ALIAS=RSA_ROOT_01 Remember to get the right Intermediate cert here! INT_CERT=TEST_OpenADR_RSA_SPCA0002_Cert.pem INT_ALIAS=RSA_VTN_Int_01 DEV_CERT=TEST_RSA_VEN_151011191522_cert.pem DEV_ALIAS=111111111111_rsa PRIV_KEY=TEST_RSA_VEN_151011191522_privkey.pem del %TRUSTSTORE% del %KEYSTORE% REM Import root CA certificate to truststore keytool -import -keystore %TRUSTSTORE% -storepass %PASSWORD% -alias %ROOT_ALIAS% -file %ROOT_CERT% REM Import intermediate CA certificate for VTN server certificates to truststore keytool -import -keystore %TRUSTSTORE% -storepass %PASSWORD% -alias %INT_ALIAS% -file %INT_CERT% REM ************** List truststore ****************** keytool -list -v -storepass %PASSWORD% -Keystore %TRUSTSTORE% REM Create a pkcs12 keystore using device cert and private key openssl pkcs12 -export -in %DEV_CERT% -inkey %PRIV_KEY% -out keystore.p12 -name %DEV_ALIAS% -password pass:%PASSWORD% REM ******************* List contents of pkcs12 file ********************** keytool -list -keystore keystore.p12 -storepass %PASSWORD% -storetype PKCS12 REM Import pkcs12 file to create a "jks" keystore keytool -importkeystore -deststorepass password -destkeypass %PASSWORD% -destkeystore %KEYSTORE% -srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass %PASSWORD% -alias %DEV_ALIAS% REM **************** List contents of new jks Keystore file ********************** keytool -list -v -storepass %PASSWORD% -keystore %KEYSTORE% del keystore.p12 REM ********** Done ************** pause Appendix B- Validation Certs in Trust and Key Stores The batch file below extracts root, intermediate, and device certificates from Trust Store and Key Store files, then validates that the VEN device certificate validates against the VTNs Trust Store certificates, and that the VTN device certificate validates against the VENs Trust Store certificates Users should copy Trust and Key Store files from both the VEN and VTN in a common directory, and then update the various "Set" commands in the batch file below to reflect the naming used for their Trust and Key Stores It is also important to specify the correct alias names used by the certificates in the Trust Store and Key Store files for this batch file to run correctly Running the batch file in the common directory with the Trust Store and Key Store files will validate the certificates and output the results to the console set set set set set set set set set set set set set VTN_TRUSTSTORE=VTN_truststore.jks VTN_KEYSTORE=VTN_keystore.jks VEN_TRUSTSTORE=VEN_truststore.jks VEN_KEYSTORE=VEN_keystore.jks ROOT_ALIAS=RSA_ROOT_01 VEN_INT_ALIAS=RSA_VEN_INT_01 VTN_INT_ALIAS=RSA_VTN_INT_01 VEN_DEV_ALIAS=111111111111_rsa VTN_DEV_ALIAS=vtn_rsa VEN_TRUST_PASSWORD=password VEN_KEY_PASSWORD=password VTN_TRUST_PASSWORD=password VTN_KEY_PASSWORD=password REM Extract VEN certs REM Extract Root and Intermediate certs from truststore, convert to PEM, and concatenate keytool -export -storepass %VEN_TRUST_PASSWORD% -alias %ROOT_ALIAS% -file vtn_root.crt -keystore %VEN_TRUSTSTORE% keytool -export -storepass %VEN_TRUST_PASSWORD% -alias %VTN_INT_ALIAS% -file vtn_int.crt -keystore %VEN_TRUSTSTORE% openssl x509 -inform der -in vtn_root.crt -out vtn_root.pem openssl x509 -inform der -in vtn_int.crt -out vtn_int.pem copy vtn_root.pem+vtn_int.pem ven_truststore.concat REM Extract device cert from keystore, convert to PEM keytool -export -storepass %VEN_KEY_PASSWORD% -alias %VEN_DEV_ALIAS% -file ven_device.crt -keystore %VEN_KEYSTORE% openssl x509 -inform der -in ven_device.crt -out ven_device.pem REM Extract VTN Certs REM Extract Root and Intermediate certs from truststore, convert to PEM, and concatinate keytool -export -storepass %VTN_TRUST_PASSWORD% -alias %ROOT_ALIAS% -file ven_root.crt -keystore %VTN_TRUSTSTORE% keytool -export -storepass %VTN_TRUST_PASSWORD% -alias %VEN_INT_ALIAS% -file ven_int.crt -keystore %VTN_TRUSTSTORE% openssl x509 -inform der -in ven_root.crt -out ven_root.pem openssl x509 -inform der -in ven_int.crt -out ven_int.pem copy ven_root.pem+ven_int.pem vtn_truststore.concat REM Extract device cert from keystore, convert to PEM keytool -export -storepass %VTN_KEY_PASSWORD% -alias %VTN_DEV_ALIAS% -file vtn_device.crt -keystore %VTN_KEYSTORE% openssl x509 -inform der -in vtn_device.crt -out vtn_device.pem REM Validate Certs openssl verify -CAfile vtn_truststore.concat ven_device.pem > ven_to_vtn_results.txt openssl verify -CAfile ven_truststore.concat vtn_device.pem > vtn_to_ven_results.txt REM send results to console type ven_to_vtn_results.txt type vtn_to_ven_results.txt pause ... harness and the XMPP server contain both root and intermediate certificates for both RSA and ECC The Key Store used by the test harness for HTTP communication contain the device certificate and private... VTNs Trust Store certificates, and that the VTN device certificate validates against the VENs Trust Store certificates Users should copy Trust and Key Store files from both the VEN and VTN in a common... certificates (Part of the OpenADR Security Requirements) Creating the Trust Store and Key Stores requires two tools: Keytool and OpenSSL Keytool is part of the Java SDK and OpenSLL is available