OpenSSH supports a proprietary version of certificates that allow simple login to hosts.
The usual way to enable a user
U to access a specific host
SSH is to copy the public key of
U in a file on
This method suffers from a lack of generality. If another user
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.
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.
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.
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 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
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|
Timestamp key algorithm
Timestamp public key
CA key white-list
The individual tags are further explained below.
The Algorithm of the public key used to verify timestamp signatures.
The public key used to verify timestamp signatures.
The list of Object IDs describing which Asymmetric Keys can be used with this template.
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 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.
nul-terminated list of Principals (user names) for which a
certificate will not be issued.
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).
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
S~T~ over the SSH Certificate Request and the
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
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
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
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.