User:Mparfeni

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

Two-factor authentication with SSH

Prerequisites

Install 'yubico-pam'.

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

Using pure HTTPS to authenticate the validation server

Hoiatus: While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.

If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting CLIENTID=1 instead of your own ID. Although pam_yubico's default server uses HTTPS already, for security reasons you should specify it manually via the urllist parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the debug parameter to the auth line.

SSHD configuration

You should check that /etc/ssh/sshd_config contains these lines and that they are not commented. The sshd_config shipped with Template:Pkg 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