Intro
By default, the Controller does not check the certificate of the VTCs upon connection, but the VTC always checks the Controller cert against the root CA. The Controller can be build with SSL_VERIFY=ON. If that build flag is set, the Controller will now verify that any incoming VTC connection has a valid cert signed by the same root CA as the Controller. In addition, the Controller will verify that the VTC cert has a Common Name (CN) that matches what is configured in the provisioning database for that specific VTC.
While requiring more hands-on management, this is a way to provide an additional layer of security for your DVN cloud.
The Controllers and VTCs include a default cert in the certificates directory of the app. For enhanced security, the network administrator should create a new root certificate using these instructions so only VTCs with the same root CA will be able to talk to the Controller.
For the following instructions, we will be using the EasyRSA certificate management tool.
For simplicity, please copy the tool + requisite config files from this download link to any of your machines that need the tool.
Overview
At a high level, you'll need a single secure machine that will create and host the PKI (Public Key Infrastructure) for your network's certificates. For each Controller/VTC in the network, you'll need to generate a CSR (certificate signing request) that will be sent to the PKI machine to process and generate the cert. This will ensure that the private keys for each individual machine never have to leave that specific machine, only the public cert. This is the most secure way and should always be followed in production. Example:
VTC A generates CSR using easyrsa --> sends the CSR to the PKI machine which processes the request --> upon success, the PKI machine will send the .crt file back to the VTC A machine.
NOTE: To simplify this process in a test or lab environment, EasyRSA provides a shortcut that allows the CSR and cert to be generated in 1 step all from the PKI machine. While this is not the recommended production-style deployment, it can significantly reduce the number of steps in this process and will be documented further down in the docs as the Lab Shortcut Method.
CSR Method
Build the Root CA + PKI
First, download Easy RSA tool on cert management/pki machine
on the machine that will manage the PKI:
# edit the vars.example file, line 213
# uncomment the line, and name your CA
# in this example, I'll use DVN 4.3 CA
.....
set_var EASYRSA_REQ_CN "DVN 4.3 CA"
.....
Then run the following:
./easyrsa init-pki
./easyrsa build-ca nopass
At this point, you'll have a complete root cert. This file (found at <easyrsa dir>/pki/ca.crt) will need to be utilized as the root cert for every Controller and VTC in your network. Copy the file securely and place it in the certificate directory of each Controller or VTC with the following filename (must be exact): ca-cert.pem.
For Controllers:
/var/lib/dvn-dps/certificates/ca-cert.pem
For VTCs:
/var/lib/dvn/certificates/ca-cert.pem
Generating Individual Certificates
Controllers
Download the EasyRSA tool.
Run the following for each Controller in your network:
tar -xzvf easyrsa.tar.gz
./easy-rsa init-pki
./easyrsa gen-req <Controller ID> nopass
Note that the entity name must be the Controller ID that will be used by the DVN network.
Copy the file located at <easyrsa path>/pki/reqs/[name].req to the PKI machine securely.
From the PKI machine, import the request and sign it as a server cert:
./easyrsa import-req /path/to/[name].req <Controller ID>
./easyrsa sign-req server <Controller ID>
Transport the newly signed certificate to the requesting entity. This entity may also need the CA cert (ca.crt) unless it had a prior copy.
Ensure all files are transferred and renamed as follows:
| File | Destination for File |
|---|---|
| pki machine: /easyrsadir/pki/ca.crt | controller machine: /var/lib/dvn-dps/certificates/ca-cert.pem |
| controller machine: /easyrsadir/pki/private/[name].key | controller machine: /var/lib/dvn-dps/certificates/server-key.pem |
| pki machine: /easyrsadir/pki/issued/[name].crt | controller machine: /var/lib/dvn-dps/certificates/server-cert.pem |
VTCs
Download the EasyRSA tool.
Run the following for each VTC in your network:
tar -xzvf easyrsa.tar.gz
./easy-rsa init-pki
./easyrsa gen-req <VTC ID> nopass
Note that the VTC ID must match the actual VTC ID of the node that the Controller will know about (what will appear in vtc_config.json/jsec file).
WARNING: underscores are not allowed in this name (per ASN.1). This is used as the certificate Common Name (CN).
Copy the file located at <easyrsa path>/pki/reqs/[name].req to the PKI machine securely.
From the PKI machine, import the request and sign it as a client cert:
./easyrsa import-req /path/to/[name].req <VTC ID>
./easyrsa sign-req client <VTC ID>
Transport the newly signed certificate to the requesting entity. This entity may also need the CA cert (ca.crt) unless it had a prior copy.
Ensure all files are transferred and renamed as follows:
| File | Destination for File |
|---|---|
| pki machine: /easyrsadir/pki/ca.crt | VTC machine: /var/lib/dvn/certificates/ca-cert.pem |
| VTC machine: /easyrsadir/pki/private/[name].key | VTC machine: /var/lib/dvn/certificates/vtc.cert |
| pki machine: /easyrsadir/pki/issued/[name].crt | VTC machine: /var/lib/dvn/certificates/vtc.key |
Service-Prov
Since service-prov connects directly to the Controllers for certain pieces of functionality, run the following commands exactly to generate the certificates for the REST API:
On the service-prov host machine:
Run the following:
tar -xzvf easyrsa.tar.gz
./easy-rsa init-pki
./easyrsa gen-req dart nopass
Copy the file located at <easyrsa path>/pki/reqs/[name].req to the PKI machine securely.
From the PKI machine, import the request and sign it as a server cert:
./easyrsa import-req /path/to/[name].req dart
./easyrsa sign-req client dart
Transport the newly signed certificate to the requesting entity.
| File | Destination for File |
|---|---|
| pki machine: /easyrsadir/pki/issued/dart.crt | service-prov machine: /usr/local/dispersive/certificates/dart.pem |
| service-prov machine: ./pki/private/dart.key | service-prov machine: /usr/local/dispersive/certificates/dart.key |
Lab Shortcut Method
The EasyRSA provides a way to generate CSRs and sign them directly from the PKI host machine with 1 single command. The resulting cert + private key can then be transferred directly to the requisite Controller or VTC machine, simplifying deployment greatly. If you are not concerned with the private keys for all machines residing on a single machine, this method works very well :
On the PKI Machine:
# edit the vars.example file, line 213
# uncomment the line, and name your CA
# in this example, I'll use DVN 4.3 CA
.....
set_var EASYRSA_REQ_CN "DVN 4.3 CA"
.....
Then run the following:
./easyrsa init-pki
./easyrsa build-ca nopass
Controllers
From the PKI machine, run the following:
./easyrsa build-server-full <Controller ID> nopass
Copy and rename the files to the Controller machine:
| PKI Machine File | Controller Machine File |
|---|---|
| ./pki/ca.crt | /var/lib/dvn-dps/certificates/ca-cert.pem |
| ./pki/issued/[controllerid].crt | /var/lib/dvn-dps/certificates/server-cert.pem |
| ./pki/private/[controllerid].key | /var/lib/dvn-dps/certificates/server-key.pem |
VTCs
From the PKI machine, run the following:
./easyrsa build-client-full <VTC ID> nopass
Copy and rename the files to the VTC machine:
| PKI Machine File | VTC Machine File |
|---|---|
| ./pki/ca.crt | /var/lib/dvn/certificates/ca-cert.pem |
| ./pki/issued/[vtcid].crt | /var/lib/dvn/certificates/vtc.cert |
| ./pki/private/[vtcid].key | /var/lib/dvn/certificates/vtc.key |
Service-Prov
From the PKI machine, run the following:
./easyrsa build-client-full dart nopass
Copy and rename the files to the service-prov machine:
| PKI Machine File | service-prov Machine File |
|---|---|
| ./pki/issued/dart.crt | /usr/local/dispersive/certificates/dart.pem |
| ./pki/private/dart.key | /usr/local/dispersive/certificates/dart.key |
Note that for service-prov, the root CA cert does not need to be transferred. The certificates for service-prov can be found at /usr/local/dispersive/certificates.
4.2.0 Considerations
Prior to the 4.3.0 release, the old Orchestrator (formerly called DART) was used as a web management interface. In order to get that working with 2-way certs, follow the same instructions that are listed above for service-prov to generate the cert and key. Then, copy the resulting file as follows:
| PKI Machine File | Orchestrator/DART Machine File |
|---|---|
| ./pki/issued/dart.crt | /var/www/dvn-dart/certs/dart.pem |
| ./pki/private/dart.key | /var/www/dvn-dart/certs/dart.key |