Adding certs to the EPIC trusted root certificate store (this makes CURL secure)

If you’ve ever tried to use CURL with a groov API from an EPIC you will have noticed that if you just do a standard curl -X ... request without setting up certificates, either GET or POST, you will get this warning message:

curl: (60) server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a “bundle”
of Certificate Authority (CA) public keys (CA certs). If the default
bundle file isn’t adequate, you can specify an alternate file
using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
the bundle, the certificate verification probably failed due to a
problem with the certificate (it might be expired, or the name might
not match the domain name in the URL).
If you’d like to turn off curl’s verification of the certificate, use
the -k (or --insecure) option.

If you just want to get up and running then curl -k -X ... will work fine without any certificates, and despite being referred to as “insecure” it actually is still a secure, encrypted connection. https is the only option with groov devices and is ALWAYS both secure and encrypted, it’s just not trusted.
This “trust” comes from curl being able to find the issuer of the server’s certificate in the EPIC clients trusted root store, but if the certificate isn’t there then the client doesn’t know it can trust the server, which is why the fail message shows up.
Because this is just a standard server certificate it will work for self-signed certificates as well as Certificate Authority (CA) signed certificates. You can learn more about certificates from the recent OptoVideo series or our security blog post if you want to know more about what that process looks like and why it’s important.

The curl manual page regarding the -k / --insecure option confirms this by saying the following:

curl verifies the server’s TLS certificate before it continues: that the certificate contains the right name which matches the host name used in the URL and that the certificate has been signed by a CA certificate present in the cert store.

You can find more curl-specific details here: curl.se/docs/manpage.html#-k


So, with all that out of the way, how do we deal with this?

The short version is that you need to add the contents of your server’s certificate to the end of /etc/ssl/certs/ca-certificates.crt, the exact file called out in the error message that curl refers to. If you didn’t follow all that, no worries, here are the exact steps:

Firstly, you’ll need the server certificate, which you can download via groov Manage in your browser. On the groov server that you want to communicate with go to groov Manage, then in the “Security” menu select “Server SSL” and finally click “Download Public Certificate”. I recommend naming it something meaningful, ideally with your hostname – for example <server-hostname>_PC.pem where “PC” = “Public Certificate”.
This public certificate will work with curl whether you’re using the default certificate from your device, a custom self-signed certificate, or a certificate signed by a Certificate Authority (CA).

You’ll need to get this file (which is downloaded as *.pem but is essentially just a text file) somewhere on your client EPIC’s file system. You can put it straight into /home/dev/unsecured via groov Manage or any other folder – but what’s important is that you know the full path to this file.

Now is the part where you’ll need to open a terminal, so you will need a free shell license. Once you’ve applied the license and opened an SSH session you’ll then need to log into the root user. I strongly suggest you back up the device and be careful going forward with root since you can cause some major damage with admin privileges’. With great power comes great responsibility.
Once logged in as root, concatenate your server certificate to the end of the ca-certificates file and make sure you use >> in between the file paths.
Here are the exact commands I used (replace the path and filename I used to wherever your public certificate is):

sudo su
cat /home/dev/unsecured/epic-terry_PC.pem >> /etc/ssl/certs/ca-certificates.crt
exit

You will have to enter your shell user’s password after typing in sudo su, then the exit command will log you out of the root user once you finish concatenating.

Once you’ve done this you can now use curl -X ... without the insecure option! You can also delete the .pem file wherever you have it stored since the content is saved in the ca-certificates file.

Happy coding!