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 do 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 TRUSTSTORE=VEN_truststore.jks

set KEYSTORE=VEN_keystore.jks

set PASSWORD=password

set ROOT_CERT=TEST_OpenADR_RSA_RCA0002_Cert.pem

set ROOT_ALIAS=RSA_ROOT_01

REM Remember to get the right Intermediate cert here!

set INT_CERT=TEST_OpenADR_RSA_SPCA0002_Cert.pem

set INT_ALIAS=RSA_VTN_Int_01

set DEV_CERT=TEST_RSA_VEN_151011191522_cert.pem

set DEV_ALIAS=111111111111_rsa

set 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 VTN_TRUSTSTORE=VTN_truststore.jks

set VTN_KEYSTORE=VTN_keystore.jks

set VEN_TRUSTSTORE=VEN_truststore.jks

set VEN_KEYSTORE=VEN_keystore.jks

set ROOT_ALIAS=RSA_ROOT_01

set VEN_INT_ALIAS=RSA_VEN_INT_01

set VTN_INT_ALIAS=RSA_VTN_INT_01

set VEN_DEV_ALIAS=111111111111_rsa

set VTN_DEV_ALIAS=vtn_rsa

set VEN_TRUST_PASSWORD=password

set VEN_KEY_PASSWORD=password

set VTN_TRUST_PASSWORD=password

set 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