Yubikey

Whats is Yubikey

Yubikey

The YubiKey is a hardware authentication device manufactured by Yubico that supports one-time passwords, public key encryption and authentication, and the Universal 2nd Factor (U2F) protocol developed by the FIDO Alliance (FIDO U2F). It allows users to securely log into their accounts by emitting one-time passwords or using a FIDO-based public/private key pair generated by the device. YubiKey also allows for storing static passwords for use at sites that do not support one-time passwords. Facebook uses YubiKey for employee credentials, and Google supports it for both employees and users. Some password managers support YubiKey.

Yubikey features

Let's take a look at the options a YubiKey provides:

• Yubico One-Time Password (OTP) The YubiKey generates an encrypted password that can only be used once
• OATH – HOTP (EVENT)
• OATH – TOTP (TIME)
• Challenge and Response (HMAC-SHA1, Yubico OTP)
• PIV-Compatible Smart Card
• OpenPGP
• FIDO U2F
• Static passwords

Adding Yubikey PPA to your system

You can update your system with unsupported packages from this untrusted PPA by adding ppa:yubico/stable to your system's Software Sources.

sudo add-apt-repository ppa:yubico/stable
sudo apt-get update

If you want to remove this ppa:

sudo add-apt-repository --remove ppa:yubico/stable

How to use yubikey with Google

Requirements

• Latest version of Google Chrome browser (or at least version 38)
• A U2F Security Key, YubiKey 4, YubiKey 4 Nano, YubiKey 4C, YubiKey NEO, or other Yubico U2F-enabled YubiKey
• A Google Account (such as Gmail, Google Docs, YouTube, Google Plus, Blogger, Adwords)

Note: If your Google account is a managed account — such as with G Suite, Google Cloud, or Google for Education — your administrator must have enabled two-step verification before you can use your YubiKey. If the option to select 2-Step Verification is not available (as described in the steps below), ask your administrator to enable this security option.

Setting up your Google Account

1. Turn on 2-step verification. If you already have set up 2-Step Verification, continue with the next step.
2. Add a Security Key for 2-step verification. (We recommend that you add two YubiKeys, or Security Keys. They can be used interchangeably, or one can be your primary device, and one can be a backup device.
3. Be sure to save backup codes (you will use these if you are ever logging in without your YubiKey). To do this, scroll down after you have added your YubiKey(s) and, under Backup codes, click Show Codes. Click Download or Print, and save the codes in a safe location.

   • You can also set up Google Authenticator to generate verification codes if you don’t have your YubiKey. The Authenticator app can receive codes even if you are not connected to the internet.

Your YubiKey is now registered to your account as your default Two-Step Verification device! The screen now displays all devices that are registered to your account, so you can easily add another Security Key, or remove registered keys. (If you accidentally lose a YubiKey, come here and remove that YubiKey from your account. No one could log on to your account, though, because they would still need to know your username and password.)

Logging in to your Google Account

Logging in to your Google account with your YubiKey is refreshingly simple.

1. The next time you need to login to your Google account, insert your YubiKey.
2. Enter your user name and password, and click Sign in.
3. When the YubiKey begins to blink, tap it.

   • If you want to trust this computer for a short period of time, so you do not have to insert your YubiKey each time you log in, check the box to Remember this computer for 30 days.
   • If you do not have your YubiKey with you, click Use a verification code instead.

Local Authentication Using Challenge Response(sudo)

The PAM module can utilize the HMAC-SHA1 Challenge-Response mode found in YubiKeys starting with version 2.2 for offline authentication. This mode is useful if you don’t have a stable network connection to the YubiCloud.

The ykpamcfg utility currently outputs the state information to a file in the current user’s home directory ($HOME/.yubico/challenge-123456 for a YubiKey with serial number API readout enabled, and $HOME/.yubico/challenge for one without).

The PAM module supports a system wide directory for these state files (in case the user’s home directories are encrypted), but in a system wide directory, the challenge part should be replaced with the username. Example: /var/yubico/alice-123456.

To use the system-wide mode, you currently have to move the generated state files manually and configure the PAM module accordingly.

The following process is tested on Ubuntu 12.04.

First install the package:

sudo apt-get install libpam-yubico

You will get a question about the PAM configuration line. Enter this line:

mode=challenge-response

The next question will be about which PAM modules to enable. Don’t enable anything just yet, because you need to program your YubiKey first.

If you have already installed the package or want to reconfigure it, you may use this command:

sudo dpkg-reconfigure libpam-yubico

The next step is to add a challenge-response slot to your YubiKey. If you have a normal YubiKey with OTP functionality on the first slot, you could add Challenge-Response on the second slot. You could have CR on the first slot, if you want.

First, program a YubiKey for challenge response on Slot 2:

ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible
...
Commit? (y/n) [n]: y
$

Now, set the current user to require this YubiKey for logon:

mkdir $HOME/.yubico
ykpamcfg -2 -v
...

Stored initial challenge and expected response in '/home/alice/.yubico/challenge-123456'.

$

From security perspective, it is generally a good idea to move the challenge file in a system-wide path that is only read- and writable by root. To do this do as follow:

sudo mkdir /var/yubico
sudo chown root.root /var/yubico
sudo chmod 700 /var/yubico
ykpamcfg -2 -v
...

Stored initial challenge and expected response in '$HOME/.yubico/challenge-123456'.

sudo mv ~/.yubico/challenge-123456 /var/yubico/alice-123456
sudo chown root.root /var/yubico/alice-123456
sudo chmod 600 /var/yubico/alice-123456

It is important that the file is named with the name of the user that is going to be authenticated by this YubiKey.

Finally we tell the pam module where to look for the challenge file

emacs /etc/pam.d/common-auth

and edit the following line as follow:

auth   required        pam_yubico.so mode=challenge-response chalresp_path=/var/yubico

Then back to the PAM configuration step, first make sure you have a root terminal available to be able to disable YubiKey login in case of issues.

sudo -s

Then run the "pam-auth-update" command and enable the Yubico PAM module.

sudo pam-auth-update

You should now be able to authenticate using YubiKey Challenge-Reseponse together with a password like this:

jas@latte:~$ sudo -s
[sudo] password for jas:
root@latte:~#

Now remove the YubiKey and try again (in a new terminal to avoid sudo caching), and you should not be able to login.

Two-factor authentication with SSH

Prerequisites

Install 'yubico-pam'.

apt-get install libpam-yubico

Authorization Mapping Files

A mapping must be made between the YubiKey token ID and the user ID it is attached to. There are two ways to do this, either centrally in one file, or individually, where users can create the mapping in their home directories. If the central authorization mapping file is being used, user home directory mappings will not be used and vice versa.

Central authorization mapping

Create a file /etc/yubico/authorized_yubikeys, the file must contain a user name and the Yubikey token ID separated by colons (same format as the passwd file) for each user you want to allow onto the system using a Yubikey.

The mappings should look like this, one per line:

<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...

You can specify multiple key tokens to correspond to one user, but only one is required.

Per-user authorization mapping

Each user creates a ~/.yubico/authorized_yubikeys file inside of their home directory and places the mapping in that file, the file must have only one line:

<user name>:<Yubikey token ID1>:<Yubikey token ID2>

This is much the same concept as the SSH authorized_keys file.

Note that this file must be readable by the pam_yubico module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.

Obtaining the Yubikey token ID (a.k.a. public ID)

You can obtain the Yubikey token ID in several ways. One is by removing the last 32 characters of any OTP (One Time Password) generated with your Yubikey. Another is by using the modhex calculator.

Enter your Yubikey OTP and convert it, your Yubikey token ID is 12 characters and listed as:

Modhex encoded: XXXXXXX

PAM configuration

Having set up the pam_yubico module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.

The default way

Obtain HMAC credentials from Yubico as described in #YubiCloud and validation servers. You will receive a Client ID and a secret key.

Add one of the two following lines to the beginnning of /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys

if you're using a central authorization mapping file, or

auth            required      pam_yubico.so id=CLIENTID

if you're using per-user authorization mapping, where CLIENTID} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.

Using pure HMAC to authenticate the validation server

Add key to the above lines in /etc/pam.d/sshd:

auth            required      pam_yubico.so id=CLIENTID key=SECRETKEY ...

where CLIENTID and SECRETKEY are your HMAC ID and key.

You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:

# chmod o-r /etc/pam.d/sshd

HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own

SSHD configuration

You should check that /etc/ssh/sshd_config contains these lines and that they are not commented. The sshd_config shipped with 'openssh' has these set correctly by default.

ChallengeResponseAuthentication no
UsePAM yes

That is it!

You should not need to restart anything if you did not change the SSHD config file.

To log in, at the Password: prompt of SSH, you have to type your password without pressing enter and touch the Yubikey's button. The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.

You can display information about the login data generated by pam_yubico by adding the debug option to the auth line in/etc/pam.d/sshd. However, if you're using a central authorization file, you should remove that option once finished testing, as it causes pam_yubico to display the entire content of the central file to every user who logs in using a Yubikey.

Yubikey as hardware token for GPG

Introduction

GPG is most often used to encrypt and sign e-mails within software developer communities and cyberpunk circles. You also find that GPG is used to verify packages when you install software on your Ubuntu or Fedora box. GPG keyring can also be used for authenticating SSH connections.

Yubikey 4 Nano is one of the tiniest OpenPGP compatible hardware tokens on the market. With hardware token the your RSA private keys used by the GPG are not readable in the filesystem as it would usually be under ~/.gnupg directory.

Using GPG to send encrypted/signed e-mail can be done via variety of applications each one coming with a different support level for hardware tokens such as Yubikey:

Encrypting on command line as shown below works perfectly with Yubikey, but is cumbersome to use for newbies. Evolution has full GPG support built-in on Fedora, supports hardware tokens such as Yubikey for signing and encrypting. Retrieving correspondent's keys and setting trust level still has to be performed on command-line as shown below. Enigmail is a GPG plugin for Mozilla Thunderbird, supports hardware tokens, good user interface integration - untrusted senders key can easily be signed. Mailvelope generates keys internally and currently can't make use of hardware token PIV and PGP modes can't be used simultaneously

scdaemon which is used by GPG as backend to access smartcards exclusively locks the card even if configured to use PCSC-Lite as backend. Firefox similarily wants to have exclusive access to the token when there are valid certificates present in the PIV applet. This means that currently PGP and PIV modes can't be used simultaneously.

GPG has most often two versions installed: gpg and gpg2

Following guide focuses on gpg2 only. When gpg command happens to be executed accidentally at wrong time gpg-agent could be started with flags incompatible with gpg2, in that case kill gpg-agent process.

Setting up Yubikey

Install GPG v2.x if it hasn't been installed yet:

apt install gnupg2

First check whether GPG detects your token:

gpg2 --card-status

If you have Estonian ID-card reader hooked up to the computer you might have conflicts with web browsers, so it's a good idea to tell GPG reader name:

cat << \EOF >> ~/.gnupg/scdaemon.conf
reader-port "Yubico Yubikey 4 CCID"
EOF

Set up Yubikey, this is roughly equivalent to gpg2 --full-gen-key:

gpg2 --card-edit
admin
generate

Add identities, eg. when you use multiple e-mail addresses or aliases and set the trust level to ultimate for all of your identities:

gpg2 --edit-key first.last@example.com
adduid
trust

Export your public keys and upload it to a HTTP(S) accessible URL:

gpg2  --export --armor > filename.asc

Adding trusted people

As the root of trust is your own key, everything that is to be implicitly trusted has to be signed by yourself - hence to trust someone you first need to retreive their public key:

wget https://www.koodur.com/lauri.asc

Import it to your keyring located in your home directory (~/.gnupg/keyring.kbx):

gpg2 --import lauri.asc

Verify that the 40-character fingerprint of the imported key matches via other means eg. by giving a call via phone, meeting face to face or taking part of a keysigning party. Finally sign the public key identified by e-mail address:

gpg2 --sign-key <your email>

Alternatively keys can be fetched and imported from publicly operated keyservers, in that case 40-character key fingerprint and keyserver hostname is required. For example in order to import key used to sign CERT-EE (RIA) e-mails following commands should suffice. In this case pgp.mit.edu is keyserver operated by Massachusetts Institute of Technology:

gpg2 --keyserver pgp.mit.edu --recv <yourkey>
gpg2 --sign-key cert@cert.ee

Publishing your key

Use following to list your keys, your key fingerprint is the 40-character string just above your identities and e-mail addresses:

gpg2 --list-keys

Most commonly used keyservers can be found at Wikipedia. To prevent key collision attacks it might be good idea to upload your key to all of the listed servers there as it is very common that users specify only last 8 digits of the fingerprint to import keys.

gpg2 --keyserver pgp.mit.edu --send-key E1BC859AFC900AA925F1BAF33E1E3B1EE82AD8C0

Encrypting and decrypting arbitrary files

To encrypt a file you need to have recipient's public key in your keyring as shown above. To encrypt a file and output it in ASCII armored format:

gpg2 -r lauri@koodur.com -a -o encrypted.asc -e plain.txt

To dump decrypted document on command line:

gpg2 -d encrypted.asc

To save it into a file:

gpg2 -d encrypted.asc -o decrypted.txt

If you want to encrypt a directory, you will need to convert it to a file first. Run the command:

tar czf myfiles.tar.gz mydirectory/

This gives you a new file 'myfiles.tar.gz' which you can then encrypt/decrypt. To turn a tarball back into a directory:

tar xzf myfiles.tar.gz

Permanent configuration for GPG agent

It's very tricky to get this right. Following was tested on Fedora 25.

GPG agent wants to show PIN dialog on demand so it has to get graphical session environment variables right ($DISPLAY, $WAYLAND_DISPLAY etc).

Easiest way is to create autostart file:

cat << \EOF > ~/.config/autostart/gpg-agent.desktop
[Desktop Entry]
Type=Application
Name=gpg-agent
Comment=Autostart GPG agent
Exec=/usr/bin/gpg-connect-agent /bye
Terminal=false
EOF

Tell gpg-agent to export ssh-agent compatible socket:

cat << \EOF >> ~/.gnupg/gpg-agent.conf
enable-ssh-support
default-cache-ttl 90
ignore-cache-for-signing
EOF

Override environment variables when terminal is opened:

cat << \EOF >> ~/.bashrc
unset SSH_AGENT_PID
export SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"
EOF

Kill all the relevant processes, log out and log in again. When attempting to ssh to a remote box PIN dialog should pop up.

Using same Yubikey on another computer

Import your public keyring, eg in my case:

gpg2 --keyserver pgp.mit.edu --recv-key E1BC859AFC900AA925F1BAF33E1E3B1EE82AD8C0

On the first computer export secrets, in Yubikey case this should export only stubs which tell GPG to look for the key on a hardware token:

gpg2 --export-secret-keys -a -o secrets

Copy the file to new machine:

scp secrets new-machine:

On the new machine:

gpg2 --import secrets

Yubikey and KeePass

Yubikey can be integrated with KeePass thanks to contributors of KeePass plugins.

1. StaticPassword

   Configure one of Yubikey slots to store static password. You can make the password as strong as 65 characters (64 characters with leading `!`). This password can then be used as master password for your KeePass database.

2. one-time passwords (OATH-HOTP)

   1. Download plugin from KeePass website: http://keepass.info/plugins.html#otpkeyprov
   2. Use 'yubikey-personalization-gui-git' to setup OATH-HOTP
   3. In advanced mode untick `OATH Token Identifier`
   4. In KeePass additional option will show up under `Key file / provider` called `One-Time Passwords (OATH HOTP)
   5. Copy secret, key length (6 or 8), and counter (in Yubikey personalization GUI this parameter is called `Moving Factor Seed`)
   6. You may need to setup `Look-ahead count` option to something greater than 0, please see thread for more information
   7. See video for more help

3. Challenge-Response (HMAC-SHA1)

   1. Get the plugin from AUR: 'keepass-plugin-keechallenge'
   2. In KeePass additional option will show up under `Key file / provider` called `Yubikey challenge-response`
   3. Plugin assumes slot 2 is used

Removing sertificates from yubikey

To reset the PIV applet on the YubiKey to completely remove the certificates and set the PIN to default

Use this procedure if you want to completely remove the certificates created when you installed the YubiKey PIV Manager to pair your YubiKey with your computer. If you want to keep your certificates, skip to the next procedure.

1. Open the YubiKey PIV Manager.
2. Click Manage device PINs.
3. Click Change PIN.
4. In the Current PIN field, enter a 6-8 character PIN that is not your PIN.
5. In the New PIN and Repeat new PIN fields, enter a 6-8 character matching PIN (for example, 12345678).
6. Click OK. An error appears with the message “PIN verification failed. 2 tries remaining.”
7. Repeat steps 3-6 to change your PIN until you see the Manage device PINs window.
8. If you previously provisioned your YubiKey, or if you chose to set a PUK and management key, then you will need to lock out the PUK. To do this:

   1. In the Manage Device PINs window, click Change PUK.
   2. Repeat steps 3-6 to change your PUK until you see the Manage device PINS window.

9. Click Reset device.
10. Click OK.

To delete the only the certificates created following the compute login instructions

Use this procedure if you want to remove only the certificates created for computer login.

1. Open the YubiKey PIV Manager.
2. Click Certificates.
3. On the Authentication tab, click Delete certificate.
4. On the Key Management tab, click Delete certificate.

Removing the yubikey piv manager application

To remove YubiKey PIV Manager, drag the application to the Trash.

Troubleshooting

Q: If I lose my YubiKey what should I do?

A: You should login to the sites where you used the YubiKey on and change the account settings to use your replacement YubiKey instead.

Q: What if I can’t login to the site to change my settings?

A: Use the service’s authentication recovery method.

Author

Mark Parfeniuk C11, Estonian IT College.

References

1.https://lauri.xn--vsandi-pxa.com/2017/03/yubikey-for-gpg.html Lauri's blog

2.https://wiki.archlinux.org/index.php/yubikey Yubikey wiki

3.https://www.yubico.com/support/knowledge-base/ Knowledge base for yubikey

4.https://developers.yubico.com/yubico-pam/Authentication_Using_Challenge-Response.html Local Authentication Using Challenge Response