|
|
---
|
|
|
title: YubiKey setup
|
|
|
title: YubiKey documentation
|
|
|
---
|
|
|
|
|
|
YubiKeys are rugged security keys that can do FIDO2 two-factor
|
|
|
authentication (2FA), PKCS and OpenPGP operations, all inside a small
|
|
|
USB form factor.
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
# Tutorial
|
|
|
|
|
|
<!-- simple, brainless step-by-step instructions requiring little or -->
|
|
|
<!-- no technical background -->
|
|
|
|
|
|
# How to
|
|
|
|
|
|
## Use the PIV feature as a two-factor ssh-rsa key
|
|
|
## SSH RSA authentication in PIV mode
|
|
|
|
|
|
### Token setup
|
|
|
|
... | ... | @@ -82,9 +91,265 @@ protocol for non-TPO hosts, you may add this at the end of `~./ssh/config`: |
|
|
IdentityAgent /dev/null
|
|
|
IdentityFile ~/.ssh/id_ed25519_sk
|
|
|
|
|
|
## Pager playbook
|
|
|
|
|
|
<!-- information about common errors from the monitoring system and -->
|
|
|
<!-- how to deal with them. this should be easy to follow: think of -->
|
|
|
<!-- your future self, in a stressful situation, tired and hungry. -->
|
|
|
|
|
|
## Disaster recovery
|
|
|
|
|
|
<!-- what to do if all goes to hell. e.g. restore from backups? -->
|
|
|
<!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
|
|
|
<!-- "Installation" below but some pointers. -->
|
|
|
|
|
|
# Reference
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
When you receive your YubiKey, you need to first inspect the "blister"
|
|
|
package to see if it has been tampered with.
|
|
|
|
|
|
Then, open the package, connect the key to a computer and visit this
|
|
|
page in a web browser:
|
|
|
|
|
|
<https://www.yubico.com/genuine/>
|
|
|
|
|
|
This will guide you through verifying the key's integrity.
|
|
|
|
|
|
Out of the box, the key should work for two-factor authentication with
|
|
|
FIDO2 on most websites. It is imperative that you keep a copy of the
|
|
|
backup or "scratch" codes that are usually provided when you setup 2FA
|
|
|
on the site, as you may lose the key and that is the only way to
|
|
|
recover from that.
|
|
|
|
|
|
For other setups, see the following how-to guides:
|
|
|
|
|
|
* [SSH RSA authentication in PIV mode](#ssh-rsa-authentication-in-piv-mode)
|
|
|
|
|
|
## Upgrades
|
|
|
|
|
|
YubiKeys cannot be upgraded, the firmware is read-only.
|
|
|
|
|
|
## SLA
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Design and architecture
|
|
|
|
|
|
A YubiKey is an integrated circuit that performs cryptographic
|
|
|
operations on behalf of a host. In a sense, it is a tiny air-gapped
|
|
|
computer that you connect to a host, typically over USB but Yubikeys
|
|
|
can also operate over NFC.
|
|
|
|
|
|
## Services
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Storage
|
|
|
|
|
|
The YubiKeys keep private cryptographic information embedded in the
|
|
|
key, for example RSA keys for the SSH authentication mechanism. Those
|
|
|
keys are supposed to be impossible to extract from the Yubikey, which
|
|
|
means they are also impossible to backup.
|
|
|
|
|
|
## Queues
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Interfaces
|
|
|
|
|
|
YubiKeys use a few standards for communication:
|
|
|
|
|
|
* FIDO2 for 2FA
|
|
|
* PIV for SSH authentication
|
|
|
* OpenPGP "smart card" applet for OpenPGP signatures, authentication
|
|
|
and encryption
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
It's possible to verify the integrity of a key by visiting:
|
|
|
|
|
|
<https://www.yubico.com/genuine/>
|
|
|
|
|
|
## Implementation
|
|
|
|
|
|
The firmware on YubiKeys is proprietary and closed source, a major
|
|
|
downside to this platform.
|
|
|
|
|
|
## Related services
|
|
|
|
|
|
YubiKeys can be used to authenticate with the following services:
|
|
|
|
|
|
| Service | Authentication type |
|
|
|
|---------------|---------------------|
|
|
|
| [Discourse][] | 2FA |
|
|
|
| [GitLab][] | 2FA, SSH |
|
|
|
| [Nextcloud][] | 2FA |
|
|
|
|
|
|
[Discourse]: service/forum
|
|
|
[GitLab]: howto/gitlab
|
|
|
[Nextcloud]: service/nextcloud
|
|
|
|
|
|
## Issues
|
|
|
|
|
|
There is no issue tracker specifically for this project, [File][] or
|
|
|
[search][] for issues in the [team issue tracker][search] with the
|
|
|
label ~Foo.
|
|
|
|
|
|
[File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
|
|
|
[search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues?label_name%5B%5D=Foo
|
|
|
|
|
|
## Maintainer
|
|
|
|
|
|
anarcat worked on getting a bunch of YubiKeys shipped to a Tor meeting
|
|
|
in 2023, and is generally the go-to person for this, with a fallback
|
|
|
on TPA.
|
|
|
|
|
|
## Users
|
|
|
|
|
|
All tor-internal people are expected to have access to a YubiKey and
|
|
|
know how to use it.
|
|
|
|
|
|
## Upstream
|
|
|
|
|
|
YubiKeys are manufactured by [Yubico](https://www.yubico.com), a company headquartered in
|
|
|
Palo Alto in California, but with Swedish origins.
|
|
|
|
|
|
## Monitoring and metrics
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Tests
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Logs
|
|
|
|
|
|
N/A
|
|
|
|
|
|
## Backups
|
|
|
|
|
|
YubiKeys backups are complicated by the fact that you can't actually
|
|
|
extract the secret key from a YubiKey.
|
|
|
|
|
|
### FIDO2 keys
|
|
|
|
|
|
For 2FA, there's no way around it: the secret is generated on the key
|
|
|
and stays on the key. The mitigation is to keep a copy of the backup
|
|
|
codes in your password manager.
|
|
|
|
|
|
### OpenPGP keys
|
|
|
|
|
|
For OpenPGP, you may want to generate the key outside the YubiKey and
|
|
|
copy it in, that way you can backup the private key somewhere. A
|
|
|
robust and secure backup system for this would be made in three parts:
|
|
|
|
|
|
1. the main YubiKey, which you use every day
|
|
|
2. a backup YubiKey, which you can switch to if you lose the first
|
|
|
one
|
|
|
3. a copy of the OpenPGP secret key material, encrypted with itself,
|
|
|
so you can create a second key when you lose a key
|
|
|
|
|
|
The idea of the last backup is that you can recover the key material
|
|
|
from the first key with the second key and make a new key that
|
|
|
way. It may seem strange to encrypt a key with itself, but it is
|
|
|
actually relevant in this specific use case, because another copy of
|
|
|
the secret key material is available on the backup YubiKey.
|
|
|
|
|
|
## Other documentation
|
|
|
|
|
|
* [Anarcat's old (2015) Yubikey howto](https://anarc.at/blog/2015-12-14-yubikey-howto/)
|
|
|
* [Yubikey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/) |
|
|
* [A Yubikey cheatsheet](https://debugging.works/blog/yubikey-cheatsheet/)
|
|
|
* [TPA-RFC-53][] and [discussion ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083)
|
|
|
|
|
|
[TPA-RFC-53]: policy/tpa-rfc-53-security-keys
|
|
|
|
|
|
# Discussion
|
|
|
|
|
|
While we still have to make an all-encompassing security policy
|
|
|
([TPA-RFC-18](policy/tpa-rfc-18-security-policy)), we have decided in April 2023 to train our folks to
|
|
|
use YubiKeys as security keys, see [TPA-RFC-53][] and [discussion
|
|
|
ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083).
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
## Security and risk assessment
|
|
|
|
|
|
### Background
|
|
|
|
|
|
TPA (Tor Project system Administrators) is looking at strengthening
|
|
|
our security by making sure we have stronger two-factor authentication
|
|
|
(2FA) everywhere. We have mandatory 2FA on some services, but this can
|
|
|
often take the form of phone-based 2FA which is prone to social
|
|
|
engineering attacks.
|
|
|
|
|
|
This is important because some high profile organizations like ours
|
|
|
were compromised by hacking into key people's accounts and destroying
|
|
|
critical data or introducing vulnerabilities in their software. Those
|
|
|
organisations had 2FA enabled, but attackers were able to bypass that
|
|
|
security by hijacking their phones, which is why having a
|
|
|
cryptographic token like a Yubikey is important.
|
|
|
|
|
|
We also don't necessarily provide people with the means to more
|
|
|
securely store their (e.g. SSH) private keys, used commonly by
|
|
|
developers to push and sign code. So we are considering buying a bunch
|
|
|
of Yubikeys, bringing them to the next Tor meeting, and training
|
|
|
people to use them.
|
|
|
|
|
|
There's all sorts of pitfalls and challenges in deploying 2FA and
|
|
|
YubiKeys (e.g. "i lost my yubikey" or "omg GnuPG is hell"). We're not
|
|
|
going to immediately solve all of those issues. We're going to get
|
|
|
hardware into people's hands and hopefully train them with U2F/FIDO2
|
|
|
web 2FA, and maybe be able to explore the SSH/OpenPGP side of things
|
|
|
as well.
|
|
|
|
|
|
### Threat model
|
|
|
|
|
|
The main threat model is phishing, but there's another threat actor to
|
|
|
take into account: powerful state-level adversaries. Those have the
|
|
|
power to intercept and manipulate packages as they ship for
|
|
|
example. For that reason, we were careful in how the devices were
|
|
|
shipped, and they were handed out in person at an in-person
|
|
|
meeting.
|
|
|
|
|
|
Users are also encouraged to authenticate their YubiKey using the
|
|
|
Yubico website, which should provide a reliable attestation that the
|
|
|
key was really made by Yubico.
|
|
|
|
|
|
That assumes trust in the corporation, of course. The rationale there
|
|
|
is the reputation cost for YubiKey would be too high if they allowed
|
|
|
backdoors in their services, but it is of course a possibility that a
|
|
|
rogue employee (or Yubico itself) could leverage those devices to
|
|
|
successfully attack the Tor project.
|
|
|
|
|
|
### Future work
|
|
|
|
|
|
Ideally, there would be a rugged *and* open-hardware device that could
|
|
|
simultaneously offer the tamper-resistance of the Yubikey while at the
|
|
|
same time providing an auditable hardware platform.
|
|
|
|
|
|
## Technical debt and next steps
|
|
|
|
|
|
At this point, we need to train users on how to use those devices, and
|
|
|
factor this in a broader security policy ([TPA-RFC-18](policy/tpa-rfc-18-security-policy)).
|
|
|
|
|
|
## Proposed Solution
|
|
|
|
|
|
This was adopted in [TPA-RFC-53][], see also the [discussion
|
|
|
ticket](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41083).
|
|
|
|
|
|
## Other alternatives
|
|
|
|
|
|
* [tillitis.se](https://tillitis.se/): not ready for end-user adoption yet
|
|
|
* [Passkeys](https://fidoalliance.org/passkeys/) are promising, but have their own pitfalls. They
|
|
|
certainly do not provide "2FA" in the sense that they do not add an
|
|
|
extra authentication mechanism on top of your already existing
|
|
|
passwords. Maybe that's okay? It's still early to tell how well
|
|
|
passkeys will be adopted and whether they will displace traditional
|
|
|
mechanisms or not.
|
|
|
* [Nitrokey](https://www.nitrokey.com/fr): not rugged enough
|
|
|
* [Solokey](https://solokeys.com/): still at the crowdfunding stage
|
|
|
* [FST-01](https://www.gniibe.org/FST-01/fst-01.html): EOL, hard to find, gniibe is working on a [smartcard
|
|
|
reader](https://www.gniibe.org/memo/development/ttxs/ttxs-hardware-another.html)
|
|
|
* [Titan keys](https://cloud.google.com/titan-security-key/): FIDO2 only, but ships built-in with Pixel phones |