martin carpenter

contents

trusting 3rd party certificates on ubuntu

2012/10/25, updated 2013/08/17

tags: ubuntu pki

If you run your own CA or need to trust certificates issued by a third party CA whose issuing certificate(s) are not included in the Ubuntu distribution at /etc/ssl/certs then you may need to trust them by adding them to your system.

Briefly (more detail on each of these steps below):

• Convert certificate to PEM format
• Install certificate in trusted location
• Generate fingerprint link
• Add to any other application-specific stores

Convert certificate to PEM format

Certificates are generally delivered in one of two formats: PEM (ASCII, originally described in the Privacy Enhanced Mail RFCs 1421, 1422, 1423, 1424) and DER (binary, defined in the ITU's X.690 Distinguished Encoding Rules). You need PEM. Translate binary cert.crt → ASCII cert.pem as follows:

alice@ubuntu:~$ cd /tmp
alice@ubuntu:/tmp$ openssl x509 -in cert.crt -inform DER \
    -out cert.pem -outform PEM

Install certificate and fingerprint in local store

Ubuntu has a directory for local trusted CA certificates: /usr/local/share/ca-certificates. Copy your PEM file into this directory (any filename that you choose). The file should be owned by root:root and with mode 644 (rw-r--r--). Clearly you don't want this file (or indeed directory) to be writable by anyone other than root. Oh, and you should be really sure that you do trust the certificate that you're about to add.

alice@ubuntu:~$ cd /usr/local/share/ca-certificates/
alice@ubuntu:/usr/local/share/ca-certificates$ sudo cp /tmp/cert.pem .
alice@ubuntu:/usr/local/share/ca-certificates$ sudo chown root:root cert.pem
alice@ubuntu:/usr/local/share/ca-certificates$ sudo chmod 0644 cert.pem

(You should probably choose a better name than cert).

For fast location of a specific certificate on the file system a long-standing OpenSSL mechanism creates symlinks named after the subject hash to the actual friendly-named version. (The hash filenames are postfixed with an integer extension in case you happen to have two certificates with the same subject hash, for example if a certificate has been renewed). You can generate these links using c_rehash from OpenSSL:

alice@ubuntu:/usr/local/share/ca-certificates$ sudo c_rehash .

Create link from system store

Some software does not know about /usr/local/share/ca-certificates so requires a link from the system store in /etc/ssl/certs.

alice@ubuntu:~$ cd /etc/ssl/certs
alice@ubuntu:/etc/ssl/certs$ sudo ln -s /usr/local/share/ca-certificates/cert.pem
alice@ubuntu:/etc/ssl/certs$ sudo c_rehash .

The symbolic link nicely documents "this certificate is not part of the base install".

Other application-specific stores

Java

The JRE stores trusted CA certificates under lib/security/cacerts (similarly for the JDK this is in jre/lib/security/cacerts). You can add certificates to the store using the keytool utility shipped with your JRE.

alice@ubuntu:/tmp$ sudo keytool -import -trustcacerts -file cert.pem \
    -alias "New CA certificate" \
    -keystore /opt/jdk1.7.0/jre/lib/security/cacerts

Ruby rvm

If you're using rvm to manage your ruby environment along with a rvm-local OpenSSL package then this won't pick up certificates added to your sytem CA certificate store. The trusted certifcate store for rvm is at $rvm_path/usr/ssl/certs. Replace /usr/local/share/ca-certificates in the instructions above with this path: install the certificate at this second location and re-run c_rehash.

Miscellaneous notes

• c_rehash recreates all fingerprint symbolic links in the given directory (.).
• These certificate fingerprints are not those that you will see in, say, MSIE's certificate store which are a hash of the entire DER-encoded certificate.
• The traditional OpenSSL fingerprint algorithm takes the MD5 hash of the DER-encoded certificate subject name, munges that into an unsigned long and then converts it into a hex string. Under the covers c_rehash calls openssl x509 -subject_hash_old.
• The new OpenSSL fingerprint algorithm (changed starting with OpenSSL 1.0.0, June 2010) takes the SHA-1 hash of the DER-encoded certificate subject name, munges it into an unsigned long and then converts it into a hex string. Under the covers c_rehash calls openssl x509 -subject_hash.
• Ubuntu ships with update-ca-certificates(8). This can be used to refresh/update the CA certificates contained in /etc/ssl/certs. I don't like this approach since I like to separate certificates shipped with the system (/etc/ssl/certs) from certificates that I have subsequently added (/usr/local/share/ca-certificates).