How to set up a YubiKey in Linux using call-response

YubiKey hardware security keys make your system more secure. And the procedure of logging into accounts is faster and more convenient. Follow the instructions below to easily add the required settings on your Linux system.

Setting up the YubiKey in Linux is quite different from setting up in other OSes, for example in Windows. First, you will need to perform operations through the terminal, not through the user interface. Secondly, you will need to make not one, but a number of settings so that hackers cannot bypass certain restrictions, while you do not block access to the system yourself. The following actions are meant:

• installing Yubico software;
• setting up and binding the YubiKey security key;
• setting up the system to use keys;
• elimination of possible malfunctions.

If you know English well, you can watch this video, it is about setting up using HMAC-SHA1 protocol. If you’re more comfortable with a text format, check out the text version of the instructions below.

If you plan to use Security Key or YubiKey Bio series keys, please refer to the instructions for configuring keys using the U2F function.

Compatible keys

Depending on how you want to configure your system (via HMAC-SHA1 or U2F) you will need to select compatible keys. Series 5 or FIPS keys are suitable for login without a password or two-factor authentication. But the Bio or Security Key series can only be used for U2F.

Ways to install Yubico software

There are several ways to install Yubico software on Linux:

• by installing the Yubico Authenticator;
• by installing YubiKey Manager;
• using built-in repositories;
• using Yubico’s PPA packages;
• by compiling from the source code.

More information in the article: “How to install Yubico software on Linux”.

Configuring the YubiKey security key

Consider setting up a YubiKey on an Ubuntu system using the HMAC-SHA1 challenge-response function. Based on this example, you will be able to make similar settings in systems similar to Ubuntu.

1. Open a terminal and run the command to install the software for Ubuntu: sudo apt install libpam-yubico yubikey-manager.
2. Insert the YubiKey.
3. Run the command: ykman otp chalresp -g 2.
4. Confirm the settings by pressing the key Y, then Enter.
5. To bind the key to the account, run the command: ykpamcfg -2. After that, you should receive confirmation from the system in the format: «Збережений початковий виклик», «/home/<USER>/.yubico/challenge-<SERIAL>». where in place <USER> will be your username, and instead <SERIAL> — the serial number of the YubiKey. If the file does not run, go to “Troubleshoot”.

In order not to lose access to your personal device in case you lose the key, we recommend adding a spare hardware device. To do this, you will need to repeat the same operations as when adding the first key. If you don’t have a spare key yet, you can come back to this step later.

To set up an additional level of security, you need to move the file challenge-<SERIAL> to an OS directory where you will need to get sudo permission to edit the file (eg /etc). To do this, follow these steps:

• Create a named directory yubico (sudo mkdir /etc/yubico).
• Move the call-response file to /etc/yubico, while instead of challenge-<SERIAL> should be written username-<SERIAL>. To move a file from ~/.yubico до /etc/yubico and rename the login user, run the command: sudo mv ~/.yubico/challenge-<SERIAL> /etc/yubico/`whoami`-<SERIAL>.

After the file challenge-<SERIAL> will be moved to a safe location, the PAM file will also need to be modified for it to work correctly. To do this, you will need to add to the configuration of the PAM file “chalresp_path=/etc/yubico” at the end.

Note thatafter performing these steps, you will not be able to modify the file if you lose the key. This can lead to blocking of access. So we don’t recommend doing this step without adding a backup security key.

Configuring the system to use security keys

In this section, we’ll look at how to configure keys using sudo commands without locking yourself out. We will also consider how to fix the system in case of errors.

The debug log

If you’re having trouble logging in, you can turn on the debugging system to find the cause. To do this, launch Terminal and specify: sudo touch /var/log/pam_yubico.log. Next, find the line pam_yubico.so and add at the end: “debug debug_file=/var/log/pam_yubico.log”.

After that, all the events will be saved in the debug log, and you can find the error and fix it. If you don’t need the debug log, you can disable it by removing the line “debug debug_file=/var/log/pam_yubico.log” from the files pam.

The sudo Command

Let’s wonder how to set up the system to vimagati the key when using the sudo command (this command helps to take away the privileges of the super-coordinator) and not to block yourself.

1. Open the terminal and open the tax log.
2. Create a PAM configuration file, in which case it is set to:

#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, thenEnterTo save the file, but don’t close the terminal yet, otherwise you won’t be able to change anything else. You can have a look at:

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 the YubiKey from the computer.
2. Start a new terminal and enter the command: sudo echo test.
3. If any program asks you for a password. Enter it and press Enter.
1. If the key is not inserted, authentication may fail. Well, it went well, otherwise look for pardons in the file changes /etc/pam .d/sudo, otherwise, check that you have correctly installed the Yubico PAM module.
4. Insert the security key and open the new terminal.
5. Re-enter sudo echo test, then, if the program needs a password, enter the password and type Enter.
1. If the authorization with the updated key was successful, it means that you correctly set the key for the system. There is a need to close the system to fix the system for supplying the selected key at the entrance.

Configuring the system for a remote key when entering the system

1. Open the terminal and enter the command: sudo nano /etc/pam.d/gdm-password. You should receive an answer:

#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. After that, press Ctrl+X, then Enter, to save the settings.

System settings on demand when using the terminal

In the same way, you can configure the terminal, only by entering a slightly different command: sudo nano /etc/pam.d/login.

Elimination of possible malfunctions

Sometimes, even during the launch of the file ykpamcfg -2, you can see an error as if the file already exists. This can happen if one of the YubiKeys was previously bound to the system. To clear the association with the old hardware and add the new key, run the command in the terminal: rm ~/.yubico/challenge-<SERIAL>. Only instead of <SERIAL> enter the serial number of the new key.

This completes our instruction. If you have not yet chosen a key, or are looking for a spare hardware device, we invite you to view the offers in our online store. If you have any questions about key compatibility, please contact our managers.

Similar materials in the Knowledge Base