first version of the knowledge base :)

2026-03-14 11:41:54 +01:00
commit 27965301ad
47 changed files with 4356 additions and 0 deletions
--- a/Guides/security/yubikey-usage.md
+++ b/Guides/security/yubikey-usage.md
@@ -0,0 +1,113 @@
+---
+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/)