Ubuntu Linux 20+ login guide (challenge response)

This article covers how to secure a local Linux login using the HMAC-SHA1 challenge-response feature on YubiKeys. This does not work with remote logins via SSH or other methods. The commands in this article are specific to Ubuntu (or Ubuntu based - such as Linux Mint) system, but the instructions can be adapted for any distribution of Linux. For RHEL, refer to RHEL login guide (challenge response).

 Tip: If you have a Security Key Series or YubiKey Bio Series, challenge-response is not supported, so refer to the following article instead: Ubuntu Linux login guide (U2F).

1 Installing the required software

1. Open Terminal
2. Run the following command:
   

   sudo apt install libpam-yubico yubikey-manager
   

2 Configuring the YubiKey

 Tip: This section can be skipped if you already have a challenge-response credential stored in slot 2 on your YubiKey, such as one made for Yubico Login for Windows.

1. Open Terminal
2. Insert your YubiKey
3. Run the following command:
   

   ykman otp chalresp -g 2
   

4. Press Y and then Enter to confirm the configuration

Repeat these steps for any additional YubiKeys you want associated with your account. 

 Tip: Setting up additional YubiKeys is strongly recommended so that if your YubiKey is lost or broken you are not locked out of your computer.

3 Associating the YubiKey(s) with your user account

1. Open Terminal
2. Insert your YubiKey
3. Run the following command:
   

   ykpamcfg -2
   

If successful, you will see an output such as Stored initial challenge and expected response in '/home/<USER>/.yubico/challenge-<SERIAL>' where <USER> is your username and <SERIAL> is the serial number printed on the YubiKey. 

If you have backup YubiKeys, repeat the steps above to associate them with your account. If you do not have a backup device available at this time, you can add one later using the same steps as long as you still have access to your account. 

 Tip: Having a backup YubiKey is strongly recommended so that if your device is lost or broken, you will not be locked out of your computer.

If you would like to add an additional layer of security, you can change the output of the challenge-<SERIAL> file to an area of the OS where you'll need sudo permission to edit the file ( e.g. /etc ). After creating a directory named yubico ( sudo mkdir  /etc/yubico ). when moving the challenge-response file to /etc/yubico the filename will need to be changed to username-<SERIAL> instead of challenge-<SERIAL>. You can move the file from ~/.yubico to /etc/yubico and rename to the login username by running the command (sudo mv ~/.yubico/challenge-<SERIAL> /etc/yubico/`whoami`-<SERIAL>).

Once the challenge-<SERIAL> file is moved to a safer location, the PAM file will need to also be modified for this to function correctly. You will need to append the PAM file's configuration to have chalresp_path=/etc/yubico added to the end. 

 Warning: Once you modify the /etc/pam.d/sudo file to require the YubiKey, if you lose or misplace the YubiKey, you will not be able to modify or change the file to remove the YubiKey requirement.

4 Configuring the system to use the YubiKey(s)

4.1 Test Configuration with the sudo command

This section covers how to require the YubiKey when using the sudo command, which should be done as a test so that you do not lock yourself out of your computer.

1. Open Terminal
2. Enable debug logging during initial setup 
3. Create PAM config files

#this will require password + YubiKey for Login

sudo nano /etc/pam.d/yubico-required

 auth required pam_yubico.so mode=challenge-response debug debug_file=/var/log/pam_yubico.log

#This will only require YubiKey for Login

sudo nano /etc/pam.d/yubico-sufficient

 auth sufficient pam_yubico.so mode=challenge-response debug debug_file=/var/log/pam_yubico.log

1. Press Ctrl+X and then Enter to save the file. Be sure you do not close the Terminal window, otherwise you will not be able to revert the changes.

sudo nano /etc/pam.d/sudo 

#for password + YubiKey

Add the line below the “@include common-auth” line. 

@include yubico-required

#for YubiKey only 

Add the line above the “@include common-auth” line. 

@include yubico-sufficient

1. Remove your YubiKey from the computer
2. Open a new Terminal window
3. In the new Terminal window, run the following command:
   

   sudo echo test
   

   When prompted, enter your password and press Enter. 
• Even with the correct password, the authentication should fail as the YubiKey is not plugged in. If the authentication succeeds without the YubiKey, that indicates the Yubico PAM module was not installed or there is a typo in the changes you made to /etc/pam.d/sudo. 
4. Insert your YubiKey
5. Open a new Terminal window and run the following command again:
   

   sudo echo test
   

   When prompted, enter your password and press Enter

If the password was accepted this time, you have configured the YubiKey and system correctly and can continue on to the next section for requiring the YubiKey to login.

 Tip: If you do not want to require the YubiKey to run the sudo command, remove the line you added to the /etc/pam.d/sudo file.

4.2 Configuring the system to require the YubiKey for login

1. Open Terminal
2. Run the following command:
   

   sudo nano /etc/pam.d/gdm-password
   

#for Password + YubiKey

Add the line below the “@include common-auth” line. 

@include yubico-required

#for YubiKey only 

Add the line above the “@include common-auth” line. 

@include yubico-sufficient

Press Ctrl+X and then Enter to save and close the file.

4.3 Configuring the system to require the YubiKey for TTY terminal

1. Open Terminal
2. Run the following command:
   

   sudo nano /etc/pam.d/login
   

#for Password + YubiKey

Add the line below the “@include common-auth” line. 

@include yubico-required

#for YubiKey only 

Add the line above the “@include common-auth” line. 

@include yubico-sufficient

Press Ctrl+X and then Enter to save and close the file.

You will no longer be able to log in to the computer without the YubiKey.

5 Troubleshooting

5.1 Running ykpamcfg -2 fails

If you see the “file … already exists, refusing to overwrite” error when running ykpamcfg -2, this indicates you have already associated this YubiKey with your account. If you want to clear the existing association to start again, you can run the command below in Terminal, where <SERIAL> is the serial of the YubiKey.

rm ~/.yubico/challenge-<SERIAL>

5.2 Enabling debug mode

If you are unable to login and are unsure why, you can enable debugging on the Yubico PAM module using the steps below. This provides insight into why the module is not allowing the login.

1. Open Terminal
2. Run the following command:
   

   sudo touch /var/log/pam_yubico.log
   

3. Add debug debug_file=/var/log/pam_yubico.log to the end of the line that contains pam_yubico.so

Each subsequent login event will have the debug log saved in the /var/log/pam_yubico.log file.

5.3 Disabling debug mode

To disable logging, remove the line debug debug_file=/var/log/pam_yubico.log from the yubico-required or yubico-sufficient PAM files