Changes
Page history
yubikey: also move FAQ to the tutorial section
authored
Nov 12, 2025
by
anarcat
Hide whitespace changes
Inline
Side-by-side
howto/yubikey.md
View page @
026af6e7
...
...
@@ -146,6 +146,109 @@ instructions:
8.
If you have not already done so, generate and save the 2FA backup codes.
9.
Log out and log back in again, to verify the yubikey 2FA works.
## FAQ
### I don't have usb-c in my laptop, would i need an adaptor then?
If you get a USB-A key, yes, but you can get a USB-C key!
### Who should use this?
Everyone! If you're using a service like Nextcloud, the Discourse
forum, GitLab, you should enable 2FA and preferably with a
cryptographic token. That's not yet official policy, but it's probably
going to hit the security policy in some shape or form in the future.
### I do my work from Tails, do I need a Yubikey?
Yes, because Tails doesn't necessarily protect you against phishing attacks.
### Can I use the USB port during my work session, or i need to have the YubiKey plugged all the time?
You don't need to have it plugged in all the time.
One interesting aspect of the YubiKey is that you can unplug it and
decide "nope, authentication doesn't happen here anymore".
It's a clear way to secure that cryptographic material, physically.
### Any reason why we pick a Yubikey and not a tool with a open design like a NitroKey?
anarcat made a
[
review of the Nitrokey in 2017
](
https://anarc.at/blog/2017-10-26-comparison-cryptographic-keycards/
)
and found that
their form factor was less reliable than the YubiKey.
The Solokey was also considered but is not quite ready for prime time
yet. See also
[
this review
](
https://veronneau.org/solo-v2-nice-but-flawed.html
)
.
Google's Titan key was also an option but only supports 2FA (not
OpenPGP or SSH), see the
[
other alternatives
](
#other-alternatives
)
section for more
details.
### My Yubikey squirts out an OTP code when I accidentally touch it
There are several ways to deal with this issue. Since we don't use
[
Yubico OTP
](
https://www.yubico.com/resources/glossary/yubico-otp/
)
in Tor, the easiest solution is to simply disable the OTP app on the USB
interface.
First, ensure the Yubikey is inserted in one of your USB ports.
On the command-line, you can install the
`yubikey-manager`
package and run the
command below:
ykman config usb --disable otp
This program is also available with a GUI, installed with
`yubikey-manager-qt`
on Debian-based systems. Installers for other platforms such as Windows and
MacOS can be downloaded from the
[
Yubico website download page
](
https://www.yubico.com/support/download/yubikey-manager/
)
.
The procedure with the Yubikey Manager GUI is to open the program, click the
`Interfaces`
tab, and under
`USB`
, uncheck
`OTP`
and click
`Save interfaces`
.
Once this is done, OTP will remain disabled until it's manually re-enabled.
If you want to conserve the ability to generate Yubico OTP codes, there are two
options: either disable sending the
`<Enter>`
character using
`ykman otp
settings --no-enter 1`
, or swap the OTP to slot 2, which requires a sustained
2-second touch to activate, with
`ykman otp swap`
.
### I'm getting a "No YubiKey found" error
When running the
`ykman`
command, you might stumble upon the following error:
Error: No YubiKey found with the given interface(s)
This might happen because GnuPG (or probably a lock contention between
`ykman`
's
`pcscd`
and GnuPG's
`scdaemon`
).
The fix is unclear, but a workaround is to disconnect and reconnect
your YubiKey.
### After upgrading to GnuPG 2.4 I can't use my key anymore
If you're running debian sid or you've just upgraded to trixie, you most
probably switched to version 2.4 of GnuPG. You might then encounter this error:
# gpg --card-status
gpg: selecting card failed: No such device
gpg: OpenPGP card not available: No such device
A
[
NEWS item
](
https://salsa.debian.org/debian/gnupg2/-/blob/c1b1cb0d4526cb31dea7730d39d8d4945ea837d1/debian/NEWS#L1-8
)
was added to the debian gnupg package to warn about this problem. It used to be
that gnupg's scdaemon would first try its internal CCID mechanism, fail and then
default to trying with pcscd and that last part was how we were interacting with
the yubikeys through GnuPG. The fallback no longer happens, but we can tell
scdaemon to directly try with pcscd instead.
Open (or create if it doesn't exist)
`~/.gnupg/scdaemon.conf`
and add the
following line:
disable-ccid
Then restart the scdaemon with
`systemctl --user restart gpg-agent.service`
.
That should make you able to interact with your yubikey instead.
Note: it's also possible to use CCID
*instead*
of pcscd, but that change was not
investigated.
# How to
## SSH authentication
...
...
@@ -1089,109 +1192,6 @@ As opposed to private keys, which start with something like this:
(11:private-key[...]
## FAQ
### I don't have usb-c in my laptop, would i need an adaptor then?
If you get a USB-A key, yes, but you can get a USB-C key!
### Who should use this?
Everyone! If you're using a service like Nextcloud, the Discourse
forum, GitLab, you should enable 2FA and preferably with a
cryptographic token. That's not yet official policy, but it's probably
going to hit the security policy in some shape or form in the future.
### I do my work from Tails, do I need a Yubikey?
Yes, because Tails doesn't necessarily protect you against phishing attacks.
### Can I use the USB port during my work session, or i need to have the YubiKey plugged all the time?
You don't need to have it plugged in all the time.
One interesting aspect of the YubiKey is that you can unplug it and
decide "nope, authentication doesn't happen here anymore".
It's a clear way to secure that cryptographic material, physically.
### Any reason why we pick a Yubikey and not a tool with a open design like a NitroKey?
anarcat made a
[
review of the Nitrokey in 2017
](
https://anarc.at/blog/2017-10-26-comparison-cryptographic-keycards/
)
and found that
their form factor was less reliable than the YubiKey.
The Solokey was also considered but is not quite ready for prime time
yet. See also
[
this review
](
https://veronneau.org/solo-v2-nice-but-flawed.html
)
.
Google's Titan key was also an option but only supports 2FA (not
OpenPGP or SSH), see the
[
other alternatives
](
#other-alternatives
)
section for more
details.
### My Yubikey squirts out an OTP code when I accidentally touch it
There are several ways to deal with this issue. Since we don't use
[
Yubico OTP
](
https://www.yubico.com/resources/glossary/yubico-otp/
)
in Tor, the easiest solution is to simply disable the OTP app on the USB
interface.
First, ensure the Yubikey is inserted in one of your USB ports.
On the command-line, you can install the
`yubikey-manager`
package and run the
command below:
ykman config usb --disable otp
This program is also available with a GUI, installed with
`yubikey-manager-qt`
on Debian-based systems. Installers for other platforms such as Windows and
MacOS can be downloaded from the
[
Yubico website download page
](
https://www.yubico.com/support/download/yubikey-manager/
)
.
The procedure with the Yubikey Manager GUI is to open the program, click the
`Interfaces`
tab, and under
`USB`
, uncheck
`OTP`
and click
`Save interfaces`
.
Once this is done, OTP will remain disabled until it's manually re-enabled.
If you want to conserve the ability to generate Yubico OTP codes, there are two
options: either disable sending the
`<Enter>`
character using
`ykman otp
settings --no-enter 1`
, or swap the OTP to slot 2, which requires a sustained
2-second touch to activate, with
`ykman otp swap`
.
### I'm getting a "No YubiKey found" error
When running the
`ykman`
command, you might stumble upon the following error:
Error: No YubiKey found with the given interface(s)
This might happen because GnuPG (or probably a lock contention between
`ykman`
's
`pcscd`
and GnuPG's
`scdaemon`
).
The fix is unclear, but a workaround is to disconnect and reconnect
your YubiKey.
### After upgrading to GnuPG 2.4 I can't use my key anymore
If you're running debian sid or you've just upgraded to trixie, you most
probably switched to version 2.4 of GnuPG. You might then encounter this error:
# gpg --card-status
gpg: selecting card failed: No such device
gpg: OpenPGP card not available: No such device
A
[
NEWS item
](
https://salsa.debian.org/debian/gnupg2/-/blob/c1b1cb0d4526cb31dea7730d39d8d4945ea837d1/debian/NEWS#L1-8
)
was added to the debian gnupg package to warn about this problem. It used to be
that gnupg's scdaemon would first try its internal CCID mechanism, fail and then
default to trying with pcscd and that last part was how we were interacting with
the yubikeys through GnuPG. The fallback no longer happens, but we can tell
scdaemon to directly try with pcscd instead.
Open (or create if it doesn't exist)
`~/.gnupg/scdaemon.conf`
and add the
following line:
disable-ccid
Then restart the scdaemon with
`systemctl --user restart gpg-agent.service`
.
That should make you able to interact with your yubikey instead.
Note: it's also possible to use CCID
*instead*
of pcscd, but that change was not
investigated.
## Pager playbook
<!-- information about common errors from the monitoring system and -->
...
...
...
...
