Certificate Installation with OpenSSL - Other People's Certificates

Note: In the case of self signed remote server certificates, you need this guide

This is where you want to install the certificate for just one server, when you don't want to install the certificate for the CA that signed the server certificate. Normally you wouldn't want to do this, as by installing the CA certificate you will be able to connect to other servers with certificates signed by the same CA without further effort.

Probably the only time you would want to install only the certificate for one server but not for the CA is where you only trust the server opperator, but not their CA. However, in this case I'd suggest you start prodding the server opperator to get their certificates from a more trust-worthy supplier...

If you do only want to add the server certificate and not the CA, it is supprisingly simple. As far as OpenSSL is concerned, there is very little difference between a self signed certificate and a server certificate for a non trusted CA - they both require a highest level trusted entity of themselves.
Thus, you just just treat the server certificate as if it were a self signed server certificate, and install that as per the guide below.

Installing Self Signed Certificates into the OpenSSL framework

This bit of the document isn't quite finished. As a quick hack, follow the CA Certificate Install Guide, but with both the server certificate and the CA certificate being the same thing, which is the self signed certificate.

Installing CA Certificates into the OpenSSL framework

First off, you'll need to know where your version of OpenSSL thinks its certificates, keys etc are all stored. This will depend on what version of OpenSSL you're using (not much), but more importantly, where it came from (tar ball / rpm / deb / bsd ports etc). Below are a few common places.
From now on, we'll refer to this directory as <ssl-base-dir>

General built from source, OpenSSL 0.9.x <prefix>/ssl/ (either the system default, or overriden at configure time with "--prefix foo")

Another way to check On most OpenSSL builds, if you run the command openssl version -d it will report the directory used, eg OPENSSLDIR: "/usr/lib/ssl" (directory is /usr/lib/ssl). On some systems (eg Ubuntu), the path given from this will contain a symlink to the real certificates store elsewhere on the system, so you might want to double-check!

Note - if you run an alternate system to the above, let me know where it hides so I can add it to the list

In <ssl-base-dir>, you should find subdirectories of certs and private at a very minimum, probably a few more too (eg csr, lib, misc etc). If you don't find these two in what you think is <ssl-base-dir>, either you've got the wrong place place, or you've got a faulty open-ssl install. You can try to find it by searching for the directory "certs".

Fistly, a quick word about the files used below:

ca-certificate-file means the PEM formatted certificate of your CA.
server-certificate-file means the PEM formatted certificate of a server which has been signed by the CA (normally the server you were trying to connect to when you ended up here).

In the case of a self signed certificate, these two will be one and the same.

Before you can begin, you need to get the certificate from your CA. Ideally, get it in PEM format, otherwise you'll need to convert it.

Slight Aside: You need to ensure there's only one CA certificate in the file from your CA. Normally there is, but ocassionally several are stored in the same file. To list the number of certificates in a file, use the command below. If you get an answer of more than one, then see the section on multiple certificates in one file. The command to check the number of certificates in a file is:

Once the certificate is in PEM format and you know there's only one certificate in the file, you need to verify it. First up, find the fingerprint for the CA from a trusted source (and I can't stress this one enough). Now, calculate the fingerprint for the certificate you've downloaded, and ensure they're the same. To find the fingerprint, use:

Assuming they match (if they don't, you've either done something wrong, or its time to start panicing), we can install the certificate. As root (and now would be an ideal time to check you need to be root - only root should have write access, but the certs directory needs to be world readable). Copy your CA certificate to <ssl-base-dir>certs/ and finds out its Hash. OpenSSL looks for certificates using an 8 byte hash value. Calculate it with:

In order for OpenSSL to find the certificate, it needs to be looked up as its hash. Normally, you would create a symbolic link for a meaningful name of the CA to the hash value, rather than renaming the CA certificate. Ideally, create a symbolic link (or hard link if you must, but symbolic ones usually make spotting which hash is which certificate name that bit easier). The symbolic link must be for the hashed value above plus ".0" - if you forget the .0 then OpenSSL won't detect it, and you'll get lots of errors.
Thus, I have for the current Oxford University CA:

dbed1725.0 pointing to oxford-ca.pem
(dbed1725 is the hash of the CA certificate)

We're now to test this installation. To do so, we really want a certificate that's been signed by the newly installed CA. Failing this, you can use the CA certificate, but this won't always cause all the possible errors to show up. Run:

If you've got it correct, you should see something like:
oxford-herald2-server.pem: OK
Which tells you that your CA certificate is correctly installed.

However, if you see something like:
oxford-ca.pem: /C=GB/ST=Oxfordshire/L=Oxford/O=Oxford University/OU=Computing Services/CN=Oxford University Computing Services CA/Email=ca@computing-services.oxford.ac.uk
error 18 at 0 depth lookup:self signed certificate
You've got something wrong. Go see the errors page for more information, and probable causes.

Using a CRL

In order to check that the certificate you've just been presented (for whatever reason) is still valid (and hasn't been revoked), you'll need to check a CRL (certificate revocation list). These are published by CAs.

In most cases, you'll need some sort of automated script to pull (and verify!) the latest CRL of all CAs you trust, at some periodic interval. Once a week is usually good enough, unless it really matters to you that a revoked certificate can't be used, in which case you'll want a time closer to the CRL update frequency. YMMV, you'll need to decide for yourself.

In some cases, you can use an OCSP (Online Certificate Status Protocol) client (such as the one with OpenSSL) to query the CA each time. Much bigger overheads than keeping a static list, requires the CA to support it, but will allow you to start rejecting revoked certificates ASAP. It's up to you to decide if you need that or not...

Apache & CRLs:

You should already have a CRL directory, normally apache conf dir/ssl.crl/, but if not create on wherever your certificates etc live. To configure apache to check the CRL lists, add the following directive to your apache mod_ssl config block (i.e. the ssl virtual host config):
SSLCARevocationPath crl_directory
eg SSLCARevocationPath /etc/httpd/conf/ssl.crl/

You then need, for every CRL list, to symlink it to something based on it's hash. The file will need to be called crl_hash.r0, which you can magically achieve with:
ln -s ca.crl `openssl crl -hash -noout -in ca.crl`.r0
(You need to do this for every crl file in the directory).

OpenSSL tools & CRLs:

You need to have a crl directory. Normally this will be <ssl-base-dir>/crl/, but you can change that in your openssl.cnf file (normally to be found in <ssl-base-dir>). Everyone needs to be able to read this directory (and everything in it), but no-one except the CRL fetch process should be able to write to it!

You need to symlink the CRL files to a special name based on their hash, much like you have to with the CA certificates. This time the name is hash.r0, so your friend is:
ln -s ca.crl `openssl crl -hash -noout -in ca.crl`.r0
(Well, that is, unless your apache has a handy makefile to do it all for you, in which case just pop the crls in the directory and run make).

Using OpenSSL OCSP:

Installing CA Certificates on Mac OSX

Mac OSX 10.0 to 10.4

The tool for handling CA Certificates, server certificates etc on OSX is called "certtool".
Firstly, make a copy of the system trusted keychain in your home directory, so you can work on it using certtool. Do that with:
cp /System/Library/Keychains/X509Anchors ~/Library/Keychains/

Now, install the PEM formatted certificate into your local trusted keychain with:
certtool i mycertificate.crt k=X509Anchors
This should install the certificate. If you have problems, check the certificate format (shouldn't be binary), and check the manual for certtool.

Once the certificate is in your keychain, you need to make it system wide. You do this by copying (as root / using sudo) your trusted keychain back as the system one, with something like:
sudo cp ~/Library/Keychains/X509Anchors /System/Library/Keychains/
With that done, restart Safari, Mail etc, and they should then pick up the new CA certificate.

Mac OSX 10.5 (Leopard) onwards

It is no longer possible to import certificates into Leopard on the command line. Instead, you need to use the Keychain Access application (ask finder for it).

For reasons unknown, you will need to have your CA Certificate in PKCS12 format, unlike everything else on the planet, which is happy with normal X509 DER or PEM format. In order to turn your Certificate into the correct format, see here. Note that you will need to export the certificate with a password, as OSX seems incapable of importing a password-less file.

Having got your PKCS12 certificate file, load up Keychain Access and unlock with your sudo password. In the left hand side, pick System. Now choose File then Import Items, and import the your CA certificate .p12 file. Pick Trust Always when importing.

Notes for OSX

Note that these installation instructions will not affect Mac IE, Entourage etc. For those, install the certificate as normal for IE

Installing CA Certificates for OpenLDAP

OpenLDAP can be compiled against either OpenSSL, or GNUTLS. In either case, it won't use the system list of CA certificates.

To prime the server (slapd) with your CA certificate, add an entry to slapd.conf of the form:

For the client side (ldapsearch et al), you need to add an entry to ldap.conf (note that you may have two different copies, one in /etc/ and the other in /etc/ldap/ or /etc/openldap/) of the form:

(If you use the OpenLDAP module in PHP, you'll then need to copy this ldap.conf file to .ldaprc in the home directory of the webserver.)

Installing CA Certificates for use within Java

Before you can install a CA Certificate for use within your Java JVM, you need to know two things. Firstly, you need to know your keystore password. If you haven't changed it since installing java, then this will be changeit. However, if you have changed it from changeit, you'll need to remember what you changed it to!

Secondly, you'll need to know where your Java JRE is installed. This will vary from system to system, JRE to JRE etc, so there's no quick answer. You are looking for the directory that holds the likes of bin/java, bin/keytool, and lib/security/cacerts. Use whatever search tools your OS provides to find this.

Once you've located your JRE home, it's quite easy. Just get a copy of the CA certificate to hand, decide on a friendly name for it (which will be shown when listing the keystore), and change into the JRE home directory. Run:

bin/keytool -import -trustcacerts -alias CAFriendlyName -file ca-certificate-file.crt -keystore lib/security/cacerts

You will be prompted for your password (changeit, assuming it wasn't changed), and then asked if you want to trust the certificate. Answer yes, and you're away. The process will look something like:

Guides Index

Written By: Nick Burch Last modified: Tuesday, 20-Jan-2015 12:09:10 GMT
These pages are from http://www.gagravarr.org/writing/openssl-certs/

This work is licensed under a Creative Commons License.