Skip to content

TLS Certificates

This guide will talk you through generating 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 Kyrio as the certificate provider.

Many programs will have a test VTN for which you can quickly generate test certificates for free, from Kyrio. When you are ready to connect to their live production VTN, you will need to go through the process with Kyrio 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 Kyrio in order to connect to test VTN instances.

Generate Certificate from Kyrio

Generate a Test certificate at https://testcerts.kyrio.com/.

You will see the following screen.

Kyrio Test Certs screen

Click on Get Certificate under OpenADR on the left side. In the modal window there is a form. The only things you must update are:

  • Device type Client (VEN)
  • Country Your country (USA is default)
  • Company Name Your company name
  • Text Enter something descriptive (this will not be used)

Kyrio modal form

Keep all other configurations the same. Click GET to download your certificates. Unzip the folder and view the contents. They should look similar to the following.

Kyrio Certificate files

Here's a description of each file:

  • TEST_OpenADR_RSA_RCA0002_Cert.pem: CA certificate file
  • TEST_OpenADR_RSA_MCA0002_Cert.pem: CA certificate file
  • TEST_RSA_VEN_1234_privkey.pem: Certificate private key
  • TEST_RSA_VEN_1234_cert.pem: Certificate file
  • TEST_RSA_VEN_1234_cert_Fingerprint.txt: Certificate fingerprint (this fingerprint isn't correct and isn't used)

The first two files are certificate authority files and are the same in every certificate bundle generated from Kyrio. The next two files - the private key and certificate file - contain the RSA private/public key pair and some information that was signed by Kyrio. 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.

  1. The file that ends with privkey.pem - for simplicity rename it to privkey.pem.
  2. In a plain text editor, concatenate together the contents of three other files and save it as certchain.pem, in this order:
    1. The file that ends with cert.pem
    2. The file that ends with MCA0002_Cert.pem
    3. The file that ends with RCA0002_Cert.pem

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

CLI-driven option for creating files

Navigate to the folder you just downloaded in the unix or powershell command line, run the following 3 lines and copy the /certs folder into the Plaid root directory:

mkdir certs
cp *_privkey.pem certs/privkey.pem
cat *_cert.pem *_MCA0002_Cert.pem *_RCA0002_Cert.pem > certs/certchain.pem

For powershell you will need to add commas between the file names in the cat command

Finally, in the config file, make sure that the certificate file path parameters point to the correct files:

  • keypath points to the privkey file
  • certpath points to the certchain file
  • capath points to the ca file that is provided with Plaid. When connecting to a test instance, it should use the test file.

In the binaries, only the test file is given.

Production certificates

The test certificates will not work with most production VTNs. Production certificates will be generated either via Kyrio (you will need to go through the validation process and purchase a subscription to get production certificates) 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!