Login with Client Certificates

Skopos has limited support for login with a client SSL (x509) certificate. It works both with the Web interface and with the CLI client (skopos). To use this, you will need:

  • for the Web interface: a client certificate file in the form supported by your browser (most browsers require a binary PKCS#12 file). This document includes instructions for creating client certificate requests and signing them with a CA certificate.
  • for the CLI interface: a client certificate and private key in PEM form (concatenated in a single file)
  • for the Skopos server: the CA certificate used to sign the client certificates. This can be either your own CA certificate or the root certificate of a public CA (if you used a public CA to sign your client certificates).

Command-line Options

Server startup:

skopos --certfile SERVER-CERT --client-ca CA-FILE

(normally, the server is ran in a container; replace skopos with the appropriate docker run command, including the necessary options to map the required files into the container's name space; see Installing Skopos and Engine Arguments)

Command-line client:

skopos --client-cert CLIENT-CERT-FILE

Browser Setup

You can import a client certificate into your browser. Once this is done, you can access your Skopos engine, if it was started with the --client-ca option. The browser will prompt you to select a client certificate to submit (once per session, remembered until you close the browser).

Chromium/Chrome

The chromium-based browsers use client certificates in the binary PKCS#12 form.

Click on: Menu / Settings / Advanced / Manage Certificates (or type 'cert' into the 'search settings' bar to find it quickly). Open the YOUR CERTIFICATES tab and click on IMPORT. Select your PKCS#12 certificate file (e.g, alice.p12). If the certificate's private key was encrypted, the browser will prompt for password once and then save the certificate in its store in unlocked form.

Mozilla Firefox

Firefox uses client certificates in the binary PKCS#12 form.

Open Preferences / Advanced / Certificates / View Certificates. Select the Your Certificates tab (this is important, Firefox has the 'Import' button on all tabs, but it will not be able to open a client certificate from any other tab).

Select your PKCS#12 certificate file (e.g, alice.p12). If the certificate's private key was encrypted the browser will prompt for password once and then save the certificate in its store in unlocked form.

Other Browsers

(coming soon)

Creating Certificates with openssl

Creating a Certificate Authority

(optional - you may already have one or you can use the services of a public CA to sign client certificates)

A CA certificate is a self-signed certificate can be used to sign other certificates. You can create your own CA to use for signing your client certificates and/or your Skopos engine's server certificate.

Use the following template to create a configuration file (replace the items found in braces with your own text), save the file somewhere on a host that has the openssl command-line tool installed:

[req]
distinguished_name=dn
x509_extensions=e
prompt=no

[e]
extendedKeyUsage=serverAuth,clientAuth
keyUsage=critical,digitalSignature,keyCertSign
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints=critical,CA:TRUE, pathlen:0

[dn]
O={organization name - this line optional}
CN={a name for your CA, e.g., your company name; required}

NOTE the extendedKeyUsage will limit the types of certificates that you can sign with your CA. This is NOT part of the x509 spec, but some servers and clients enforce the presence of the correct key usage along the entire chain up to the root CA. The example template has both serverAuth and clientAuth listed, to allow your CA to sign either client and server certificates.

Use the following command to create a new private key and a CA certificate self-signed with that key, both stored in the same file. IMPORTANT: set a strong password when prompted and protect the file from being exposed.

f=ca.pem # set this to the name of the CA file you want to be created
openssl req -batch -newkey rsa:2048 -x509 -days 3650 -out "$f" -keyout "$f" -config cert-ca.cfg # the last item is the name of the config file created from the template above

Creating a Client Certificate

Use the following template to create a configuration file for openssl:

[req]
distinguished_name=dn
req_extensions=e
prompt=no

[e]
extendedKeyUsage=critical,clientAuth
keyUsage=critical,digitalSignature,keyEncipherment,keyAgreement
subjectKeyIdentifier=hash
basicConstraints=critical,CA:FALSE

[dn]
O={org name, this line is optional}
CN={username, required - this name will be displayed as the 'logged-in user'}

First, create a certificate-signing request and a private key (in the example here, the CSR is named cert-clt.pem and the key cert-clt.pem.key), note the private key is not encrypted (do not encrypt it if the certificate is to be used with the skopos client utility; note you will have an opportunity to create a version with an encrypted key later for the PKCS#12 form of the file):

f=cert-clt.pem # the file name base for your CSR and key
openssl req -batch -nodes -newkey rsa:2048 -days 3650 -out $f -keyout $f.key -config cert-client.cfg

If you have your own CA certificate and want to sign the client certificate with it, use this command (NOTE you will need the same configuration file as the one that was used to create the signing request even though all the required information is already in the CSR file; this is a known BUG in openssl). This command assumes that your CA certificate is in a file named ca.pem and has the private key in it.

f=cert-clt.pem
openssl x509 -req -in $f -out cert-clt-signed.pem -CA ca.pem -CAkey ca.pem -CAcreateserial -days 3650 -extfile cert-client.cfg -extensions e

NOTE: if you are signing multiple certificates with the same CA certificate, always run the command from the same directory and be sure to preserve the ca.srl file that will be created on the first run. This file keeps the 'serial number' of your CA and ensures that each signed certificate has its own unique serial number.

Once the certificate is signed (whether with your own CA as above or by someone else), and you have it in a PEM-format file (e.g., cert-clt-signed.pem as from the command above), you can create the files needed for the CLI and for a browser as follows:

For skopos, simply concatenate it with the (un-encrypted!) private key:

cat cert-clt-signed.pem cert-clt.pem.key >my-client-cert.pem

For browsers, create a PKCS#12 file using openssl:

openssl pkcs12 -export -clcerts -in cert-clt-signed.pem -inkey cert-clt.pem.key -out client.p12

The above command will prompt for a password to encrypt the key (you will need to type this password later when loading the cert. into a browser). To skip this and create a PKCS#12 file with an un-encrypted password, add the -nodes option to the command.