-
Notifications
You must be signed in to change notification settings - Fork 1
Developers: Managing Certificates
Except for the Spool server production certificates, all Spool certificates are generated using OpenSSL. OpenSSL comes preinstalled on Mac OS X and many Linux Distros. If you are using Windows, OpenSSL is included in Git for Windows (see here) or you can find unofficial binaries on the OpenSSL wiki.
The spool install script will automatically generate the required development certificates for you. See Getting Started.
If you lost your secrets folder, run source Spool/setup/Generate-Certificates.sh in the Spool_Application directory to generate new ones.
The OPEnS production instance of Spool uses Letsencrypt certificates. If you are working on the OPEnS production instance of Spool you shouldn't need to create new certificates unless you are moving the servers. If they aren't working, try renewing them and setting up autorenewal again (see below).
Before generating Letsencrypt certificates you'll need to have your DNS and iptables set up so that the server can accept allowed traffic on port 443. To generate the certificates use certbot. The certbot website has straightforward instructions on how to install certbot and generate new certificates for your site. The Lab’s servers are running Ubuntu 18.04 LTS
Once you create the ssl certificate, you’ll need to modify the permissions on the certificate file so that docker can access it and mount it into the container. Specifically, you'll want to run
sudo chmod 755 /etc/letsencrypt/live/. If the server still won't start, also do sudo chmod 755 /etc/letsencrypt/archive/.
Todo: figure out a better solution to this that doesn't involve weakening protection of the certificate. For example, running a docker swarm or a kubernetes cluster would probably allow us to feed in secrets in a way that doesn't involve reading files.
Create a crontab task to run certbot renew weekly. To open/create crontab file run crontab -e then add @weekly sudo certbot renew to the list of crontab tasks.
In order to use Spool with Loom, you must update Loom's SSL trust anchors to include the Spool Certificate Authority certificate. OPEnS Lab's production Spool certificate authority will be included by default in the loom SSL trust anchors.
If you are testing a local configuration of Spool, a new trust anchors file can be generated. Make sure that SSLClient and python3 are installed and then run the following command:
python3 my/path/to/SSLClient/tools/pycert_bearssl/pycert_bearssl.py convert -c TAs -l TAs_NUM -s my/path/to/Spool_Application/secrets/ca.crt -n my/path/to/Spool_Application/secrets/ca.crt
This will create a certificates.h file in your working directory. Copy the contents of this file into loom/src/InternetPlats/TrustAnchors.h. Do NOT commit this file to git.
If you have your own production Spool deployment and want to enable your Loom devices to connect, you can use this user friendly tool to generate a TrustAnchors.h file for Loom. You just need to add the domain for your Spool instance in the list of domains.
Spool uses mutual TLS authentication (or mTLS) to authenticate Loom devices when they attempt to log data. When a user creates a new network in Spool the network is issued a client key and client x509 certificate. These credentials are stored in the loom config for the device that sends data to Spool. When the device sends data to Spool both Spool and the device present their X509 certificates. The device verifies Spool's certificate by checking that it is consistent with the device's certificates set in Loom's TrustAnchors.h file. Unlike a normal TLS connection however, Spool also attempts to verify the device's client certificate by checking if it originated with Spool's certificate authority (CA). The certificate authority is just a special certificate that is used to create and sign more certificates. This section describes how to create and maintain a certificate authority.
Creating a certificate authority is very similar to creating a normal certificate. First, generate a private key:
openssl ecparam -name prime256v1 -genkey -noout -out ca.key
Then generate a certificate authority using the special settings in Spool's configprod.txt file, replacing <Number of Days> with the number of days you want the certificate authority to be valid for.
openssl req -config /my/path/to/Spool/setup/configprod.txt -new -key ca.key -x509 -days <Number of Days> -out ca.crt
This will prompt you to provide the subject information (country, locality, common name, etc.) for the certificate authority. For reference, the subject information for OPEnS' production spool instance is
/C=US/ST=OR/L=Corvallis/O=OPEnS Lab/OU=Spool Device Root CA/CN=spool.open-sensing.org
Now you have a certificate authority at ca.crt! If you save the key in a secure location, you can use it to renew the certificate without breaking the client certificates Spool has already issued to devices.
If your certificate authority has expired or is going to expire soon and you still have the certificate authority key you can generate a new certificate authority to replace the expired one. If you don't still have the key, you'll need to create a new certificate authority. Unfortunately, this will invalidate all of your certificates issued by the original certificate authority.
To replace the certificate authority, generate a new certificate signed with the same key and with the same subject. Get the subject:
openssl x509 -subject -noout -in ca.crtThe subject is everything after subject=.
Now generate a new certificate authority. Replace <Number of Days> with the number of days you would like your new certificate authority to be valid for. Replace <Subject> with your subject.
openssl req -config /my/path/to/Spool/setup/configprod.txt -new -key ca.key -x509 -days <Number of Days> -subj "<Subject>" -out newca.crt