From aaf1342b59b588089dc3258edd2e1dc4b534d909 Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Sun, 11 Feb 2018 21:02:38 +0000 Subject: [PATCH 1/3] document https://github.com/QubesOS/qubes-app-yubikey --- security/yubi-key.md | 92 +++++++++++++++++++++++++++----------------- 1 file changed, 57 insertions(+), 35 deletions(-) diff --git a/security/yubi-key.md b/security/yubi-key.md index 3dee80cc..1df57b4f 100644 --- a/security/yubi-key.md +++ b/security/yubi-key.md @@ -40,52 +40,67 @@ password (other than your login password!) and apply the configuration. To use this mode you need to: -1. Configure your YubiKey for challenge-response HMAC-SHA1 mode, for example +1. Install yubikey personalization the packages in your TemplateVM on which your USB VM is based. + + For Fedora. + + sudo dnf install ykpers yubikey-personalization-gui + + For Debian. + + sudo apt-get install yubikey-personalization yubikey-personalization-gui + + Shut down your TempalteVM. Then reboot your USB VM (so changes inside the TemplateVM take effect + in your TemplateBased USB VM or install the packages inside your USB VM if you would like to avoid + rebooting your USB VM. + +2. Configure your YubiKey for challenge-reponse `HMAC-SHA1` mode, for example [following this - tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/) -2. Install the `ykpers` package in template on which your USB VM is based. -3. Create `/usr/local/bin/yubikey-auth` script in dom0: + tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/). - #!/bin/sh + On Debian, you can run the graphical user interface `yubikey-personalization-gui` from the command line. - key="$1" + - Choose `configuration slot 2`. + - It is recommended to enable `Require user input (button press)` but this is optional. + - Note: Derivating from the above video, use the following settings select + `HMAC-SHA1 mode`: `fixed 64 bit input`. + - We will refer the `Secret Key (20 bytes hex)` as `AESKEY`. + - It is recommended to keep a backup of your `AESKEY` in an offline VM used as vault. + - Consider to keep a backup of your `AESKEY` on paper and store it in a safe place. + - In case you have multiple yubikeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other yubikeys. - if [ -z "$key" ]; then - echo "Usage: $0 []" - exit 1 - fi +3. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in dom0. - # if password has given, verify it - if [ -n "$2" ]; then - # PAM appends \0 at the end - hash=`head -c -1 | openssl dgst -sha1 -r | cut -f1 -d ' '` - if [ "x$2" != "x$hash" ]; then - exit 1 - fi - fi + sudo qubes-dom0-update qubes-yubikey-dom0 - challenge=`head -c64 /dev/urandom | xxd -c 64 -ps` - # You may need to adjust slot number and USB VM name here - response=`qvm-run -u root --nogui -p sys-usb "ykchalresp -2 -x $challenge"` +4. Adjust USB VM name in case you are using something other than the default + `sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0. - correct_response=`echo $challenge | xxd -r -ps | openssl dgst -sha1 -macopt hexkey:$key -mac HMAC -r | cut -f1 -d ' '` +5. Paste your `AESKEY` from step 2 into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. - test "x$correct_response" = "x$response" - exit $? +6. Paste your hashed password (other than your standard Qubes password) into +`/etc/qubes/yk-keys/yk-login-pass-hashed.hex` in dom0. -4. Adjust USB VM name (`sys-usb` above), and possibly YubiKey slot number (`2` - above), then make the script executable. -5. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using other - screen locker program). Add this line at the beginning: - - auth [success=done default=ignore] pam_exec.so expose_authtok quiet /usr/local/bin/yubikey-auth AESKEY PASSWORD-HASH - - Replace `AESKEY` with hex-encoded key configured in the first step, then - replace `PASSWORD-HASH` with SHA1 hash for your YubiKey-linked password (other - than your standard Qubes password). You can calculate it using this command: + You can calculate your hashed password using this command: echo -n "PASSWORD" | openssl dgst -sha1 + (Replace `PASSWORD` with your actual password.) + +7. Edit `/etc/pam.d/login` in dom0. Add this line at the beginning: + + auth include yubikey + +8. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using other + screen locker program) in dom0. Add this line at the beginning: + + auth include yubikey + +9. Edit `/etc/pam.d/lightdm` (or appropriate file if you are using other + display manager) in dom0. Add this line at the beginning: + + auth include yubikey + ### Usage When you want to unlock your screen... @@ -100,6 +115,13 @@ When everything is ok, your screen will be unlocked. In any case you can still use your login password, but do it in a secure location where no one can snoop your password. +### Mandatory YubiKey Login + +Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen locker program) +and remove `default=ignore` so the line looks like this. + + auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth + Locking the screen when YubiKey is removed ------------------------------------------ @@ -137,7 +159,7 @@ persist across VM restarts. For example name the file 5. Then make `/rw/config/rc.local` executable. sudo chmod +x /rw/config/rc.local - + 6. For changes to take effect, you need to call this script manually for the first time. sudo /rw/config/rc.local From 582125ababbbbc451b26ef5d6625fca898b31788 Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Fri, 23 Feb 2018 13:58:16 +0100 Subject: [PATCH 2/3] avoid password in shell history as suggested by @marmarek https://github.com/QubesOS/qubes-doc/pull/582#pullrequestreview-98203644 --- security/yubi-key.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/security/yubi-key.md b/security/yubi-key.md index 1df57b4f..91d42f44 100644 --- a/security/yubi-key.md +++ b/security/yubi-key.md @@ -81,11 +81,15 @@ To use this mode you need to: 6. Paste your hashed password (other than your standard Qubes password) into `/etc/qubes/yk-keys/yk-login-pass-hashed.hex` in dom0. - You can calculate your hashed password using this command: + You can calculate your hashed password using the following two commands. + First run the following command to store your password in a temporary variable `password`. + (This way your password will not leak to the terminal commnand history file.) - echo -n "PASSWORD" | openssl dgst -sha1 - - (Replace `PASSWORD` with your actual password.) + read password + + Now run the following command to calculate your hashed password. + + echo -n "$password" | openssl dgst -sha1 7. Edit `/etc/pam.d/login` in dom0. Add this line at the beginning: From f8c0eac48df36c1bbd25235481a36ed000d83aed Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Sun, 25 Feb 2018 15:36:02 +0100 Subject: [PATCH 3/3] fix typos --- security/yubi-key.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/security/yubi-key.md b/security/yubi-key.md index 91d42f44..0d12ddd3 100644 --- a/security/yubi-key.md +++ b/security/yubi-key.md @@ -50,11 +50,11 @@ To use this mode you need to: sudo apt-get install yubikey-personalization yubikey-personalization-gui - Shut down your TempalteVM. Then reboot your USB VM (so changes inside the TemplateVM take effect + Shut down your TemplateVM. Then reboot your USB VM (so changes inside the TemplateVM take effect in your TemplateBased USB VM or install the packages inside your USB VM if you would like to avoid rebooting your USB VM. -2. Configure your YubiKey for challenge-reponse `HMAC-SHA1` mode, for example +2. Configure your YubiKey for challenge-response `HMAC-SHA1` mode, for example [following this tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/). @@ -62,12 +62,12 @@ To use this mode you need to: - Choose `configuration slot 2`. - It is recommended to enable `Require user input (button press)` but this is optional. - - Note: Derivating from the above video, use the following settings select + - Note: Different from the above video, use the following settings select `HMAC-SHA1 mode`: `fixed 64 bit input`. - We will refer the `Secret Key (20 bytes hex)` as `AESKEY`. - It is recommended to keep a backup of your `AESKEY` in an offline VM used as vault. - Consider to keep a backup of your `AESKEY` on paper and store it in a safe place. - - In case you have multiple yubikeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other yubikeys. + - In case you have multiple YubiKeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other YubiKeys. 3. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in dom0. @@ -83,7 +83,7 @@ To use this mode you need to: You can calculate your hashed password using the following two commands. First run the following command to store your password in a temporary variable `password`. - (This way your password will not leak to the terminal commnand history file.) + (This way your password will not leak to the terminal command history file.) read password