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.
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).
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.
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
- The file with extension
.pfx
- use commandopenssl pkcs12 -in "Your_test_Cert_name.pfx" -out privkey.pem -nodes -nocerts
- Open
privkey.pem
and remove everything until the line that says-----BEGIN PRIVATE KEY-----
. (Remember to not remove that line) - In a plain text editor, concatenate together the contents of three other files and save it as
certchain.pem
, in this order:Your_test_Cert_name_primary.crt
OpenADR Alliance TEST RSA VEN CA intermediate.crt
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 filecertpath
points to the certchain filecapath
points to the ca file that is provided with Plaid. In the source code, this is in thecacerts/
folder. When connecting to a test instance, it should use thetest
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 thecacerts
folder (or download here)