Key Revocation Lists on OpenSSH – A Free Software Knowledge Base

The gist

The Secure Shell SSH enables to connect to a remote host using an encrypted connection to run commands through a command interpreter (Unix shell) or to transfer files using its SFTP protocol.

To guarantee the identity of the server to the connecting client, the SSH server provides SSH keys that the client can verify, either using an already recorded key (in a known_hosts file), or by verifying the signature of the key generated by a trusted certification authority (see our article “Presentation and use of SSH certificates”).

Likewise, upon connection, a server can authenticate a client by requiring an SSH key to prove the identify of the user, here again either by using a previously authorized and recorded key (in an authorized_keys file), or by verifying the signature of the key generated by a trusted certification authority.

As a complement to this possibility of trusting a key for authentication, OpenSSH allows the revocation of the trust granted to a key or to a certificate, which can be particularly useful in case the key is compromised.

In this document, we will show in practice how:

a server can revoke keys or certificates used by clients;
a client can revoke keys or certificates used by servers.

Read on below for details or ↓ skip to the takeaway

Key revocation lists

The OpenSSH server and client both allow to specify revocation lists that designate keys or certificates that have been revoked:

a key or certificate designated in a revocation list used by a client cannot be used to verify the identity of a server;
likewise, a key or certificate designated in a revocation list used by a server cannot be used to authenticate a client.

These revocation lists can be provided in two forms:

text files providing a list of revoked keys;
or binary files in an OpenSSH format called Key Revocation Lists (KRLs), generated from text files using the command ssh-keygen -k.

Creation of a KRL revocation file

Use of `ssh-keygen -k`

These KRL files can be created using the command ssh-keygen -k. To later add references of additional keys or certificates, the option -u must also be used. The name of the KRL binary file that will be generated must always be specified using the option -f filename.

Caution: used without the -u option, the -k option will overwrite the content of an existing KRL file without prior notice.

However, when the option -u is used, the output file must exist. It can therefore be a good habit to first create an empty KRL file using the -k option alone, without any input file:

$ ssh-keygen -k -f revocation_list.krl
$ file revocation_list.krl
revocation_list.krl: OpenSSH key/certificate revocation list, format 1, version 0, generated Fri May 12 12:05:23 2023

The -u option can then be systematically used along with -k and thus avoid overwriting existing information in the file. For example, to revoke a key stored in example.pub:

$ ssh-keygen -ku -f revocation_list.krl example.pub
Revoking from example.pub

To populate the KRL file, ssh-keygen -k needs input text files that include:

a list of keys, one per line, which means, for example, a content similar to:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...4DE8KbbGA34JBTYEVOdOucjz herschel@laptop
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXN...W2yAX7g26E73LWSI= alice@ordi1
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...xioxrHTsQl2chRU0zuB/+yPz juliet@julietpc

or a KRL specification, which include a directive on each line, followed by a colon (:) and the information specific to the directive. Each of these lines will designate a key or certificate to include in the generated list. The section below details the format of these specifications.

KRL files being binary files, the command ssh-keygen -Q must be used to examine its content. By default, the command returns a zero exit code if none of the keys in the files mentioned in the arguments is revoked by the KRL file, and a non-zero exit code only if at least one of the provided keys is revoked:

$ ssh-keygen -Q -f revocation_list.krl ssh_host_ed25519_key.pub
ssh_host_ed25519_key.pub (root@server): REVOKED

Using the additional -l option, the content of the KRL file is printed:

$ ssh-keygen -Q -l -f revocation_list.krl
# KRL version 0
# Generated at 20230512T120523

hash: SHA256:SHA256:ZvMiKrEjFWXWvZNIAraoHDb6Nwp+4mytu7jL5YyZwc8 # ssh-ed25519
hash: SHA256:66f3222ab1231565d6bd934802b6a81c36fa370a7ee26cadbbb8cbe58c99c1cf

# CA key ssh-ed25519 SHA256:e7wnSbMmyStx4K0+Mk3dj/03m/bI4Fk823EL0WdD8l4
id: Test server

KRL specifications

In a KRL specification, a key or certificate can be designated using the following directives:

serial: to designate a certificate with a serial number other than zero (assigned on the certificate creation using the -z option of ssh-keygen). Using this directive requires the public key of the certificate authority to be provided with the option -s ac.pub;
id: to designate the certificate by its identifier (assigned on the certificate creation using the -I option of ssh-keygen). Note that, although the command ssh-keygen -L uses quotes to display the identifier (under the label Key ID), the value provided in the KRL file must not be quoted, even if it includes spaces. Using this directive, here again, requires the public key of the certificate authority to be provided with the option -s ac.pub;
key: to designate a key by including its base64 value;
hash: to designate a key using its SHA256 fingerprint that can be found in the SSH server logs or using the command ssh-keygen -l -f key.pub.

Here is an example of a KRL specification file including an example of each mentioned directives:

serial: 42
id: Test server
hash: SHA256:ZvMiKrEjFWXWvZNIAraoHDb6Nwp+4mytu7jL5YyZwc8
key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHldYQOwXC+FRPWqI4ebXg7rbhd+ZW/VSfi44FTQFly5 beelzebot@hell

The keys and certificates designated by these directives (stored, in our example, in a file new_revocation_list.spec) can be added to an existing revocation list stored in a binary KRL file (revocation_list.krl in our example) using the following command (the option -s ac.pub is required because we used the directives serial and id that both require the key of the certificate authority):

$ ssh-keygen -ku -f revocation_list.krl -s ac.pub new_revocation_list.spec
Revoking from new_revocation_list.spec

This file can then be used by an SSH server or client.

Use of a revocation file by an SSH server

Configuration to use

To use a key or certificate revocation list, the corresponding file must be designated in the configuration of the SSH server (in the file /etc/ssh/sshd_config on Debian GNU/Linux systems) using the directive RevokedKeys:

RevokedKeys /etc/ssh/revocation_list

As indicated before, this file revocation_list can be:

a text file including a public key on each line;
a binary file in the KRL format generated by the command ssh-keygen -k as detailed above.

Caution : if the file designated by RevokedKeys cannot be read, any connections using keys for authentication will be refused by the server.

This situation will be clearly identified in the system logs on each connection, with a message like:

error: Error checking authentication key ED25519 SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE in revoked keys file /etc/ssh/revocation_list: No such file or directory

It is therefore required to create the file before restarting the SSH server to update its configuration. The file can, for example, be created as en empty file using the command:

touch /etc/ssh/revocation_list

The OpenSSH server must be restarted to re-read its configuration:

service ssh restart

Clients using a key or certificate included in the revocation list will then no long be able to log in.

Although the documentation for the directive RevokedKeys in the manual sshd_config(5) only mentions the possibility to list SSH keys in a text file designated by this directive, in practice it is also possible to include certificates.

However, the inclusion of a certificate will revoke not only the certificate, but also the SSH key that corresponds.

Be aware that this behaviour is different from designating a certificate in a KRL file (using its serial number or identifier, for example), as, in this case, only the use of the certificate would become impossible, and the use of the SSH key would still be possible (provided, of course, that the key is authorized in the file authorized_keys of the account).

It then seems better not to include a certificate when using a text file with RevokedKeys, as this use is undocumented and seems to lead to unexpected results.

Server behaviour

In case of revoking an SSH key:

if a client tries to use only the key to connect, the SSH server logs (by default auth.log on Debian GNU/Linux systems) will mention it:
```
error: Authentication key ED25519 SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list
```

if a client tries to connect by presenting a certificate based on this key, the SSH server logs will mention both the key and the certificate:

error: Authentication key ED25519 SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list
error: Authentication key ED25519-CERT SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list

In case of revoking an SSH certificate:

when this certificate is presented by a client, the authentication will be refused and the SSH server logs will mention the attempted use of the certificate, along with the SHA256 fingerprint of the corresponding key:
```
error: Authentication key ED25519-CERT SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list
```
if the client tries to connect using the key corresponding to a revoked certificate, the connexion will be allowed (providing, of course, that the key is included in the authorized_keys file of the account), as only the certificate is revoked.

Use of a revocation file by an SSH client

Configuration to use

To revoke keys or certificates provided by a server for its authentication, the revocation file must be designated using the directive RevokedHostKeys in the client configuration file ~/.ssh/config:

RevokedHostKeys /home/herschel/.ssh/revocation_list

Here again, this file can be:

a text file including a public key on each line;
a binary file in the KRL format generated by the command ssh-keygen -k as detailed above.

Unlike other directives in the file ~/.ssh/config like IdentityFile, the directive RevokedHostKeys does not interpret the ~ as the home directory of the account in the file path. A relative path would be interpreted as relative to the current working directory of the ssh process. An absolute path must therefore be used here (at least on OpenSSH 8.4).

If the client cannot read a revocation file, the authentication of the server will fail and the connection will stop. The client would print a message similar to:

Error checking host key ECDSA SHA256:wxocsORNEfXuuTcXGwitKR8RUompGbgpXTEsXXirAFI in revoked keys file /home/herschel/.ssh/revocation_list: No such file or directory
Host key verification failed.

Client behaviour

Note that, contrary to what we could imagine at first glance, revoking a server key will not systematically prevent its authentication and forbid any connection to it.

The revocation indeed applies to particular keys or certificates, and a server usually provides several keys and certificates of different types that the client will consider sequentially (based on an order of algorithm types defined by the directive HostKeyAlgorithms in the client configuration).

Consequently, if the client does not revoke all certificates and keys provided by a server, the connection will be cancelled only if the first certificate or the first key of the server considered by the client is designated in the revocation list used by the client.

Should it be the case, the connection will be cancelled by the client with an explicit message such as:

$ ssh -i ~/.ssh/id_ed25519 lab.example.org
Host key ED25519-CERT SHA256:ZvMiKrEjFWXWvZNIAraoHDb6Nwp+4mytu7jL5YyZwc8 revoked by file /home/herschel/.ssh/revocation_list
Host key verification failed.

Using the command ssh with its option -v, the client will mention more information about the revoked certificate provided by the server:

$ ssh -v -i ~/.ssh/id_ed25519 lab.example.org
...
debug1: Server host certificate: ssh-ed25519-cert-v01@openssh.com SHA256:ZvMiKrEjFWXWvZNIAraoHDb6Nwp+4mytu7jL5YyZwc8, serial 0 ID "Test server" CA ssh-ed25519 SHA256:e7wnSbMmyStx4K0+Mk3dj/03m/bI4Fk823EL0WdD8l4 valid forever
Host key ED25519-CERT SHA256:ZvMiKrEjFWXWvZNIAraoHDb6Nwp+4mytu7jL5YyZwc8 revoked by file /home/herschel/.ssh/revocation_list
Host key verification failed.

In the case the client considers, before any other key or certificate, a key or certificate that was not revoked and is trusted, the server will be correctly authenticated and the client will continue with the connection and proceed to its own authentication.

For reference, if the client receives a server key it revoked, the printed message will be similar and will mention the key:

$ ssh -v -i ~/.ssh/id_ed25519 lab.example.org
...
debug1: Server host key: ecdsa-sha2-nistp256 SHA256:wxocsORNEfXuuTcXGwitKR8RUompGbgpXTEsXXirAFI
Host key ECDSA SHA256:wxocsORNEfXuuTcXGwitKR8RUompGbgpXTEsXXirAFI revoked by file /home/herschel/.ssh/revocation_list
Host key verification failed.

Lastly, note that if a client considers a server certificate it has revoked, it will refuse to connect to the server, ignoring any previously authorized key presented by the server and stored in the known_hosts file.

Takeaway

As the OpenSSH server can authenticate a client and the OpenSSH client a server based on SSH keys (or certificates), a mechanism was also necessary to revoke a key or certificate (e.g. in case a key is compromised). OpenSSH enables revoking a key (or a certificate) through Key Revocation Lists (or KRLs):

an OpenSSH server can designate a key revocation list in its configuration file sshd_config using the directive RevokedKeys:
```
RevokedKeys /etc/ssh/revocation_list
```
as for the OpenSSH client, it can designate such a key revocation list in its user configuration file ~/.ssh/config using the directive RevokedHostKeys:
```
RevokedHostKeys /home/herschel/.ssh/revocation_list
```

In both cases, the file can use the same format:

either a text file including a public key on each line;
or a binary file in a specific KRL format generated by the command ssh-keygen -k.

KRL binary files are created from input text files composed either of a list of keys (one per line), or of KRL specifications using the directives serial, id, key ou hash to designate a key or certificate respectively by its certificate serial number, certificate identifier, the key itself, or its SHA256 (as included in the OpenSSH server logs or printed by the command ssh-keygen -l -f key.pub).

The content of these binary files can then be printed using the command ssh-keygen -Q -l -f revocation_list for visual verification. Revocations of specific keys can also be tested using the command ssh-keygen -Q -f revocation_list keys.txt, the keys to test being provided in the files mentioned in the arguments (such as keys.txt here).

Once a revocation list is configured:

on the server site, the connection of a client using a revoked key (or a certificate whose corresponding key is revoked) will be forbidden and a message printed in the system logs:
```
error: Authentication key ED25519 SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list
error: Authentication key ED25519-CERT SHA256:QfLKGkjku0mCMS9bTJPtuCkie3Cr158kb9C7axTYXRE revoked by file /etc/ssh/revocation_list
```
When a certificate is revoked, a client that present it will no longer be able to get authenticated (and an message similar to the one above will be printed in the system logs). The client will however still be able to continue using the corresponding key alone (provided it was authorized in the file ~/.ssh/authorized_keys of the remote account).
on the client site, the establishment of a connection to an SSH server will be cancelled because of a revoked key or certificate only if the key or certificate is the first considered by the client (following an order defined in the client configuration by the directive HostKeyAlgorithms). If the client first considers a key of certificate that is not revoked and is trusted, then the connection will continue normally.

Key revocation lists

Creation of a KRL revocation file

Use of ssh-keygen -k

KRL specifications

Use of a revocation file by an SSH server

Configuration to use

Server behaviour

Use of a revocation file by an SSH client

Configuration to use

Client behaviour

Use of `ssh-keygen -k`