OpenSSH Certificates

OpenSSH supports a proprietary version of certificates that allow simple login to hosts.

Traditional Method

The usual way to enable a user U to access a specific host H using SSH is to copy the public key of U in a file on H (typically called authorized_keys).

This method suffers from a lack of generality. If another user U' were to be given access to H, their public key should also be copied in that same file. At the same time, if U were to be given access to a different host H', their public key would have to be added to an equivalent file on that host.

While various automatic provisioning systems have been devised, those still represent a workaround rather than a solution to the problem.

OpenSSH CA

Since version 5.4 (released 2010-03-08) OpenSSH has had support for so-called OpenSSH Certificates.

By using these, only one OpenSSH CA public key has to be copied onto the target host. At that point any user can be granted access to any such host by giving them a file that contains the following information: their own public key, a validity period, a list of usernames that the user it allowed to login as and a digital signature over the whole content created using the private key of an SSH CA.

This file, the SSH Certificate, is then automatically presented to the SSH server by the SSH client of the user as part of the login process.

OpenSSH Certificates with YubiHSM

The private key of an SSH CA is a regular private key and can be stored on a YubiHSM. In fact, OpenSSH has builtin support for signing SSH Certificates using CA private keys that reside on a hardware token through the PKCS#11 interface.

The YubiHSM however has specific support for signing SSH Certificates and this guide will describe how to leverage that.

High-level Description and components

A YubiHSM device is able to sign OpenSSH public keys when those are submitted to the device as part of a specific format that we call OpenSSH Certificate Request.

Such a request is granted (i.e., the signature is computed and released), if and only if the following two requirements are fulfilled:

  • the user who sends the request to the device has the right privileges to access the OpenSSH CA private key on the device;

  • the OpenSSH Certificate Request meets a series of pre-defined constraints.

The first requirement is fulfilled by making sure that the user submitting the request (who may not be the same one who generates the request) can establish a Session with the device through an Authentication Key that has access to the necessary Domains and has the necessary Capability set.

The second requirement is fulfilled by encoding those pre-defined constraints in an object with Type Template and Algorithm SSH Template.

SSH Template

An SSH Template is a binary object that can be used to restrict how and when an SSH CA private key should be used to sign SSH Certificate Requests.

This is a binary object that encodes a series of constraints. Its format is a collection of Tag-Length-Value tuples whose meaning is described below:

Tag Value Tag Description

0x01

Timestamp key algorithm

0x02

Timestamp public key

0x03

CA key white-list

0x04

Not before

0x05

Not after

0x06

Principals black-list

The individual tags are further explained below.

Timestamp Key Algorithm

The Algorithm of the public key used to verify timestamp signatures.

Timestamp Public Key

The public key used to verify timestamp signatures.

CA Key White-list

The list of Object IDs describing which Asymmetric Keys can be used with this template.

Not Before

The Not Before time offset to be applied to the current time. If a request contains a time value that is before this computed timestamp, an error will be returned.

Not After

The Not After time offset to be applied to the current time. If a request contains a time value that is after this computed timestamp, an error will be returned.

Principals Black-list

The nul-separated, nul-terminated list of Principals (user names) for which a certificate will not be issued.

SSH Certificate Request

An SSH certificate format is defined by OpenSSH but it is not too dissimilar from an X.509 certificate. At its core it is a collection of attributes, a time period, a public key and a signature over all the data.

An SSH Certificate Request is the set of information that must be sent to a YubiHSM so that it can generate the aforementioned signature. This consists of all the data present in the certificate (excluding the signature).

Signing an SSH Certificate Request

Once an SSH Template has been stored on the YubiHSM and an SSH Certificate Request has been created, it can be sent to the device for signing.

This is done by issuing the Sign SSH Certificate Command. The parameters required are:

  • the Object ID of the SSH CA key which has already been stored on the device

  • the Object ID of the SSH Template to use in order to validate the request

  • the Algorithm to use to produce the certificate signature

  • the timestamp with the definition of Now

  • the signature S~T~ over the SSH Certificate Request and the timestamp

  • the SSH Certificate Request

After the command is issued, the following steps take place in the YubiHSM. First the the signature S~T~ is verified using the public key present within the specified SSH Template. If the verification is successful, the value of Now is recorded. Next the SSH Certificate Request is parsed to extract the Not Before and Not After timestamps together with the list of Principals. The following checks are then performed:

  • the ID of the SSH CA key must appear in the SSH CA key white-list present in the SSH Template

  • the Not Before timestamp in the SSH Certificate Request must be greater than or equal to Now plus the Not Before offset specified in the SSH Template

  • the Not After timestamp in the SSH Certificate Request must be less than or equal to Now plus the Not After offset specified in the SSH Template

  • none of the Principals specified in the SSH Certificate Request must appear in the Principals black-list SSH Template

If all the constraints were fulfilled, the YubiHSM will produce a signature using the Algorithm specified in the command. This signature can be appended to the SSH Certificate Request to produce a valid SSH Certificate.