YubiKey Usage

Guide to using a YubiKey for SSH, authentication, and key protection in self-hosted environments

created: Sat Mar 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time) updated: Sat Mar 14 2026 00:00:00 GMT+0000 (Coordinated Universal Time) #security#yubikey#ssh

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:

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

ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub admin@server.example

4. Test login

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:

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