# 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)