1. Yubico
  2. Business
  3. Guides

Red Hat Linux Family Login Guide - Challenge Response

Avatar
Clay Degruchy
Created - Updated

1 Introduction

This guide 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 the guide are for a Red Hat Enterprise Linux (or RHEL based - such as CentOS or Fedora) system, but the instructions can be adapted for any distribution of Linux.

2 Installing the Required Software

  1. Download the packages pam_yubico, ykclient, and ykpers from the EPEL repository to your home folder.
  2. Open Terminal.
  3. Run: sudo rpm -i ykclient*.rpm ykpers*.rpm pam_yubico*.rpm
    • Note that you may also need to install the libyubikey package, depending on which distribution you are using.

3 Configuring the YubiKey

Note: This section can be skipped if you already have a challenge-response credential stored in slot 2 on your YubiKey. You will have done this if you used the Windows Logon Tool or Mac Logon Tool. 

  1. Open Terminal.
  2. Insert your YubiKey.
  3. Run: ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible
  4. Press Y and then Enter to confirm the configuration.

Repeat these steps for any additional YubiKeys you want associated with your account. Note: Setting up additional YubiKeys is strongly recommended so that if your YubiKey is lost or broken you are not locked out of your computer. 

4 Associating the YubiKey(s) With Your Account

  1. Open Terminal.
  2. Insert your YubiKey.
  3. Run: ykpamcfg -2
  4. If your key's Challenge-Response credential was configured to require touch, your YubiKey will begin flashing, indicating that you should touch its sensor.

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. Warning: 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.

5 Configuring the System to Use the YubiKeys

5.1 Test Configuration with the Sudo Command

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

  1. Open Terminal.
  2. Run: sudo nano /etc/pam.d/sudo
  3. Add the following line above the “auth include system-auth” line.

auth       required   pam_yubico.so mode=challenge-response

  1. Press Ctrl+O 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.
  2. Remove your YubiKey from the computer.
  3. Open a new Terminal. 
  4. In the new Terminal, run: sudo echo test. When prompted, enter your password and press Enter. 
    1. 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. 
  5. Insert your YubiKey.
  6. Open a new Terminal and run sudo echo test again. When prompted, enter your password and press Enter. If your key's Challenge-Response credential was configured to require touch, your YubiKey will begin flashing, indicating that you should touch its sensor.

Congrats! 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. Note: 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.

5.2 Configuring the System to Require the YubiKey for Login

  1. Open Terminal.
  2. Run: sudo nano /etc/pam.d/gdm-password
  3. Add the following line above the “auth substack password-auth” line.

auth       required   pam_yubico.so mode=challenge-response

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

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

6 Alternate Configurations

6.1 Login with YubiKey Only (1FA)

If you would prefer to not require a password for login or running sudo, you can use auth sufficient instead of auth required in the configuration files.

7 Troubleshooting

7.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>

7.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: sudo touch /var/log/pam_yubico.log
  3. Run: sudo nano /etc/pam.d/gdm-password
  4. Add “ debug debug_file=/var/log/pam_yubico.log” (without quotes) 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.