DEV Community: Erik Huelsmann

SSH with gpg-agent on systemd

Erik Huelsmann — Fri, 12 Jul 2024 19:43:05 +0000

There's a lot of information floating around on the web explaining how to replace ssh-agent with gpg-agent. This is important if you - like me - want to use a yubikey or smart card device to store the private key of your SSH key pair.

Unfortunately, none of the advice worked for me with the following system setup:

systemd v249
GNOME desktop 42.9
Ubuntu 22.04

Although the above is quite specific, I expect the information below to be much more generally applicable. [[edit: this article also applies to Ubuntu 24.04; I learned that after upgrading]]

Prerequisite for Yubikeys and smart cards

GPG needs pcscd and scdaemon to be able to access private keys stored on a yubikey or smart card:

$ sudo apt install pcscd scdaemon
$ systemctl enable --now pcscd
$ systemctl enable --now scdaemon

After running these commands, gpg --card-status should provide you with information about your smart card.

Configuring GPG with ssh-agent support

To enable ssh-agent support in gpg-agent, add the following to your gpg-agent.conf:

# ~/.gnupg/gpg-agent.conf
enable-ssh-support

Enabling `gpg-agent` (per user)

gpg-agent is a per-user service, which systemd facilitates with the --user flag on the systemctl command:

$ systemctl enable --user --now gpg-agent.socket
$ systemctl enable --user --now gpg-agent-ssh.socket

If you forget to add the .socket extension, systemctl will throw an error about a missing [Install] section in the service definition. Please note that the sockets are to be enabled; the service itself is to be left untouched.

Verifying status of the GPG agent can be done using:

$ systemctl status --user gpg-agent.socket
$ systemctl status --user gpg-agent-ssh.socket

Although the service is now running, the environment shows an incorrect value for SSH_AUTH_SOCK (/run/user/<uid>/keyring/ssh).

Fixing SSH_AUTH_SOCK

There are several configurations blocking successful use of gpg-agent for SSH, causing the value of SSH_AUTH_SOCK to be incorrect.

Disable `ssh-agent` user service

If it is enabled, this service needs to be disabled, as it is conflicting:

$ systemctl disable --user --now ssh-agent

Disable Xsession.options ssh-agent

The Xsession script tries to start an ssh-agent. This can be disabled by modifying /etc/X11/Xsession.options and /etc/X11/Xsession.options.d/*.conf, making sure the last file loaded contains:

no-use-ssh-agent

This is best achieved by creating a file named /etc/X11/Xsession.options.d/zz-no-ssh-agent.conf with that content.

Disable GNOME Keyring (gnome-keyring-ssh.desktop)

GNOME Keyring tries to start an SSH agent if none is running. The way to disable this is by executing the following commands - which are different from those published all around:

$ cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/gnome-keyring-ssh.desktop
$ echo "X-GNOME-Autostart-enabled=false" >> ~/.config/autostart/gnome-keyring-ssh.desktop
$ echo "Hidden=true" >> ~/.config/autostart/gnome-keyring-ssh.desktop

The "Hidden=true" addition is advertized all around the web, but didn't work for me.

Setting SSH_AUTH_SOCK

Using systemd to manage gpg-agent has one drawback: systemd doesn't set environment variables in the user shell session. This can be solved by adding this snippet to the user's bashrc:

# to be appended to ~/.bashrc
if [[ -z "$SSH_AUTH_SOCK" ]]
then
  if [[ -e "/run/user/$(id -u)/gnupg/S.gpg-agent.ssh" ]]
  then
    export SSH_AUTH_SOCK="/run/user/$(id -u)/gnupg/S.gpg-agent.ssh"
  fi
fi

Conclusion

Yubikey and smart card support with private keys on the key or card does not come out of the box, even in this day and age, but with a bit of configuration, setting up private keys on a smart card and making it work under GNOME, is doable.

Server access with SSH certificates - deep dive

Erik Huelsmann — Sat, 30 Mar 2024 17:07:21 +0000

There are a growing number of articles around which explain about the setup and use of SSH certificates, like the Wikibooks Certificate-based Authentication cookbook.

This article goes into detail where the others stop: Most articles describe how the principal in the certificate (-n argument to ssh-keygen when signing the user's key) needs to be set to the name of the user on the target host. There are however many more options that can be used on the server as well as in the certificate to manage access.

Advanced principals

By default, OpenSSH requires the name of the user logging in to be among the principals in the certificate. That is, if certificate based authentication is used, 'bob' needs to be in the list of principals to be able to:

$ ssh bob@server01.example.com

Next to this default, servers have 3 mechanisms for setting up more advanced authentication setups using principals.

AuthorizedPrincipalsFile

Using this directive, a global or per-user list of principals can be configured for access to the server. That is to say that if the server is configured with an authorized_principals file:

# /etc/ssh/sshd_config

# for a global configuration:
AuthorizedPrincipalsFile /etc/ssh/authorized_principals

# for per-user configuration, relative to $HOME:
AuthorizedPrincipalsFile .ssh/authorized_principals

which contains

access-any-user

Then, if bob has a certificate named any_bob with the access-any-user principal, he can authenticate to the server as any user:

bob@client$ ssh -o CertificateFile=any_bob-cert.pub -i any_bob sshd@server01.example.com
This account is currently not available.

The response This account is currently not available. indicates the authentication was successful and the nologin shell was executed.

Remark: Using the AuthorizedPrincipalsFile directive disables the default behaviour to accept certificates listing the target username among the principals.

Per-principal command restriction

The authorized principals file supports the same options as the authorized keys file does. Assuming server01 has a user named wacky with a regular login shell, if we change /etc/ssh/authorized_principals to contain:

command="/usr/bin/date" access-any-user

Then:

bob@client$ ssh -o CertificateFile=any_bob-cert.pub -i any_bob wacky@server01.example.com
Sat Mar 30 15:29:44 CET 2024

The source from which is being connected can be restricted using this method using the from= option. See for more options the documentation of the authorized_keys file.

Certificate based restrictions

Certificates can come with their own restrictions, independent of the restrictions specified by the server. The ones to highlight here are force-command and source-address. In case a force-command restriction in the certificate conflicts with the command restriction in the authorized principals file (i.e. they are not the same string), the mechanism is considered a mismatch (and the next mechanism - e.g. password based - is tried).

Certificate identity (`-I`) and sequence numbers (`-z`)

Although most sources hostnames for host certificates and <user>@<host> for user certificates, these can be any string value. They serve two purposes:

To identify the certificate that was presented during authentication, in the system logs (syslog or journalctl); and
To identify the certificate in the Key Revocation List (KRL)

Many articles don't specify a sequence number, but specifying one is definitely desirable to be able to revoke specific certificates.

Dynamic authorization of principals

The configuration option AuthorizedPrincipalsCommand is a global setting which may be used to configure dynamic authorized principal list generation using an external command:

AuthorizedPrincipalsCommand /usr/local/bin/dynamic-principals "%u %s"
AuthorizedPrincipalsCommandUser dedicateduser

The sshd_config man page lists the supported tokens. Each returned line on standard output must conform to the same requirements as the lines from a static authorized principals file.

Prerequisites

To authenticate servers to clients:

A host certificate authority (CA) key pair
A host CA's public key deployed to clients; configured using the @cert-authority known_hosts-marker either through
- global configuration (/etc/ssh/ssh_known_hosts)
- user specific configuration (~/.ssh/authorized_keys)
In case of a user-specified CA in authorized_keys, a principals list needs to be specified with the principals= option.

To authenticate clients to servers:

A client CA key pair
A client CA's public key deployed to servers; configured through /etc/ssh/sshd_config using the TrustedUserCAKeys configuration directive

Note: neither the client CA nor the host CA require a certificate of their own.

Conclusion

Although by default the target user name must be among the principals in the certificate, this is not a hard requirement: principals can be listed statically or dynamically on the server resulting in a successful authentication when a non-empty intersection between the server and certificate principals exists. This allows for a setup where principals define roles rather than login accounts.

Using the concepts presented in this article (especially the - certificate-based - command restriction) in combination with command restrictions in e.g. sudo opens opportunities for fine-grained control over user and admin access.

DEV Community: Erik Huelsmann

SSH with gpg-agent on systemd

Prerequisite for Yubikeys and smart cards

Configuring GPG with ssh-agent support

Enabling gpg-agent (per user)

Fixing SSH_AUTH_SOCK

Disable ssh-agent user service

Disable Xsession.options ssh-agent

Disable GNOME Keyring (gnome-keyring-ssh.desktop)

Setting SSH_AUTH_SOCK

Conclusion

Server access with SSH certificates - deep dive

Advanced principals

AuthorizedPrincipalsFile

Per-principal command restriction

Certificate based restrictions

Certificate identity (-I) and sequence numbers (-z)

Dynamic authorization of principals

Prerequisites

Conclusion

Enabling `gpg-agent` (per user)

Disable `ssh-agent` user service

Certificate identity (`-I`) and sequence numbers (`-z`)