YubiKey/SSH

From Gentoo Wiki
Jump to:navigation Jump to:search

YubiKeys can be configured to authenticate SSH connections in multiple ways.

Many YubiKeys can be configured to provide FIDO/U2F authentication. OpenSSH 8.2p1+ supports ed25519-sk and ecdsa-sk algorithms.

Most YubiKeys can be configured to provide GPG authentication. In this mode of operation, the gpg-agent is used instead of the typical ssh-agent.

Introduction

YubiKeys provide several interfaces which can be used to authentication or encryption. Several of the authentication modules provided by YubiKeys can be used for SSH authentication. U2F is extremely secure, and can be set up in multiple ways without much configuration.

Important
net-misc/openssh must be at least version 8.2p1 for FIDO/U2F functionality.
Important
The YubiKey must have firmware 5.2.3+ to use ed25519 keys.

Additionally, SSH authentication is possible using the OpenPGP module on a YubiKey.

Installation

USE flags

USE flags for net-misc/openssh Port of OpenBSD's free SSH release

+pie Build programs as Position Independent Executables (a security hardening technique)
+ssl Enable additional crypto algorithms via OpenSSL
audit Enable support for Linux audit subsystem using sys-process/audit
debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
kerberos Add kerberos support
ldns Use LDNS for DNSSEC/SSHFP validation.
legacy-ciphers Enable support for deprecated, soon-to-be-dropped DSA keys. See https://marc.info/?l=openssh-unix-dev>m=170494903207436>w=2.
libedit Use the libedit library (replacement for readline)
livecd Enable root password logins for live-cd environment.
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
security-key Include builtin U2F/FIDO support
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
static !!do not set this during bootstrap!! Causes binaries to be statically linked instead of dynamically
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
verify-sig Verify upstream signatures on distfiles
xmss Enable XMSS post-quantum authentication algorithm
Data provided by the Gentoo Package Database · Last update: 2024-10-30 18:38 More information about USE flags

The security-key USE flag is not enabled by default and must be enabled for U2F/FIDO support.

Emerge

root #USE=security-key emerge --ask net-misc/openssh
Note
The security-key USE flag must be set for U2F functionality.

If using gpg-agent:

root #emerge --ask app-crypt/gnupg
Important
The smartcard use flag must be set to use gpg with YubiKeys.

Configuration

GPG

To configure GPG keys, the following article can be followed: Configuring GPG keys on a YubiKey

The general process is to generate the keys, then load them onto the YubiKey.

U2F

There are two main ways U2F can be used on a YubiKey.

The first method, Non-Discoverable credential mode, requires the generation of -sk variant keys outside of the YubiKey. These keys must be securely stored, but are used in conjunction with the YubiKey for authentication. This method ensures more separation of factors, but is not suitable for environments where the private key cannot be safely stored.

The second method, Discoverable (resident) mode stores the -sk variant key on the YubiKey's storage, and enables the usage of the key in more hostile environments, but also means a attacker could potentially authenticate using the YubiKey given the private key, and U2F key are both in one place.

Note
The U2F master key is not accessible, and is only used internally. It is regenerated every time the module is reset and essentially used as a seed for U2F keys.

Non-Discoverable

With the YubiKey inserted, execute:

user $ssh-keygen -t ed25519-sk
Generating public/private ed25519-sk key pair.
You may need to touch your authenticator to authorize key generation.
Enter PIN for authenticator: 
You may need to touch your authenticator again to authorize key generation.
Enter file in which to save the key (/home/larry/.ssh/id_ed25519_sk): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/larry/.ssh/id_ed25519_sk
Your public key has been saved in /home/larry/.ssh/id_ed25519_sk.pub
The key fingerprint is:
SHA256:HjLrXXHoW/xllAnBFRw7QecrY97V+ezZTQE69wBrjOcv larry@gentoo
The key's randomart image is:
+[ED25519-SK 256]-+
|                 |
|           o     |
|      . . o +    |
|     . + .o*     |
| .o   + SoBo     |
| +.    .oXoE     |
|..o.   +O =..    |
|.  o+ .o.=oo     |
|    .**=***.     |
+----[SHA256]-----+
Note
Optionally, an ecdsa-sk key can be used.

First, ssh-keygen will prompt for the YubiKey's FIDO PIN (Enter PIN for authenticator:)

Then, it will prompt for a password to protect the private key with Enter passphrase (empty for no passphrase): .

Finally, it will prompt for a private key passphrase confirmation with Enter same passphrase again: .

Important
The file permissions of the private key must be 0600.

Destination configuration

To export public keys associated with keys in the current ssh agent, ssh-add -L can be used:

user $ssh-add -L
sk-ssh-ed25519@openssh.com AAAAW2XXFA0S2f2tHUFyEb6ktQmtjcpfO2McZKg2r/tfnqeSjMSHDNfdJ32OI0qF5M9NsVmeYcNZwldwZvh35Pbq+kaaAgVoEcB= larry@gentoo

The public key must be added to ~/.ssh/authorized_keys on the destination server, in the format:

FILE ~/.ssh/authorized_keys
# {key type} {pubkey} {name} {options}
sk-ssh-ed25519@openssh.com AAAAW2XXFA0S2f2tHUFyEb6ktQmtjcpfO2McZKg2r/tfnqeSjMSHDNfdJ32OI0qF5M9NsVmeYcNZwldwZvh35Pbq+kaaAgVoEcB= larry@gentoo verify-required
Tip
verify-required is not required but is recommended, this prompts for presence detection when logging in.

Usage

Once the keys are created and deployed on the destination, they are ready to be used.

ssh-agent U2F configuration

The ssh-agent is not required, but is helpful as it can store keys. It can be started with:

user $eval "$(ssh-agent -s)"

Successful execution should return the PID for the created agent.

Important
ssh-agent instances created this way only apply to the current shell session.

With an active ssh-agent keys can be added using ssh-add {keyfile}:

user $ssh-add example_key_file_ed25519_sk Identity added: example_key_file_ed25519_sk (larry@gentoo)

The loaded keys can be viewed with:

user $ssh-add -L
sk-ssh-ed25519@openssh.com AAAAW2XXFA0S2f2tHUFyEb6ktQmtjcpfO2McZKg2r/tfnqeSjMSHDNfdJ32OI0qF5M9NsVmeYcNZwldwZvh35Pbq+kaaAgVoEcB= larry@gentoo

Once the keys are installed, ssh can be used without entering a password if the private key is already loaded into the ssh-agent.

user $ssh remoteserver
Confirm user presence for key ED25519-SK SHA256:pdjHnsEQIzUfAyofW/Ff9KMVrqEahJPxrumDHzSr4vuN8h
user@remoteserver ~ $

U2F Agentless

If an agent is not being used, the key can be manually specified, requiring the key password on every usage:

user $ssh -i .ssh/id_ed25519_sh remoteserver
Enter passphrase for key '.ssh/id_ed25519_sk': 
Confirm user presence for key ED25519-SK SHA256:pdjHnsEQIzUfAyofW/Ff9KMVrqEahJPxrumDHzSr4vuN8h
user@remoteserver ~ $

GPG

If the OpenGPG Authentication key is being used, the GPG agent can be activated with:

user $export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)

Once activated, the gpg-agent can be used like a typical ssh-agent

See also

  • SSH — the ubiquitous tool for logging into and working on remote machines securely.

External Resources

Retrieved from "https://wiki.gentoo.org/index.php?title=YubiKey/SSH&oldid=1241327"