#lang en

<<TableOfContents()>>
= Passwords =
== One time passwords Mobile ==
 * Download the app 'authenticator' from the [[https://apps.apple.com/us/app/yubico-authenticator/id1476679808| appstore]] or [[https://play.google.com/store/apps/details?id=com.yubico.yubioath| playstore]].
 * Insert your Yubikey in your phone.
 * Right top, tap the + sign
 * Add your OTP key

== One time passwords Desktop ==
 * Download the app 'authenticator' from the [[https://www.yubico.com/products/services-software/download/yubico-authenticator/| website]]
 * Insert your Yubikey in your computer.
 * Right top, tap the + sign.
 * Add your OTP key.

=== Debian cli ===
 * Make sure `yubikey-manager` is intalled (`apt-get install yubikey-manager`)
 * Insert your yubikey in your computer
 * In a terminal, run `ykman oath list` to list all present credentials
 * To generate a code, run `ykman oath code <credentialname> (in quotes if the name contains a space) and touch your key.

= Use SSH =
== Change codes ==
To use this, it's recommended that you put a PIN, a PUK and a management code on your Yubikey. To do this, start the GUI, or use the following commands:
{{{
ykman piv change-pin
ykman piv change-puk
ykman piv change-management-key
}}}

The default codes for a new Yubikey are:
 * PIN: 123456
 * PUK: 12345678
 * Management: 010203040506070801020304050607080102030405060708

For more info about PIN, PUK, and Management keys, [[https://developers.yubico.com/yubikey-piv-manager/PIN_and_Management_Key.html|follow this link]]

== Generate certificates ==
Now making the Yubikey understand SSH. Generate the private key, certificate and the public SSH-key.
 * Generate a private key (EC does not work at the moment)
{{{
Old: ykman piv generate-key -a RSA2048 9a pubkey.pem
New: ykman piv keys generate -a RSA2048 --touch-policy always 9a pubkey.pem
}}}
 * Generate a certificate
{{{
Old: ykman piv generate-certificate -d 1826 -s "SSH Key" 9a pubkey.pem
New: ykman piv certificates generate -d 1826 -s "SSH key" 9a pubkey.pem
}}}
 * Convert the certificate to a ssh key
{{{
ssh-keygen -D /usr/local/lib/opensc-pkcs11.so
}}}

== Configuration ==
==== Debian ====
Make sure yubikey-manager and opensc-pkcs11 is installed:
{{{
sudo apt-get install yubikey-manager opensc-pkcs11 
}}}

Add on top to your SSH config file ''~/.ssh/config'':
{{{
PKCS11Provider /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so
}}}

==== Archlinux ====
Add on top to your SSH config file ''~/.ssh/config'':
{{{
PKCS11Provider /usr/lib/opensc-pkcs11.so
}}}

==== Mac OS X ====
For MacOSX, there's more to do:
 * Make sure you run [[https://brew.sh/|brew]] or download the OpenSC install from [[https://github.com/OpenSC/OpenSC/wiki|OpenSC Github]].
 * Install opensc if you use brew: 
{{{
brew install opensc
}}}
 * Link the right library:
{{{
sudo ln `brew list opensc |grep lib/opensc-pkcs11.so` /usr/local/lib/opensc-pkcs11.so
}}}
 * And add on top to your SSH config file ''~/.ssh/config'':
{{{
PKCS11Provider /usr/local/lib/opensc-pkcs11.so
}}}

And that's enough to make ssh possible.

== SSH Agent ==
=== Debian / Ubuntu ===
1. Make sure ssh agent is running:
    * `env | grep -i agent` should return a `SSH_AUTH_SOCK`
2. Add pkcs11 file
    * `ssh-add -s /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so`
    * When prompted, enter your yubikey piv pin
3. ssh to a remote server and test if the agent is forwared. If not, check if you enabled agent forwarding in your [[https://wiki.sciuro.org/Howto/SSH#Config |ssh config]].
4. If something goes wrong, or you want to remove the key from your ssh agent, run `ssh-add -e /usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so`

= Passwordless login =
[[https://askubuntu.com/questions/1167691/passwordless-login-with-yubikey-5-nfc | Ubuntu]]

= U2F PAM / Sudo =
== Debian / Ubuntu ==
Source [[https://www.ha-obsession.net/2017/05/u2f-sudo-fedora-25.html?m=1 | High-Availability Obsession ]]
 1. Install necessary packages
    * `sudo apt-get install libpam-u2f pamu2fcfg`
 1. Get config line for the U2F PAM module
 Plug in your yubuikey, run this command and then touch your key
    * `pamu2fcfg -u $(whoami) -opam://$(hostname) -ipam://$(hostname)`
    * The output should look like `username:base64,hex`
 1. Installing the pam config
    * In a separate terminal, become root
    * Put the config line you created in /etc/u2f_mappings
    * If you have multiple keys, repeat step 2, and put the output after the first string, separated by a colon (:)
 1. Setup /etc/sudoers
    * If you want to require the user touching the yubikey for every sudo call (immediate timeout), do the following:
    * As root, run `visudo`
    * After `Defaults env_reset` put `,timestamp_timeout=0`
    * Save and exit editor
 1. Setup /etc/pam.d/sudo
    * Edit `/etc/pam.d/sudo`
    * Put the following line at the top of the file: (Below the shebang)
    * `auth [success=done new_authtok_reqd=done default=die] pam_u2f.so origin=pam://HOSTNAME appid=pam://HOSTNAME authfile=/etc/u2f_mappings cue`
    * Make sure to replace the two HOSTNAME intances with your hostname (run `hostname` to get this value)
    * Save and exit editor.

    * If you want to allow either the yubikey, '''OR''' the user password, use: `auth sufficient pam_u2f.so origin=pam://HOSTNAME appid=pam://HOSTNAME authfile=/etc/u2f_mappings cue`
    * If you want to require both the yubikey, '''AND''' the user password, use: `auth required pam_u2f.so origin=pam://HOSTNAME appid=pam://HOSTNAME authfile=/etc/u2f_mappings cue`

== BSD ==
Install the pam module:
{{{
pkg install pam_ssh_agent_auth
}}}

Add to the /usr/local/etc/pam.d/sudo:
{{{
auth		sufficient	pam_ssh_agent_auth.so file=~/.ssh/authorized_keys
}}}

Add a new file to the /usr/local/etc/sudoers.d/wheel or any where else:
{{{
Defaults env_keep += SSH_AUTH_SOCK

%wheel ALL=(ALL) ALL
Defaults:%wheel timestamp_timeout=0
}}}

= Disk Encryption =
== LUKS ==
[[https://infosec-handbook.eu/blog/yubikey-luks/ | Source]]

LUKS is the standard for Linux disk encryption, and can easily be installed while setting up a system using i.e. the Debian installer.
During LUKS setup, set a 'normal' passphrase, this can be used as a backup for when you lose your yubikey. Furthermore, the following installation has to be executed on the running system, so you'll need the passphrase to unlock the disk before continuing.
  ''The following method has been tested on Debian 4.19 with a yubikey NEO''

 1. Run `sudo fdisk -l | grep crypt` to see on which drive your LUKS container exists. If it returns something like `/dev/mapper/sda5_crypt`, the drive should be sda5.
 1. Run `sudo cryptsetup luksDump /dev/[partition]` to check which key slots are in use. Usualy only slot 0 will be in use.
 1. Install `yubikey-luks` by running `sudo apt-get install yubikey-luks`
 1. To setup your yubikey, run `ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible`. '''This WILL wipe any previous configuration from slot 2'''. [[https://github.com/agherzan/yubikey-full-disk-encryption#configure-hmac-sha1-challenge-response-slot-in-yubikey|More Info]]
 1. Optionally edit `/etc/ykluks.cfg`, the config for yubikey-luks
 1. Run `sudo yubikey-luks-enroll -d /dev/[partition] -s [free-key-slot]` add `-c` to wipe the slot beforehand. It will ask you for a new challenge-response password (this can be unique for every disk you set up), and an existing luks key (the one you used up to this point).
 1. Edit `/etc/crypttab`, this determains how your disk encryption is handled at boot.

 Add `,keyscript=/usr/share/yubikey-luks/ykluks-keyscript` to it after `luks` (or `discard` for Ubuntu). This causes the keyscript to be called to get the challenge-response from the yubikey.
 
 > '''Note:''' If /usr/ is located on the luks-encryped volume, cryptsetup won't be able to find it (because its encrypted) and fail. Copy `ykluks-keyscript` to `/boot/` or another location that will be readable at boot, and refer to this location in your crypttab.
 1. Run `update-initramfs -u`. The response should be something like `update-initramfs: Generating /boot/initrd.img-x.x.x-os-name-architecture`
 1. Reboot and test if everything works. If for some reason it doesn't work, just log in using your old passphrase.
 > '''Tip:''' sometimes it helps to replug the yubikey when cryptsetup is loaded.
= More information =
 * [[https://wiki.archlinux.org/index.php/YubiKey]] A lot of information about linux and yubikey.
 * [[https://archive.fosdem.org/2018/schedule/event/smartcards_in_linux/attachments/slides/2265/export/events/attachments/smartcards_in_linux/slides/2265/smart_cards_slides.pdf]] FosDem presentation
----
CategoryHardware