Secure Mail Client | Academy / 201.3
All Topics Beginner Intermediate Advanced Download
Intermediate 25 minutes

YubiKey Hardware Setup for Maximum Security

Why Use Hardware Security Keys

When it comes to protecting your most sensitive encryption keys, hardware security devices like YubiKeys provide physical, air-gapped security that is nearly impossible to compromise remotely.

The Problem with Software-Only Security

Even with the best encryption and security practices, keys stored on your general-purpose computer face several vulnerabilities:

  • Malware exposure: Sophisticated malware can extract keys from memory or disk
  • Theft of devices: If your computer is stolen, encryption keys stored on it could be at risk
  • Backup vulnerabilities: Key backups may be compromised if not properly secured
  • User error: Accidental key exposure through improper file permissions or unintended sharing

Security Alert

Physical Security Matters

Hardware security tokens like YubiKeys implement a secure element chip designed to resist physical tampering and protect cryptographic operations.

Understanding YubiKeys

YubiKeys are small USB or NFC devices that provide hardware-based authentication and encryption capabilities. They can store and use cryptographic keys without ever exposing the private key material to the host computer.

Key YubiKey Features

  • Physical presence required: Requires someone to physically possess and touch the device
  • Tamper-resistant hardware: Designed to resist both software and physical attacks
  • No extractable keys: Private key material can never leave the device
  • Multi-protocol support: Works with FIDO2/WebAuthn, U2F, PIV, OpenPGP, and OTP authentication
  • No batteries required: Powered by the USB port or NFC field
  • Durable construction: Water and crush resistant
  • PIN protection: Configurable PIN requirement for key operations

Choosing the Right YubiKey

YubiKeys come in several form factors and capabilities:

  • YubiKey 5 Series: The most versatile, supporting all protocols (NFC and USB-A or USB-C variants)
  • YubiKey Bio Series: Includes fingerprint reader for additional authentication
  • Security Key Series: More affordable, but limited to FIDO2/WebAuthn and U2F protocols
  • YubiKey 5 Nano/5C Nano: Low-profile design meant to be left in the USB port

For encryption key storage and PGP use, you will want the YubiKey 5 series, not the limited Security Key series.

Tip

Redundancy is Essential

Security professionals recommend having at least two YubiKeys configured identically. Keep one as your primary device and store the backup in a secure location.

Setting Up Your YubiKey for OpenPGP

Prerequisites

  • A YubiKey that supports OpenPGP (YubiKey 5 series)
  • GnuPG (GPG) software installed on your computer
  • Basic familiarity with GPG key concepts

Step 1: Understanding YubiKey PINs

YubiKeys use a PIN system to protect the OpenPGP functionality. Understanding this system is crucial for secure operation:

YubiKey PIN Types

User PIN
  • Default: 123456
  • Used for: Daily operations (signing, decryption, authentication)
  • Min length: 6 characters
  • Max attempts: 3 before locking
Admin PIN
  • Default: 12345678
  • Used for: Administrative functions, unlocking User PIN
  • Min length: 8 characters
  • Max attempts: 3 before permanent blockage
Reset Code
  • Default: Not set
  • Used for: Resetting User PIN without Admin PIN
  • Min length: 8 characters
  • Optional but recommended

Warning

PIN Security is Critical

A YubiKey with default PINs provides almost no security. Change both PINs immediately after setup, before storing any sensitive keys on the device.

Step 2: Changing Your PINs

You should change both default PINs immediately using the GPG command line interface:

Change YubiKey PINs
      
        
# Connect to your YubiKey
gpg --card-edit

# Enter admin mode
admin

# Access the PIN menu
passwd

You will be prompted with several options. Select the following in order:

  1. Change the User PIN (option 1)
    • Enter current PIN: 123456 (default)
    • Enter new PIN twice (at least 6 characters)
  2. Change the Admin PIN (option 3)
    • Enter current Admin PIN: 12345678 (default)
    • Enter new Admin PIN twice (at least 8 characters)
  3. Set the Reset Code (option 4) - Recommended
    • Enter Admin PIN
    • Enter new Reset Code twice (at least 8 characters)

Choose PINs that are:

  • Sufficiently long (8+ characters recommended for better security)
  • Not easily guessable (avoid patterns, dates, names)
  • Memorable to you (you will use the User PIN frequently)
  • Different from each other (don't use the same PIN for both User and Admin)

Security Alert

Document Your PINs Securely

Record your PINs in a secure location such as a password manager. If you forget both your Admin PIN and Reset Code, you will not be able to recover the OpenPGP functionality on your YubiKey.

Step 3: Understanding PIN Recovery

PIN Blocking and Recovery

When User PIN is Blocked

After 3 incorrect attempts, the User PIN becomes blocked. You have two options to recover:

Option 1: Using Admin PIN
      
        
# Enter admin mode
gpg --card-edit
admin
passwd

# Select option 1 to unblock and set new User PIN
# Enter Admin PIN when prompted
Option 2: Using Reset Code
      
        
# Enter admin mode
gpg --card-edit
admin
passwd

# Select option 2 to reset User PIN with Reset Code
# Enter Reset Code when prompted
When Admin PIN is Blocked

After 3 incorrect Admin PIN attempts, the OpenPGP application on your YubiKey becomes permanently blocked.

Recovery Options
  1. 1. Reset the entire OpenPGP application (all keys will be lost)
  2. 2. Use your backup YubiKey (if configured)
  3. 3. Use your offline master key backup to reconfigure a new YubiKey
Resetting the OpenPGP Application
      
        
# WARNING: This will delete all keys on the YubiKey's OpenPGP application
gpg --card-edit
admin
factory-reset

# Confirm the reset when prompted

Warning

PIN Attempt Tracking

The YubiKey keeps track of PIN attempts even between sessions and computer restarts. Failed attempts are permanently counted until a successful PIN entry or a reset occurs.

Step 2: Configure YubiKey Settings

Before loading keys, configure important YubiKey settings through the GPG command line. Important settings include:

  • Name information (optional)
  • Touch policies - require physical touch for key operations
  • Key attributes and algorithm preferences

The touch policies are particularly important for security:

  • ON for signatures: Requires physical touch for each signature operation
  • ON for decryption: Requires touch for each decryption operation
  • ON for authentication: Requires touch for each authentication operation (like SSH)

Using Your YubiKey with Secure Mail Client

Secure Mail Client fully supports YubiKey integration for email encryption and signing:

Configuring Secure Mail Client for YubiKey

  1. Insert your YubiKey into a USB port
  2. Open Secure Mail Client and navigate to Settings > Security > OpenPGP
  3. Select "Use YubiKey or SmartCard" option
  4. Click "Detect Hardware Keys" - Secure Mail Client will automatically detect your YubiKey
  5. Select the key to use for email encryption/signing
  6. Save your settings

Once configured, Secure Mail Client will prompt for your YubiKey PIN and physical touch (if touch policies are enabled) whenever you need to sign or decrypt emails.

Enhanced Security Mode

For maximum security, enable "Enhanced Hardware Security" in Secure Mail Client settings. This mode:

  • Never caches PIN or unlocked state between operations
  • Requires YubiKey presence for all cryptographic operations
  • Verifies YubiKey serial number consistency between operations
  • Automatically locks when YubiKey is removed

Using Your YubiKey for SSH Authentication

One of the most powerful features of YubiKey is its ability to store SSH keys for server authentication, providing hardware-backed security for your server logins.

Security Alert

Hardware-Protected SSH Keys

With YubiKey SSH authentication, your private key material never leaves the secure hardware. Even if your computer is compromised, attackers cannot extract your SSH private key.

Prerequisites

  • YubiKey with an Authentication subkey loaded
  • GPG configured to work with your YubiKey
  • Basic understanding of SSH authentication

Platform-Specific Setup Instructions

Linux Setup

Configure GPG Agent to act as SSH agent:

Edit gpg-agent.conf
      
        
# Create or edit gpg-agent.conf
mkdir -p ~/.gnupg
echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf

Add to your shell configuration file (.bashrc, .zshrc, etc.):

Shell configuration
      
        
# Configure GPG for SSH authentication
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent

Get your SSH public key:

Export SSH public key
      
        
# Restart gpg-agent first
gpg-connect-agent RELOADAGENT /bye

# Get SSH public key
ssh-add -L

The output is your SSH public key that you can add to your servers.

macOS Setup

Configure GPG Agent:

Edit gpg-agent.conf
      
        
# Create or edit gpg-agent.conf
mkdir -p ~/.gnupg
echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf

Add to your shell configuration (.zshrc, .bash_profile, etc.):

Shell configuration
      
        
# Configure GPG for SSH authentication
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent

# Optional - to ensure pinentry works properly on macOS
export GPG_TTY=$(tty)

Get your SSH public key:

Export SSH public key
      
        
# Restart gpg-agent first
gpg-connect-agent RELOADAGENT /bye

# Get SSH public key
ssh-add -L

You may need to use pinentry-mac: brew install pinentry-mac

Windows Setup

Windows setup is more involved and has multiple options:

Option 1: Using GPG4Win
  1. 1. Install GPG4Win with GPA
  2. 2. Configure gpg-agent.conf:
Edit gpg-agent.conf
      
        
# C:\Users\USERNAME\AppData\Roaming\gnupg\gpg-agent.conf
enable-putty-support
enable-ssh-support

Use PuTTY for SSH connections, which will access GPG Agent through Pageant.

Option 2: Using Windows Subsystem for Linux (WSL)
  1. 1. Configure WSL following the Linux instructions
  2. 2. Ensure GPG can access your YubiKey in WSL
  3. 3. Configure environment variables in .bashrc:
WSL configuration
      
        
# In your WSL .bashrc file
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent

Configuring Servers to Accept Your YubiKey SSH Key

  1. Export your public SSH key using the command appropriate for your OS
  2. Copy your public key to the server 
          
        
# Example for Unix/Linux servers
ssh-copy-id -i /tmp/yubikey_ssh_key.pub [email protected]

# Alternatively, manually add to ~/.ssh/authorized_keys on the server
  3. Test your connection 
          
        
# Connect to your server
ssh [email protected]

# You should be prompted for your YubiKey PIN

Troubleshooting YubiKey SSH Authentication

Common Issues and Solutions

  • Problem: ssh-add -L returns "The agent has no identities."

    Solution: Ensure gpg-agent is properly configured and can see your authentication key. Check with gpg --card-status that your YubiKey is detected.

  • Problem: PIN dialog doesn't appear when connecting

    Solution: Check that pinentry is correctly configured. On macOS, you may need pinentry-mac. On Linux, ensure the correct pinentry program is specified in gpg-agent.conf.

  • Problem: YubiKey not detected

    Solution: Run gpg --card-status to check if GPG can see your YubiKey. You might need to restart gpg-agent with gpgconf --kill gpg-agent followed by gpgconf --launch gpg-agent.

  • Problem: Server connection refused

    Solution: Verify that your public key is correctly added to the server's authorized_keys file. Check server SSH logs for specific error messages.

Tip

Testing Without Making Changes

You can test if your YubiKey SSH setup is working without modifying your server by using the -v (verbose) flag with SSH: ssh -v user@server. Look for messages about offered public keys to confirm your YubiKey authentication key is being presented.

YubiKey Maintenance and Best Practices

Securing Your YubiKey

  • Physical security: Treat your YubiKey like a physical key to your digital life
  • Backup YubiKey: Configure at least two YubiKeys identically
  • Secure master key backup: Store your master key backups securely offline
  • PIN protection: Use strong PINs and never share them
  • PIN management: Have a secure way to remember your PINs

Conclusion

YubiKeys provide an exceptional security upgrade for anyone serious about protecting their digital identity and encrypted communications. By moving your encryption keys to a hardware security device, you create a physical security barrier that is extremely difficult for attackers to overcome.

The combination of hardware security, touch requirements, and PIN protection makes YubiKeys one of the most effective defenses against remote attacks, malware, and even sophisticated adversaries.

In the next module, we will explore key management best practices to ensure you maintain the highest level of security across all your encryption needs.

Next Steps

Now that you understand YubiKey setup:

  • Purchase a YubiKey 5 Series device (preferably two for redundancy)
  • Follow the guide to move your existing keys or create new keys on your YubiKey
  • Configure Secure Mail Client to use your YubiKey for email encryption
  • Set up SSH authentication using your YubiKey
  • Learn about Key Management Best Practices in our next module

In This Module

Share This Module

Related Modules