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