129 lines
3.1 KiB
Markdown
129 lines
3.1 KiB
Markdown
# Yubico Tools Suite
|
|
|
|
Hardware security key management and authentication tools for YubiKey.
|
|
|
|
## What's Included
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| **YubiKey Manager** | GUI to configure YubiKey settings, FIDO2 PIN, OTP slots, PIV |
|
|
| **Yubico Authenticator** | TOTP/HOTP authenticator using YubiKey hardware |
|
|
| **yubico-piv-tool** | Command-line PIV/Smart Card operations |
|
|
|
|
## Threat Model
|
|
|
|
**Protects Against:**
|
|
- Phishing attacks (FIDO2/WebAuthn is phishing-resistant)
|
|
- TOTP code theft from compromised phone
|
|
- Password-only authentication weaknesses
|
|
- Remote key extraction (keys never leave hardware)
|
|
|
|
**Use Cases:**
|
|
- 2FA for online accounts (GitHub, Google, AWS, etc.)
|
|
- Password-less authentication via FIDO2
|
|
- SSH authentication with hardware keys
|
|
- Code signing with PIV certificates
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
This will:
|
|
1. Install system dependencies (pcscd, smart card libs)
|
|
2. Download and install YubiKey Manager AppImage
|
|
3. Download and extract Yubico Authenticator
|
|
4. Download and extract yubico-piv-tool
|
|
5. Create launch scripts in ~/bin/
|
|
6. Create .desktop entries for app menu
|
|
|
|
## Dependencies
|
|
|
|
Installed automatically:
|
|
- `pcscd` - PC/SC smart card daemon
|
|
- `libpcsclite1` - Smart card library
|
|
- `libccid` - CCID driver for smart cards
|
|
- `libfuse2` - Required for AppImages
|
|
- `libu2f-udev` - udev rules for U2F devices
|
|
|
|
## Usage
|
|
|
|
### YubiKey Manager
|
|
```bash
|
|
yubikey-manager
|
|
# or
|
|
~/opt/yubico/yubikey-manager.AppImage
|
|
```
|
|
|
|
Configure:
|
|
- FIDO2 PIN
|
|
- OTP slots (Yubico OTP, static password, HOTP, Challenge-Response)
|
|
- PIV certificates and PINs
|
|
- Reset YubiKey to factory settings
|
|
|
|
### Yubico Authenticator
|
|
```bash
|
|
yubico-auth
|
|
# or
|
|
~/opt/yubico/authenticator/authenticator
|
|
```
|
|
|
|
Features:
|
|
- Scan QR codes to add TOTP/HOTP accounts
|
|
- Codes stored on YubiKey (not on computer)
|
|
- Touch YubiKey to reveal codes
|
|
- Works across devices (codes travel with YubiKey)
|
|
|
|
### yubico-piv-tool
|
|
```bash
|
|
~/opt/yubico/piv-tool/bin/yubico-piv-tool --help
|
|
|
|
# Generate key in slot 9a
|
|
yubico-piv-tool -a generate -s 9a -A RSA2048
|
|
|
|
# Import certificate
|
|
yubico-piv-tool -a import-certificate -s 9a -i cert.pem
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Set a strong FIDO2 PIN** - Required for WebAuthn
|
|
2. **Set PIV PINs** - Default is 123456, change immediately
|
|
3. **Keep backup keys** - Have a second YubiKey registered
|
|
4. **Store recovery codes** - For accounts using YubiKey 2FA
|
|
5. **Use touch requirement** - Enable touch for TOTP generation
|
|
|
|
## Troubleshooting
|
|
|
|
### YubiKey not detected
|
|
```bash
|
|
# Check pcscd service
|
|
sudo systemctl status pcscd
|
|
|
|
# Restart pcscd
|
|
sudo systemctl restart pcscd
|
|
|
|
# Check USB
|
|
lsusb | grep -i yubico
|
|
```
|
|
|
|
### Permission issues
|
|
```bash
|
|
# Add user to plugdev group
|
|
sudo usermod -aG plugdev $USER
|
|
# Log out and back in
|
|
```
|
|
|
|
### AppImage won't run
|
|
```bash
|
|
# Ensure libfuse2 is installed
|
|
sudo apt install libfuse2
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [YubiKey Manager docs](https://docs.yubico.com/software/yubikey/tools/ykman/)
|
|
- [Yubico Authenticator docs](https://docs.yubico.com/yesdk/users-manual/application-oath/authenticator.html)
|
|
- [PIV Tool docs](https://developers.yubico.com/yubico-piv-tool/)
|
|
- [YubiKey Setup Guide](https://support.yubico.com/hc/en-us/articles/360013714479)
|