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.
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)
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.
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
- The file that ends with
privkey.pem
- for simplicity rename it toprivkey.pem
. - In a plain text editor, concatenate together the contents of three other files and save it as
certchain.pem
, in this order:- The file that ends with
cert.pem
- The file that ends with
MCA0002_Cert.pem
- The file that ends with
RCA0002_Cert.pem
- The file that ends with
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 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 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 thecacerts
folder (or download here)