OpenADR Security Certificate Installation and Verification Guide

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
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