Multi-factor SSH authentication using YubiKey and SSH public keys together
UPDATE: the setup described here is flawed because it only correctly secures the primary SSH channel. ie if you use port redirection like ‘ssh -L 80:localhost:80 example.com’ then the shell session will require you to enter the yubikey code, but the port redirect will be activated and usable prior to you entering the yubikey. I’d thus strongly recommend NOT FOLLOWING the instructions in this blog post, and instead upgrade to OpenSSH >= 6.2 which has proper built-in support for multi-factor authentication, avoiding the need for this hack.
A month or two ago I purchased a couple of YubiKey USB tokens, one for authentication with Fedora infrastructure and the other for authentication of my personal servers. The reason I need two separate tokens is that Fedora uses its own YubiKey authentication server, thus requiring that you burn a new secret key into the token. For my personal servers I decided that I would simply authenticate against the central YubiKey authentication server hosted by YubiCo themselves. While some people might not be happy trusting a 3rd party service for authentication of their servers, I decided this was not a big problem since I intend to combine the YubiKey authentication with the existing strong SSH RSA public key authentication which is entirely under my control.
YubiKey authentication via PAM
To start off with I decided to follow a well documented configuration path, enabling YubiKey authentication for SSH via PAM. This was pretty straightforward and worked first time. The configuration steps were
- Build and install the yubico-pam module. You might be lucky and find your distro already ships packages for this, but I was doing this on my Debian Lenny server which did not appear to have any pre-built PAM module.
- Create a file /etc/yubikey_mappings which contains a list of usernames and their associated yubikey token IDs. The Token ID is the first 12 characters of a OTP generated from a keypress of the token. Multiple token IDs can be listed for each user.
$ cat > /etc/yubikey_mappings <<EOF fred:cccccatsdogs:ccccdogscats EOF
- Get a unique API key and secret for personal use from https://upgrade.yubico.com/getapikey/
- Add the yubico-pam module to the SSHD PAM configuration module using the previously obtained API key ID in place of
XXXX$ cat /etc/pam.d/sshd # PAM configuration for the Secure Shell service # Read environment variables from /etc/environment and # /etc/security/pam_env.conf. auth required pam_env.so # [1] # In Debian 4.0 (etch), locale-related environment variables were moved to # /etc/default/locale, so read that as well. auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_yubico.so id=XXXX authfile=/etc/yubikey_mappings # Standard Un*x authentication. @include common-auth ...snip...
This all worked fine, with one exception, if I had an authorized SSH public key then SSH would skip straight over the PAM “auth” phase. This is not what I wanted, since my intention was to use YubiKey and SSH public keys for login. The yubico-pam website has instructions for setting up two-factor authentication but this only works if both your factors are configured via PAM. SSH public key authentication is completely outside the realm of PAM. AFAICT from a bit of googling, it is not possible to configure OpenSSH to require PAM and public key authentication together; it considers either one of them to be sufficient on their own.
After a little more googling though, I came across an interesting hack utilizing the ForceCommand configuration parameter of SSHD. The gist of the idea is that instead of configuring YubiKey authentication via PAM, you use the ForceCommand parameter to get SSHD to invoke a helper script which performs a YubiKey authentication check and only then executes the real command (ie login shell).
I made a few modifications to Alexandre’s script mentioned in the blog post just linked
- Use the same configuration file, /etc/yubimap_mappings, as used for centralized yubico-pam setup
- Allow the verbose debugging information to be turned off
- Load the API key ID from /etc/yubikey_shell instead of requiring editing of the helper script itself
Usage of the script is quite simple
- Create /etc/yubikey_shell containing
$ cat /etc/yubikey_shell # Configuration for /sbin/yubikey_shell # Replace XXXX with your 4 digit API key ID as obtained # from https://upgrade.yubico.com/getapikey/ YUBICO_API_ID="XXXX" # Change to 1 to enable debug logs for troubleshooting login #DEBUG=1 # To override stanard key mapping location. This file # should contain 1 or more lines like # # USERNAME:YUBI_KEY_ID:YUBI_KEY_ID:... # # This is the same syntax used for yubico-pam #TRUSTED_KEYS_FILE=/etc/yubikey_mappings
- Create the /etc/yubikey_mappings file, if not already present from a previous yubico-pam setup
$ cat /etc/yubikey_mappings fred:cccccatsdogs:ccccdogscats
- Append to the /etc/ssh/sshd_config file a directive to enable YubiKey auth for selected users
Match User fred ForceCommand /sbin/yubikey_shell
- Save the wrapper script itself to /sbin/yubikey_shell
x DEBUG=0 TRUSTED_KEYS_FILE=/etc/yubikey_mappings # This default works, but you really want to use your # own ID for greater security YUBICO_API_ID=16 test -f /etc/yubikey_shell && source /etc/yubikey_shell STD="\\033[0;39m" OK="\\033[1;32m[i]$STD" ERR="\\033[1;31m[e]$STD" ################################################## ## Disconnect clients trying to exit the script ## ################################################## trap disconnect INT disconnect() { sleep 1 kill -9 $PPID exit 1 } debug() { if test "$DEBUG" = 1 ; then echo -e "$@" fi } if test -z "$USER" then debug "$ERR USER environment variable is not set" > /dev/stderr disconnect fi #################################### ## Get user-trusted yubikeys list ## #################################### if [ ! -f $TRUSTED_KEYS_FILE ] then debug "$ERR Unable to find trusted keys list" > /dev/stderr disconnect fi TRUSTED_KEYS=`grep "${USER}:" $TRUSTED_KEYS_FILE | sed -e "s/${USER}://" | sed -e 's/:/\n/g'` for k in $TRUSTED_KEYS do debug "$OK Possible key '$k'" done ####################################### ## Get the actual OTP ## ####################################### echo -n "Please provide Yubi OTP: " read -s OTP echo KEY_ID=${OTP:0:12} ####################################### ## Iterate through trusted keys list ## ####################################### for trusted in ${TRUSTED_KEYS[@]} do if test "$KEY_ID" = "$trusted" then debug "$OK Found key in $TRUSTED_KEYS_FILE - validating OTP now ..." if wget "https://api.yubico.com/wsapi/verify?id=$YUBICO_API_ID&otp=$OTP" -O - 2> /dev/null | grep "status=OK" > /dev/null then debug "$OK OTP validated" if test -z "$SSH_ORIGINAL_COMMAND" then exec `grep "^$(whoami)" /etc/passwd | cut -d ":" -f 7` else exec "$SSH_ORIGINAL_COMMAND" fi debug "$ERR failed to execute shell / command" > /dev/stderr disconnect else debug "$ERR Unable to validate generated OTP" > /dev/stderr disconnect fi fi done debug "$ERR Key not trusted" > /dev/stderr disconnect
The avoid the need to cut+paste, here are links to the full script and the configuration file.
After restarting the SSHD service, all was working nicely. Authentication now requires a combination of a valid SSH public key and a valid YubiKey token. Alternatively, if SSH public keys are not in use for a user, authentication will require the login password and a valid YubiKey token.
I still feel a little dirty about having to use the ForceCommand hack though, because it means yubikey auth failures don’t appear in your audit logs – as far as SSHD is concerned everything was successful. It would nice to be able to figure out how to make OpenSSH properly combine SSH public key and PAM for authentication…