Skip to content

Using your YubiKey

Notes on installing and setting up your YubiKey for various platforms and applications.

Introduction

The YubiKey is a hardware device manufactured by Yubico that provides a hardware, phishing resistant "second factor" enabling true multi-factor authentication: something you know (your password) and something you have (your YubiKey). It enables you to easily and securely log in to accounts by emitting one-time passwords or using a FIDO-based public/private key pair generated by the device.

Operation

  • Simply plug it into an unused USB port.
  • During certain types of authentication you will be prompted on screen to press the inset copper button marked with and (often lit) "Y".

Security Hints

  • If you trust your environment (like at home) you can keep the YubiKey near or even plugged into your computer.
  • In low trust environments (coffee shops, hotel rooms, etc.) keep your YubiKey with you at all times (in a pocket or purse), especially if step away from your computer, even briefly. If your computer is compromised, it won't be accessible without the YubiKey that you have on you.
  • Do not use SMS text messages for multi-factor authentication. Your MFA is only as strong as the weakest method you have configured.

Enable YubiKey MFA for applications

See "Let's get your YubiKey to work" (from Yubico) on how to use MFA with: Gmail, LastPass, GitHub and many other services.

See also: How to Secure Your Google, Dropbox, and GitHub Accounts With a Yubikey

LastPass

This requires a YubiKey token (cover the button for approximately one second) on laptop/desktop to unlock LastPass.

  • My Vault -> Account Settings -> Multifactor Options
  • Set up one free option (e.g., Google Authenticator or LastPass Authenticator) - this is a useful backup
  • YubiKey (an easier option) is available when using LastPass Premium ($12/year)
    • Select the YubiKey option.
    • Insert the YubiKey device into a USB port on your computer.
    • Focus your cursor on the "YubiKey #1" field.
    • Press the button on the YubiKey device.
    • A long string of dots should appear in the YubiKey #1 field.
    • Change the "YubiKey Authentication" status to "Enabled"
    • Set "Enabled" ==> "Yes"
    • Set "Permit Offline Access" ==> "Disallow"
    • Press the Update button
    • Enter your LastPass master password and press Confirm.
    • YubiKey is now enabled for your LastPass account.
  • If your phone supports NFC, you can touch the more recent Yubikeys against your phone to unlock on mobile.

Google

For each Google account you have:

  • Visit https://accounts.google.com/b/0/SmsAuthSettings#devices
  • Enable TFA, and complete the phone verification process (phone will act as backup TFA).
  • Click on "Security Keys" and follow instructions to add YubiKey.
  • Return to the main page and add a second phone and/or print backup codes.
  • As long as you have a backup, you can also install the YubiKey Authenticator app, and configure your account to use that for the backup TFA instead of SMS/phone - this is the same as the Google Authenticator app, except that it stores the credentials on your YubiKey instead of the phone.
  • If you have funky devices/apps that don't support TFA, you can set an application specific password using that tab. This includes sending E-mail from your personal Gmail account using your civicactions.com IMAP, for instance.

GitHub

AWS Root Account

For each AWS account you have:

AWS IAM Account

Up to 8 different MFA devices can be assigned, with a combination of Yubikeys, hardware TOTP tokens and authenticator apps.

  • Visit https://console.aws.amazon.com/iam/home?region=us-east-1#users
  • Choose your user name
  • Select the "Security Credentials" tab
  • Under Multi-factor Authentication(MFA), select "Assign MFA device"
  • Enter a Device Name and Select "Security Key"
  • Allow your browser access to your Yubikey, if prompted
  • Enter your Yubikey's pin, if prompted
  • Touch your Yubikey when instructed

Linux

Locking your Machine with YubiKey

This will require the YubiKey (Two Factor Authentication) to be inserted to authenticate via PAM (login, sudo or screen unlock). Test this carefully in an alternate console session to ensure you don't lock yourself out! (If you do get locked out, you'll have to boot with a live CD and undo the changes in /etc/pam.d/. As this requires a reboot, your encrypted disk will require its passphrase again, which is the key to security here.)

This is required of CivicActions "privileged users" such as System Administrators, and it is our intention that it be standard practice for all CivicActions employees and contractors.

Installing the Yubico libpam module

In order to connect your YubiKey to the screen locking software on your computer, you need to:

Arch yubico-pam setup
pacaur -S yubico-pam
Fedora Yubico libpam module
Ubuntu/Xubuntu Yubico libpam module
sudo apt-get install libpam-yubico
Set up PAM MFA on Linux

PAM is the Pluggable Authentication Module used by GNU/Linux and Mac OS X to manage login authentication.

See Yubico GitHub page for complete documentation.

ykpamcfg -2 -v

Ubuntu autoconfiguration during installation of libpam-yubico may already have placed a line like the following in either /etc/pam.d/common-auth or /etc/pam.d/system-auth. If not using Ubuntu (or the line is not there), edit /etc/pam.d/system-auth (will need to sudo) and add the following line at the top of the file:

auth      required  pam_yubico.so   mode=challenge-response
Linux YubiKey removal lock

For additional security, you may want to immediately lock the screen when the YubiKey is removed.

This locks the laptop immediately when any YubiKey is removed. If you are not using xautolock as your "away detector", replace xautolock with a command to trigger your screen lock with the "away detector" that you do use. This is inspired by https://vtluug.org/wiki/Yubikey#Automatic_Screen_Locking_.28i3lock.2C_slock.2C_etc..29

As your login user, create executable file ~/bin/ykgone:

#!/bin/bash
USER=$(stat -c "%U" "$0")
if usb-devices | fgrep Vendor=1050; then
  echo "YubiKey present"
else
  echo "YubiKey not present, locking"
  export DISPLAY=":0"
  export XAUTHORITY=/home/$USER/.Xauthority
  su $USER -c "xautolock -locknow" &
fi

Next, create (with sudo) a device notification file /etc/udev/rules.d/90-yubikey.rules:

ACTION=="remove", ATTRS{idVendor}=="1050", RUN+="/home/$USER/bin/ykgone"

Personalize your YubiKey on Linux

This allows you to use your YubiKey with Google MFA (new fangled U2F), as well as LastPass (which uses the OTP application).

neoman
# Enable OTP, U2F, CCID checkboxes if needed, follow instructions to add and remove key

ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible

Mac OS X

This is the Mac OS X specific documentation for YubiKey.

Please help make this page more useful by adding links you found useful (describe exactly how they are useful) and specific steps you used to install, configure, and test your YubiKey.

Mac OSX YubiKey tool

This should be straightforward, but waiting for a pull request that clearly explains how to:

  • Enable OTP, U2F & CCID
  • Personalize Configuration Slot 2 with options:
    • chal-resp (Set challenge-response mode)
    • chal-hmac (Generate HMAC-SHA1 challenge responses)
    • hmac-lt64 (Calculate HMAC on less than 64 bytes input)
    • serial-api-visible (Allow serial number to be read using an API call)

Install apps

See:

tbd...

Set up PAM MFA on MacOS

tbd...

Screen lock on lid close or idle

tbd...

Away detection ideas

Exceptions to the "idle timeout lock" can be made if you are on your home network and feel that it is secure. Adapt the below script if you only want to lock your screen when you are away from home.

Assuming ~/bin/ is in your $PATH, and you want to see if a file is on a Windows server, create executable file ~/bin/out-lock:

#!/bin/sh
MOUNT="$HOME/mountain"
# Checks if server is mounted
if [ ! -d "$MOUNT" ]
then
  SERVER_IP="192.168.1.1"
  SHARE_NAME="share"
  USERNAME="admin"
  PASSWORD="password"
  FILE="home.txt"
  mount_smbfs //$USERNAME:$PASSWORD@$SERVER_IP/$SHARE_NAME $MOUNT
fi
contents=$(cat $MOUNT/$FILE)
hash=`echo -n $contents | shasum -a 256`
cuthash=`echo $hash | cut -c1-64`
if [ "$cuthash" != "7147a8f255f49cb7693dcd19b6b46e139680d48a03e0a075ea237deb7e6bacc9" ]
then
  # Lock Screen
  /System/Library/CoreServices/Menu\ Extras/User.menu/Contents/Resources/CGSession -suspend
fi

The "cron" or launchctl file located at $HOME/Library/LaunchAgents/com.dan.outlock.plist might look like this to run every 15 minutes:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.dan.outlock</string>

  <key>ProgramArguments</key>
  <array>
    <string>/bin/out-lock</string>
  </array>

  <key>Nice</key>
  <integer>1</integer>

  <key>StartInterval</key>
  <integer>900</integer>

  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

MacOS YubiKey removal lock

tbd...

Last update February 1, 2025.