From CSLabsWiki
Revision as of 14:20, 14 September 2015 by Northug (talk | contribs) (Making a Certificate)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

A CA, or certificate authority, is an entity at the top of an X.509 hierarchy; it forms a "trust root", an absolute endorsement of trust in the entity who manages that certificate, such that the CA can sign other certificate requests by other entities (usually for more domain-specific purposes, such as HTTPS, IRCS, SMTP STARTTLS, etc.), and that all of these certificates that are signed by the CA are automatically recognized as valid.

In the current state of the Internet, software developers for common software (e.g. Microsoft Windows, Mozilla Firefox, and many others) decide which CAs are to be trusted by default. This often includes a selection of relatively large Internet corporations, such as VeriSign, Digicert, Google, and many other, smaller ones. In general, operating systems (or, more specifically, distributions) usually have a place to put the CA certificates to be unconditionally trusted on a machine, though it's a bit of a crapshoot to determine if any one software application actually supports looking in these places. Nonetheless, any well-implemented piece of software, even if it doesn't follow this rule directly, usually allows CA's to be imported.

Hereafter, this article will focus on the implementation of the (COSI) CA, and how it may be used to secure and verify services which support TLS/SSL.

The CA Certificate

At present, the CA certificate in "golden" form is found on Talos, as the file /usr/share/ca-certificates/cosi/cosi_ca.crt. It is copied in some other places, notably in /usr/lib/ssl/misc/demoCA/cacert.pem, and in /var/www/html/, such that you should be able to acquire this certificate using wget or by navigating your web browser to . Of course, without the certificate, your UA will probably complain a little bit. (Tip: wget --no-check-certificate

Of course, this certificate should be widespread, and, in an ideal world, an unaltered version of it may be found on all of the local machines, but since when is it easy :)

Adding the CA Certificate to a Client

These instructions work specifically for Debian, though it is quite likely that other Linux distributions (and maybe some other POSIX-compatibles) have similar methods. Sorry, Windows users, you're on your own.

The current standard is to introduce the certificate under its usual filename (cosi_ca.crt) into the client in the same place as it is in Talos; that is, /usr/share/ca-certificates/cosi/cosi_ca.crt. Note that you probably will have to make the cosi directory.

After this is done, add a line to the /etc/ca-certificates.conf file with the relative path to the certificate from /usr/share/ca-certificates/; that is, something like:


Write out and close the file, and run update-ca-certificates. It should tell you that it added a certificate; if not, check the filenames (make sure it ends with ".crt").

This should configure the CA properly for applications which depend on /etc/ssl/certs/certificates.crt. As a developer, or if given the option, point your TLS/SSL clients to this file as the trust chain. If this is not the option, just make sure to import this certificate; you should know where it is now.

Making a Certificate

Because we use DNS search, we need to have certificates that are set up using subjectAltName (SANs). This is, unfortunately, not the default; however, the system on Talos is currently configured to do this properly.

For starters, you will need to make a Certificate Signing Request (CSR). First, on Talos, go to the file /etc/ssl/talos_openssl.cnf and find the lines reading:

[ v3_sans ]
DNS.1                           =
DNS.2                           = somedomain
IP.1                            =

Following the format as it is present, add the relevant DNS and IP entries. You can have as many or as few of either as you'd like; just remember that you should have at least one for every form of address of the server for the certificate you're making can take.

With that out of the way, cd into /usr/lib/ssl/misc and run the following:

openssl req -new -nodes -keyout service_key.pem -out newreq.pem -config /etc/ssl/talos_openssl.cnf

Note: The -nodes option prevents password encryption of the key file. While important for services, for which including a password would be extra work and simply inappropriate, it does mean that the keyfile is a red key--it contains unprotected cryptographic material! Handle it with care.

The filename newreq.pem is important, but you can rename service_key.pem to whatever you please.

Note: If, at any point, you realize you've botched a parameter, you can generate a certificate signed with an earlier key (faster than making another) by changing the -keyout option to -key.

With this done, use the CA script in the directory to proceed:

./ -sign

It will prompt for the password to the CA keyfile. (If you do not already have it, please contact Jeanna Matthews for the "Secure Services Master Password.") Assuming all goes well, it should give a textual dump of the contents of newreq.pem, which you should double-check to see that it has all the fields and correct values. Assuming it does, answer the prompt with "y" to sign it, and again with "y" to commit it to the database. If all goes well, it will create a file newcert.pem in the same directory. (If all does not go well, the file will be empty, and you should start troubleshooting this.)

newcert.pem is your CA-signed certificate. You should take this file (possibly after renaming it to something more sensible, like "service_cert.pem"), as well as the key file, and move these (securely) to their final residence. Most service software will have a way to specify both these files to enable TLS/SSL support; do so, and you should be good!

Talos' Setup

While this should never have to happen again (for a good while), this section details the setup process for the COSI CA as it exists on Talos.

First, dedicate a directory to containing the CA administrative info; out of laziness, we chose the directory where the important script was already located. You should use another, properly-permissioned, empty directory to do the same, then copy there.

Once this is done, run:

./ -newca

Answer the questionnaire, and it should create a directory demoCA under your working directory with the necessary files.

Inside demoCA, you will find a file cacert.pem. This is your CA certificate. You will want to distribute this to all the clients you want to trust certificates you sign from here on out. As noted above, installation procedures for different platforms and different software packages will vary, so this will easily be the hardest part of the process.

Now for some fun: in order for SANs to work properly, some non-default configuration (on Debian, at least) of the /etc/ssl/openssl.cnf file must be done. Open this in your favorite editor, and uncomment the line that reads:

copy_extensions = copy

Note: This does make you more vulnerable to various unsanitized certificate requests--including those for other CA's. Be wary about signing a certificate you did not generate!

After writing and closing this file, copy it to another file; on Talos, this file is /etc/ssl/talos_openssl.cnf, but feel free to name it what you like. Note that this file is the one used in the -config switch for making a new certificate, above.

Open this file for editing, and uncomment a line starting with:

req_extensions =

You can change the name of anything past the = to whatever you like, so long as it is a unique header in that file. In Talos' config, it is set to

req_extensions = v3_req_san # The extensions to add to a certificate request

Now go down to just before a section header (in []) and prepare another section by that name. Following Talos' example, this would consist of the following:

[ v3_req_san ]
basicConstraints                = CA:FALSE
keyUsage                        = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName                  = @v3_sans

You can change the v3_sans to another arbitrary name, but make sure to rename it in the corresponding section, which should look as it does in the Making a Certificate section above.

Congratulations! After this, your setup should match the one on Talos (which is still far from ideal, but nonetheless workable).