114 lines
3.2 KiB
Markdown
114 lines
3.2 KiB
Markdown
---
|
|
title: YubiKey Usage
|
|
description: Guide to using a YubiKey for SSH, authentication, and key protection in self-hosted environments
|
|
tags:
|
|
- security
|
|
- yubikey
|
|
- ssh
|
|
category: security
|
|
created: 2026-03-14
|
|
updated: 2026-03-14
|
|
---
|
|
|
|
# YubiKey Usage
|
|
|
|
## Introduction
|
|
|
|
A YubiKey is a hardware token that can protect authentication and cryptographic operations. In homelab and engineering workflows, it is commonly used for MFA, SSH keys, and protection of GPG subkeys.
|
|
|
|
## Purpose
|
|
|
|
Use a YubiKey when you want:
|
|
|
|
- Stronger authentication than password-only login
|
|
- Private keys that require physical presence
|
|
- Portable hardware-backed credentials for administrative access
|
|
|
|
## Architecture Overview
|
|
|
|
YubiKeys can be used through different interfaces:
|
|
|
|
- FIDO2 or WebAuthn: MFA and modern hardware-backed authentication
|
|
- OpenSSH security keys: SSH keys such as `ed25519-sk`
|
|
- OpenPGP applet: card-resident GPG subkeys
|
|
- PIV: smart-card style certificate workflows
|
|
|
|
Choose the interface based on the workflow instead of trying to use one mode for everything.
|
|
|
|
## Step-by-Step Guide
|
|
|
|
### 1. Use the key for MFA first
|
|
|
|
Register the YubiKey with identity providers and critical services before moving on to SSH or GPG workflows.
|
|
|
|
### 2. Create a hardware-backed SSH key
|
|
|
|
On a system with OpenSSH support for security keys:
|
|
|
|
```bash
|
|
ssh-keygen -t ed25519-sk -C "admin@example.com"
|
|
```
|
|
|
|
This creates an SSH key tied to the hardware token.
|
|
|
|
### 3. Install the public key on servers
|
|
|
|
```bash
|
|
ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub admin@server.example
|
|
```
|
|
|
|
### 4. Test login
|
|
|
|
```bash
|
|
ssh admin@server.example
|
|
```
|
|
|
|
Expect a touch prompt when required by the device policy.
|
|
|
|
## Configuration Example
|
|
|
|
Example client SSH config for a dedicated administrative target:
|
|
|
|
```text
|
|
Host lab-admin
|
|
HostName server.example
|
|
User admin
|
|
IdentityFile ~/.ssh/id_ed25519_sk
|
|
```
|
|
|
|
For GPG workflows, move only subkeys onto the YubiKey and keep the primary key offline when possible.
|
|
|
|
## Troubleshooting Tips
|
|
|
|
### The key is not detected
|
|
|
|
- Confirm USB or NFC access is available
|
|
- Check whether another smart-card daemon has locked the device
|
|
- Verify the client OS has support for the intended mode
|
|
|
|
### SSH prompts repeatedly or fails
|
|
|
|
- Make sure the correct public key is installed on the server
|
|
- Confirm the client is offering the security-key identity
|
|
- Check that the OpenSSH version supports the selected key type
|
|
|
|
### GPG or smart-card workflows are inconsistent
|
|
|
|
- Verify which YubiKey applet is in use
|
|
- Avoid mixing PIV and OpenPGP instructions unless the workflow requires both
|
|
- Keep backup tokens or recovery paths for administrative access
|
|
|
|
## Best Practices
|
|
|
|
- Use the YubiKey as part of a broader account recovery plan, not as the only path back in
|
|
- Keep at least one spare token for high-value admin accounts
|
|
- Prefer hardware-backed SSH keys for administrator accounts
|
|
- Document which services rely on the token and how recovery works
|
|
- Separate MFA usage from certificate and signing workflows unless there is a clear operational reason to combine them
|
|
|
|
## References
|
|
|
|
- [Yubico: SSH](https://developers.yubico.com/SSH/)
|
|
- [Yubico: YubiKey and OpenPGP](https://developers.yubico.com/PGP/)
|
|
- [Yubico developer documentation](https://developers.yubico.com/)
|