Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-23 13:11:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

Include Nitrokey in MFA docs

Browse Source 
Merge branch 'pr-1380'
This commit is contained in:
unman 2024-04-20 13:09:18 +00:00
commit 81891e7828
No known key found for this signature in database
GPG Key ID: BB52274595B71262
1 changed files with 96 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
user/security-in-qubes/mfa.md
View File

@ -23,7 +23,9 @@ in Qubes OS accordingly). The recommended way for using CTAP in Qubes is describ
## Multi-factor login for Qubes OS ## Multi-factor login for Qubes OS
By default Qubes has two protection mechanisms against attackers. The first is full disk encryption and the second the user login screen / lockscreen. This article section concerns only adding multi-factor authentication to the second one. By default Qubes has two protection mechanisms against attackers.
The first is full disk encryption and the second the user login screen / lockscreen.
This article section concerns only adding multi-factor authentication to the second one.
### Time-based One-time Password (TOTP) ### Time-based One-time Password (TOTP)
@ -113,48 +115,49 @@ The first option is backup codes. When generating the TOTP secret you must have
The second option is recovery from a backup. It will work as long as you included dom0 in said backup. After restoring the dom0 backup, open a terminal in dom0 and the file should be located in `/home/<USER>/home-restore-<DATE>/dom0-home/<USER>/.google_authenticator`. The second option is recovery from a backup. It will work as long as you included dom0 in said backup. After restoring the dom0 backup, open a terminal in dom0 and the file should be located in `/home/<USER>/home-restore-<DATE>/dom0-home/<USER>/.google_authenticator`.
### Login with a YubiKey ### Login with a YubiKey / NitroKey3
"The YubiKey is a hardware authentication device manufactured by Yubico to The YubiKey / NitroKey3 is a hardware authentication device manufactured by Yubico / NitroKey
protect access to computers, networks, and online services that supports to protect access to computers, networks, and online services that supports
one-time passwords (OTP), public-key cryptography, and authentication, and the one-time passwords (OTP), public-key cryptography, and authentication, and the
Universal 2nd Factor (U2F) and FIDO2 protocols[1] developed by the FIDO Universal 2nd Factor (U2F) and FIDO2 protocols[1] developed by the FIDO Alliance.
Alliance." ([Wikipedia](https://en.wikipedia.org/wiki/YubiKey))
You can use a YubiKey to enhance the user authentication in Qubes. The following You can use a YubiKey / NitroKey3 to enhance the user authentication in Qubes. The following
instructions explain how to setup the YubiKey as an *additional* way to login. instructions explain how to setup the YubiKey / NitroKey3 as an *additional* way to login.
After setting it up, you can login by providing both - a password typed in via After setting it up, you can login by providing both - a password typed in via
keyboard *and* the YubiKey plugged in. Someone eavesdropping your login attempt keyboard *and* the YubiKey / NitroKey3 plugged in. Someone eavesdropping your login attempt
would not be able to login by only observing and remembering your password. would not be able to login by only observing and remembering your password.
Stealing your YubiKey would not suffice to login either. Only if an attacker has Stealing your YubiKey / NitroKey3 would not suffice to login either. Only if an attacker has
both, the password and the Yubikey, it would be possible to login (it is thus both, the password and the Yubikey / NitroKey3, it would be possible to login (it is thus
called [Multi-factor called [Multi-factor authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication)).
authentication](https://en.wikipedia.org/wiki/Multi-factor_authentication)).
The following instructions keep your current login password untouched and The following instructions keep your current login password untouched and
recommends to define a new, additional password that is used in combination with recommends to define a new, additional password that is used in combination with
the YubiKey only. This ensures that you a) do not accidentally lock yourself out the YubiKey / NitroKey3 only. This ensures that you a) do not accidentally lock yourself out
during setup and b) you do not need to fear [shoulder during setup and b) you do not need to fear [shoulder
surfing](https://en.wikipedia.org/wiki/Shoulder_surfing_(computer_security)) so surfing](https://en.wikipedia.org/wiki/Shoulder_surfing_(computer_security)) so
much (i.e. by not using your standard login password in public). much (i.e. by not using your standard login password in public).
#### Setup login with YubiKey #### Setup login with YubiKey / NitroKey3
To use the YubiKey for multi-factor authentication you need to To use the YubiKey / NitroKey3 for multi-factor authentication you need to
* install software for the YubiKey, * install software for the YubiKey / NitroKey3,
* configure the YubiKey for the * configure the YubiKey for the
[Challenge-Response](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication) [Challenge-Response](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication)
mode, mode or the NitroKey3 for [HOTP](https://en.wikipedia.org/wiki/HMAC-based_one-time_password) mode,
* store the password for YubiKey Login and the Challenge-Response secret in * store the password for YubiKey / NitroKey3 Login and the Challenge-Response / HOTP secret in
dom0, dom0,
* enable YubiKey authentication for every service you want to use it for. * enable YubiKey / NitroKey3 authentication for every service you want to use it for.
All these requirements are described below, step by step. All these requirements are described below, step by step, for the YubiKey and NitroKey3.
Note that setting up both a YubiKey and a NitroKey3 is not supported.
1. Install YubiKey software in the template on which your USB VM is based. 1. Install YubiKey / NitroKey3 software in the template on which your USB VM is based.
Without this software the challenge-response mechanism is not working. Without this software the challenge-response / HOTP mechanism won't work.
**YubiKey**
For Fedora. For Fedora.
@ -168,18 +171,38 @@ All these requirements are described below, step by step.
sudo apt-get install yubikey-personalization sudo apt-get install yubikey-personalization
``` ```
**NitroKey3**
Follow the installation instructions on the official [NitroKey
website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
**WARNING**: *as of April 2024 the official instructions involve using pipx to
install the pynitrokey package and its dependencies without any GPG
verification! This is not a recommended practice, but will soon be
fixed by NitroKey when they start providing release artifacts with
detached signatures on [their GitHub](https://github.com/Nitrokey/pynitrokey/releases).
Proper packaging and distribution for Debian and perhaps Fedora is
also planned for the mid-long term.*
**Installing packages using pip or pipx is not recommended!**
**both**
Shut down your template. Then, either reboot your USB VM (so changes inside Shut down your template. Then, either reboot your USB VM (so changes inside
the template take effect in your USB app qube) or install the packages inside the template take effect in your USB app qube) or install the packages inside
your USB VM as well if you would like to avoid rebooting it. your USB VM as well if you would like to avoid rebooting it.
2. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in 2. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in
dom0. This provides the program to authenticate with password and YubiKey. dom0. This provides the program to authenticate with password and YubiKey / NitroKey3.
``` ```
sudo qubes-dom0-update qubes-yubikey-dom0 sudo qubes-dom0-update qubes-yubikey-dom0
``` ```
3. Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be 3. Configure your YubiKey / NitroKey3:
**YubiKey**
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 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 YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube
though) or directly on the sys-usb vm. though) or directly on the sys-usb vm.
@ -196,24 +219,53 @@ though) or directly on the sys-usb vm.
to the vm, to the vm,
- press `Write Configuration` once you are ready. - press `Write Configuration` once you are ready.
We will refer the `Secret Key (20 bytes hex)` as `AESKEY`. **NitroKey3**
Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
USB qube and running the following commands in it:
```
AESKEY=$(echo -n "your-20-digit-secret" | base32)
nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
```
Note that the 20 digit sequence can contain any printable ASCII character,
e.g. letters, numbers, punctuation marks. The actual `Secret Key (base 32)`
is the base32 encoded form of that sequence.
**both**
We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault. - It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
- Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place. - Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
- If you have multiple YubiKeys for backup purposes (in case a yubikey gets - If you have multiple YubiKeys for backup purposes (in case one gets
lost, stolen or breaks) you can write the same settings into other lost, stolen or breaks) you can write the same settings into other
YubiKeys. You can choose "Program multiple YubiKeys" in the program, make sure YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
to select `Same secret for all keys` in this case. make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up
the secret for multiple of them, but you must always use the same NitroKey, because the
HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
of this method. If you want to switch to a different NitroKey later, delete the file
`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
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. Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. 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
the file `/etc/qubes/yk-keys/nk-hotp-secret` or its content!
**NitroKey3**
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 5. As mentioned before, you need to define a new password that is only used in
combination with the YubiKey. You can write this password in plain text into combination with the YubiKey / NitroKey3. You can write this password in plain text into
`/etc/qubes/yk-keys/yk-login-pass` in dom0. This is considered safe as dom0 is `/etc/qubes/yk-keys/login-pass` in dom0. This is considered safe as dom0 is
ultimately trusted anyway. ultimately trusted anyway.
However, if you prefer you can paste a hashed password instead into However, if you prefer you can paste a hashed password instead into
`/etc/qubes/yk-keys/yk-login-pass-hashed.hex` in dom0. `/etc/qubes/yk-keys/login-pass-hashed.hex` in dom0.
You can calculate your hashed password using the following two commands. 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`. First run the following command to store your password in a temporary variable `password`.
@ -235,9 +287,9 @@ ultimately trusted anyway.
auth include yubikey auth include yubikey
``` ```
to the corresponding service file in `/etc/pam.d/` in dom0. This means, if (same for YubiKey and NitroKey3) to the corresponding service file in `/etc/pam.d/` in dom0.
you want to enable the login via YubiKey for xscreensaver (the default screen This means, if you want to enable the login via YubiKey / NitroKey3 for xscreensaver
lock program), you add the line at the beginning of `/etc/pam.d/xscreensaver`. (the default screen lock program), you add the line at the beginning of `/etc/pam.d/xscreensaver`.
If you want to use the login for a tty shell, add it to `/etc/pam.d/login`. Add If you want to use the login for a tty shell, add it to `/etc/pam.d/login`. Add
it to `/etc/pam.d/lightdm` if you want to enable the login for the default it to `/etc/pam.d/lightdm` if you want to enable the login for the default
display manager and so on. display manager and so on.
@ -246,24 +298,24 @@ display manager and so on.
these files, otherwise it will most likely not work. 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 7. Adjust the 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. `sys-usb` by editing `/etc/qubes/yk-keys/vm` in dom0.
#### Usage #### Usage
When you want to authenticate When you want to authenticate
1. plug your YubiKey into an USB slot, 1. plug your YubiKey / NitroKey3 into an USB slot,
2. enter the password associated with the YubiKey, 2. enter the password associated with the YubiKey / NitroKey3,
3. press Enter and 3. press Enter and
4. press the button of the YubiKey, if you configured the confirmation (it will 4. press the button of the YubiKey / NitroKey3, if you configured the confirmation
blink). (it will light up or blink).
When everything is ok, your screen will be unlocked. When everything is ok, your screen will be unlocked.
In any case you can still use your normal login password, but do it in a secure In any case you can still use your normal login password, but do it in a secure
location where no one can snoop your password. location where no one can snoop your password.
#### Optional: Enforce YubiKey Login #### Optional: Enforce YubiKey / NitroKey3 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. 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.
@ -271,10 +323,9 @@ Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen loc
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
``` ```
#### Optional: Locking the screen when YubiKey is removed #### Optional: Locking the screen when YubiKey / NitroKey3 is removed
Look into it You can setup your system to automatically lock the screen when you unplug your YubiKey / NitroKey3.
You can setup your system to automatically lock the screen when you unplug your YubiKey.
This will require creating a simple qrexec service which will expose the ability to lock the screen to your USB VM, and then adding a udev hook to actually call that service. This will require creating a simple qrexec service which will expose the ability to lock the screen to your USB VM, and then adding a udev hook to actually call that service.
In dom0: In dom0: