From 5cb36a7e49697d2a4186731df6f33b44314b0104 Mon Sep 17 00:00:00 2001 From: Jordan Mynes Date: Tue, 8 Apr 2025 19:31:34 -0500 Subject: [PATCH 1/4] Update mfa.md Updated yubikey instructions for CLI --- user/security-in-qubes/mfa.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md index 62a72e173..8171d9a6a 100644 --- a/user/security-in-qubes/mfa.md +++ b/user/security-in-qubes/mfa.md @@ -200,16 +200,27 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). 3. Configure your YubiKey / NitroKey3: - **YubiKey** + **YubiKey (via CLI)** Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be done on any qube, e.g. a disposable (you need to [attach the YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube though) or directly on the sys-usb vm. - You need to (temporarily) install the package "yubikey-personalization-gui" and - run it by typing `yubikey-personalization-gui` in the command line. + This command will configure your Yubikey: + + `ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -a 303132333435363738393a3b3c3d3e3f40414243` + With the following settings: + - Configuration Slot: `2`, + - Challenge-Response Mode: `HMAC-SHA1`, + - Require usser input (Optional, but Recommended): `true`, + - HMAC-SHA1 Mode: `fixed 64 bit input` + + **Yubikey (via GUI)** + + Previously, this document mentioned to (temporarily) install the package "yubikey-personalization-gui" and + run it by typing `yubikey-personalization-gui` in the command line. However, this program is now [EOL](https://developers.yubico.com/yubikey-personalization-gui/), and is not present in Debian repositories newer than Bullseye (e.g. this package is not available in Debian Bookworm). The GUI instructions are left below for posterity: - In the program go to `Challenge-Response`, - select `HMAC-SHA1`, - choose `Configuration Slot 2`, @@ -248,7 +259,7 @@ of this method. If you want to switch to a different NitroKey later, delete the Do the same if for some reason your counters get desynchronized (it stops working), e.g. due to connectivity issues (NitroKey3A Minis are known to wear out quickly). -4. **YubiKey** +5. **YubiKey** Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. Note that if you had previously used a NitroKey3 with this package, you *must* delete @@ -259,7 +270,7 @@ to connectivity issues (NitroKey3A Minis are known to wear out quickly). Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` (in base 32 format) into it. -5. As mentioned before, you need to define a new password that is only used in +6. As mentioned before, you need to define a new password that is only used in combination with the YubiKey / NitroKey3. You can write this password in plain text into `/etc/qubes/yk-keys/login-pass` in dom0. This is considered safe as dom0 is ultimately trusted anyway. @@ -281,7 +292,7 @@ ultimately trusted anyway. echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' ' ``` -6. To enable multi-factor authentication for a service, you need to add +7. To enable multi-factor authentication for a service, you need to add ``` auth include yubikey @@ -297,7 +308,7 @@ display manager and so on. It is important, that `auth include yubikey` is added at the beginning of these files, otherwise it will most likely not work. -7. Adjust the USB VM name in case you are using something other than the default +8. Adjust the USB VM name in case you are using something other than the default `sys-usb` by editing `/etc/qubes/yk-keys/vm` in dom0. #### Usage From a8d25dd5e98f5283cb3b6369daa785d7e731d875 Mon Sep 17 00:00:00 2001 From: Jordan Mynes Date: Wed, 9 Apr 2025 11:07:30 -0500 Subject: [PATCH 2/4] fix: accidentally changed numbers of steps after intended changes --- user/security-in-qubes/mfa.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md index 8171d9a6a..a555e285c 100644 --- a/user/security-in-qubes/mfa.md +++ b/user/security-in-qubes/mfa.md @@ -259,7 +259,7 @@ of this method. If you want to switch to a different NitroKey later, delete the Do the same if for some reason your counters get desynchronized (it stops working), e.g. due to connectivity issues (NitroKey3A Minis are known to wear out quickly). -5. **YubiKey** +4. **YubiKey** Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. Note that if you had previously used a NitroKey3 with this package, you *must* delete @@ -270,7 +270,7 @@ to connectivity issues (NitroKey3A Minis are known to wear out quickly). Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` (in base 32 format) into it. -6. As mentioned before, you need to define a new password that is only used in +5. As mentioned before, you need to define a new password that is only used in combination with the YubiKey / NitroKey3. You can write this password in plain text into `/etc/qubes/yk-keys/login-pass` in dom0. This is considered safe as dom0 is ultimately trusted anyway. @@ -292,7 +292,7 @@ ultimately trusted anyway. echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' ' ``` -7. To enable multi-factor authentication for a service, you need to add +6. To enable multi-factor authentication for a service, you need to add ``` auth include yubikey @@ -308,7 +308,7 @@ display manager and so on. It is important, that `auth include yubikey` is added at the beginning of these files, otherwise it will most likely not work. -8. Adjust the USB VM name in case you are using something other than the default +7. Adjust the USB VM name in case you are using something other than the default `sys-usb` by editing `/etc/qubes/yk-keys/vm` in dom0. #### Usage From 35e595d00457c567dab2548566ea1153213afd9b Mon Sep 17 00:00:00 2001 From: Jordan Mynes Date: Wed, 9 Apr 2025 11:09:50 -0500 Subject: [PATCH 3/4] fix: indicate that the secret key used is an example --- user/security-in-qubes/mfa.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md index a555e285c..95f07044b 100644 --- a/user/security-in-qubes/mfa.md +++ b/user/security-in-qubes/mfa.md @@ -207,7 +207,7 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube though) or directly on the sys-usb vm. - This command will configure your Yubikey: + This command will configure your Yubikey, given a 20 character (all lowercase) secret key, like the example below: `ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -a 303132333435363738393a3b3c3d3e3f40414243` @@ -216,6 +216,7 @@ though) or directly on the sys-usb vm. - Challenge-Response Mode: `HMAC-SHA1`, - Require usser input (Optional, but Recommended): `true`, - HMAC-SHA1 Mode: `fixed 64 bit input` + - Secret Key (example): `303132333435363738393a3b3c3d3e3f40414243` **Yubikey (via GUI)** From 91b0aee350fe7f811f3193e66b6a6a485dfdaf1f Mon Sep 17 00:00:00 2001 From: Jordan Mynes Date: Wed, 9 Apr 2025 13:18:55 -0500 Subject: [PATCH 4/4] fix: should be 40 characters, not 20 also updated example key to be more obviously an example --- user/security-in-qubes/mfa.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md index 95f07044b..8b539440a 100644 --- a/user/security-in-qubes/mfa.md +++ b/user/security-in-qubes/mfa.md @@ -207,16 +207,16 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube though) or directly on the sys-usb vm. - This command will configure your Yubikey, given a 20 character (all lowercase) secret key, like the example below: + This command will configure your Yubikey, given a 40 character (all lowercase) secret key, like the example below: - `ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -a 303132333435363738393a3b3c3d3e3f40414243` + `ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -ochal-btn-trig -a 0123456789abcdef0123456789abcdef01234567` With the following settings: - Configuration Slot: `2`, - Challenge-Response Mode: `HMAC-SHA1`, - Require usser input (Optional, but Recommended): `true`, - HMAC-SHA1 Mode: `fixed 64 bit input` - - Secret Key (example): `303132333435363738393a3b3c3d3e3f40414243` + - Secret Key (example): `0123456789abcdef0123456789abcdef01234567` **Yubikey (via GUI)**