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 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. See next section for example command line commands to execute the following steps

  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 (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 Kyrio 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 Kyrio production certificates are required, you have two options:

  • If you have gone through OpenADR certification process, you may contract directly with Kyrio to obtain the certificates
  • Obtain the certificates via GridFabric

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

Obtaining Production Certificates

Generating a private key and CSR

Kyrio maintains a well documented process to generate certificates, which can be found at https://kyrio.com/openadr/. See: Need more details on creating a CSR file?. Here are the steps from their document:

Using the command line to generate a CSR file for an OpenADR VEN is a simple two step process, requiring openssl, which is generally available in the terminal for Mac and Linux users, and may need to be added manually for Windows users by installing Cygwin with the openssl package

Generate Private Key

Use the genrsa command.

openssl genrsa -out <privkeyname>.pem 2048
  • The name of the file is up to you. Plaid supports .pem so make sure to append .pem to the filename.
  • 2048 is the bit_number to use - OpenADR uses 2048 bits for RSA certificates

Keep the private key in a secure location, and never share it externally (even with GridFabric).

Generate Certificate Signing Request (CSR)

Use the req command.

openssl req -new -sha256 -key <privkeyname>.pem -out <reqfilename>.csr \
  -subj "/C=US/O=<Company Name>/OU=OpenADR Alliance RSA VEN Certificate/CN=<unique id>"

Replace Company Name and unique id with values of your choosing.

Obtaining Kyrio Production certificates from Kyrio directly

If obtaining a certificate directly from Kyrio, what you enter as company name and unique id will match what you enter in your Naming document. You need to create a naming document for each certificate you create via Kyrio. You will send the naming document and .csr file to Kyrio, and Kyrio will sign the request with their private key and make the signed certificate available for download for you.

Obtaining production certificates via GridFabric

GridFabric can procure production certificates on behalf of our customers, with a few pre-requisites:

  • Certificates may only be used in an unchanged instance of Plaid
    • If Plaid has been updated, we will need to discuss the extent of the updates and then provide written permission to use certificates
    • Generally, updates to the plugin will not cause any issues but updates to the core OpenADR implementation may require review
  • We ask our customers to sign an agreement so their use of the certificates is bound to the same terms that we have with Kyrio

Customers generate a private key and CSR using the steps above, and send to GridFabric. GridFabric will pass along to Kyrio for signing, and when Kyrio returns the signed certificate GridFabric will share that with the customer.

For Company Name you will always set GridFabric.

For unique id we will use the format companyName-{uniqueId}, where companyName will be common for all your certs and uniqueId is controlled by you. For example,

openssl req -new -sha256 -key myprivkey-123.pem -out mycsr-123.csr \
  -subj "/C=US/O=GridFabric/OU=OpenADR Alliance RSA VEN Certificate/CN=myco-123"

Using Production Certificates

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

For cacerts, use the ven_cacerts_prod.pem file that’s included in your source code (or download here)

For the key, you use the private key that you generated when you created a CSR referenced in generating a private key and csr.

For the certificate, use the signed certificate received back from Kyrio 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.

The intermediate files are available for download at this link: https://kyrio.com/pki-resources/#1615319721833-cff4dad2-29fc. You’ll need to create a certificate chain out of:

  • 1st – your signed certificate from Kyrio
  • 2nd – append the contents of Open ADR Alliance RSA VEN (Client) CA0002 Certificate
  • 3rd – append the contents of Open ADR Alliance RSA Root CA Certificate

However, the files get downloaded as .csr files, so 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

CA certs are provided in the source code in the cacerts directory.

For the CA certs connection to the VTN (configured in the config file under the oadr>tls section), use either the production ca certs (ven_cacerts_prod.pem) or the test ca certs (ven_cacerts_test.pem). You can also download them: prod and test.

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)