Skip to content

TLS Certificates

This section is about generating TLS certificates for an instance of Plaid.

OpenADR requires connections to use TLS 1.2 with client side certificates. Both the client (the VEN, Plaid in this case) and the server (VTN) must have a certificate. Certificates are generated by a certificate authority (CA). The OpenADR alliance has selected Eonti as the certificate provider.

Many programs will have a test VTN for which you can quickly generate test certificates for free, from Eonti. When you are ready to connect to their live production VTN, you will need to go through the process with Eonti to generate live certificates. This takes more time and money but is important to ensure a secure VEN authentication process.

Test certificates

You can use free test certificates from Eonti in order to connect to test VTN instances.

Generate Certificate from Eonti

Request for a Test certificate at https://www.eonti.com/openadr/.

You will see the following screen, with a form.

Eonti Test Certs screen

The only things you must update are:

  • Name Your name
  • Email Your email
  • Certificate type VEN (Client)
  • Encryption Algorithm RSA(SHA256, 2048 bit)
  • 2 Letter Country Code Your country (USA is default)
  • Organization Name Your company name
  • Common Name Name of your certificate. Enter something descriptive (this will not be used)

There is also a Radio button in which you need to pick second option: * I want the certificate issuance portal to create the key pair for me and return the private key and public key certificate. (For TEST certificates ONLY, the private key, its password, and the public key certificate will all be downloaded at the same time from a shared drive).

Eonti modal form

Keep all other configurations the same. Click Submit to submit request for your certificates. It may take up to couple of days and you will receive your certificates through email. The email will contain 1 .pfx file and 1 .zip. Unzip the folder and view the contents. They should look similar to the following.

Eonti Certificate files

Here's a description of each file:

  • OpenADR Alliance TEST RSA Root CA root.crt: CA certificate file
  • OpenADR Alliance TEST RSA VEN CA intermediate.crt: CA certificate file
  • Eonti Test VEN primary.crt: Certificate file
  • Eonti Test VEN.pfx: Certificate private key

The first two files are certificate authority files and are the same in every certificate bundle generated from Eonti. The next two files - the private key and certificate file - contain the RSA private/public key pair and some information that was signed by Eonti. The certificate file can be verified using the two CA certificate files.

Before these files can be used by Plaid, a little prep work must be done.

Add certificate to Plaid instance

You will need to create two files based on contents of the folder that you just downloaded. See next section for example command line commands to execute the following steps

  1. The file with extension .pfx - use command openssl pkcs12 -in "Your_test_Cert_name.pfx" -out privkey.pem -nodes -nocerts
  2. Open privkey.pem and remove everything until the line that says -----BEGIN PRIVATE KEY-----. (Remember to not remove that line)
  3. In a plain text editor, concatenate together the contents of three other files and save it as certchain.pem, in this order:
    1. Your_test_Cert_name_primary.crt
    2. OpenADR Alliance TEST RSA VEN CA intermediate.crt
    3. OpenADR Alliance TEST RSA Root CA root.crt

Create a new folder in the root directory /certs and add those two files in there.


Finally, in the config file, make sure that the certificate file path parameters point to the correct files (you may want to move the certs folder into the same folder structure as your Plaid executable):

  • keypath points to the privkey file
  • certpath points to the certchain file
  • capath points to the ca file that is provided with Plaid. In the source code, this is in the cacerts/ folder. When connecting to a test instance, it should use the test file (ven_cacerts_test.pem).

In the binaries, only the test cacerts file is given.

Production certificates

The test certificates will not work with most production VTNs. Production certificates will be generated either via Eonti or directly from the VTN provider. The files need to be organized in the same way as described above, and make sure that you are using the prod ca file!

If Eonti production certificates are required, and you have gone through OpenADR certification process, you may contract directly with Eonti to obtain the certificates

You will need to generate a private key and a CSR for every production certificate that you request.

Using Production Certificates

The process to use production certificates is similar to test certificates, but they need to be prepared differently.

For cacerts, if the VTN is using an existing cert from Kyrio, then you can use the ven_cacerts_prod.pem file that’s included in your source code (or download here). If the VTN is using Eonti certificate then you will need to request the cacerts from them.

For the key, you use the private key that you generated when you created a CSR.

For the certificate, use the signed certificate received back from Eonti after the certificate signing process. To be safe, it is worth chaining a couple intermediate certificates to make sure that the VTN can trace it back to a well known certificate authority.

You’ll need to create a certificate chain out of:

  • 1st – your signed certificate from Eonti
  • 2nd – append the contents of the intermediate certificate
  • 3rd – append the contents of production root certificate

If the files get downloaded as .csr files, before appending you need to convert them into .pem. You should be able to do so using openssl – if using openssl with the command line:

openssl x509 -in mycert.crt -out mycert.pem -outform PEM -inform DER

(you need to add -inform DER because the certificates you get are in binary format).

Once you have the proper files in pem format, concatenate the contents of these 3 files into a single file in the order specified above, and that becomes your certificate file.

Add the path to these files in the Plaid Config File.

CA Certificates for the Plugin

If you would like the plugin messages to use https (configured in the config file under the plugin>tls section):

  • On Linux, there is no need to specify a CA file unless the endpoint is not using a certificate from a wellknown CA - Plaid will use the default system CA files
  • On Windows, use the ffcacert.pem file in the cacerts folder (or download here)