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

YubiKey OpenPGP Recovery and Reset

Understanding YubiKey PIN Recovery and Reset

YubiKeys are exceptionally secure authentication devices, but this security comes with an important consideration: if you forget or lock your PINs, you will need to understand the proper procedures to recover access. This module covers scenarios when your YubiKey's OpenPGP application becomes locked or requires resetting and reinstallation of keys.

Common Recovery Scenarios

  • •
    User PIN locked - After 3 incorrect attempts
  • •
    Admin PIN locked - After 3 incorrect attempts
  • •
    Forgotten PIN - You can't remember the PIN values
  • •
    Corrupted OpenPGP applet - Rare firmware issues
  • •
    Key replacement - Replacing keys with new ones

Prerequisites for Recovery

  • •
    Backups of your GPG keys - Essential for reimporting
  • •
    Command-line tools - GnuPG and YubiKey Manager (ykman)
  • •
    Backup authentication methods - Ensure you have other ways to authenticate
  • •
    Time and patience - The process requires careful attention

Warning

The Importance of Key Backups

Without proper backups of your PGP keys, resetting your YubiKey means permanently losing access to anything encrypted with those keys. Always maintain secure backups of your key material before using it with a YubiKey, and store these backups securely (ideally offline and encrypted).

Understanding YubiKey PINs and Authentication

Before tackling recovery, let's understand the different PINs and their functions in the YubiKey OpenPGP application:

YubiKey PIN Types

User PIN

  • •
    Used for regular operations (signing, encryption, authentication)
  • •
    Default value: 123456
  • •
    Locks after 3 incorrect attempts
  • •
    Can be reset using Admin PIN

Admin PIN

  • •
    Used for administrative functions (changing settings, resetting User PIN)
  • •
    Default value: 12345678
  • •
    Locks after 3 incorrect attempts
  • •
    Can only be unlocked by resetting the entire OpenPGP application

Reset Code

  • •
    Optional PIN recovery mechanism (not set by default)
  • •
    Must be set before a PIN lockout occurs
  • •
    Provides a way to reset the User PIN without Admin PIN
  • •
    Limited in availability on older YubiKey models

Security Alert

PIN Strength Recommendations

When setting PINs, follow these security guidelines:

  • User PIN: At least 6 characters, preferably 8 or more for better security
  • Admin PIN: At least 8 characters, consider using 10+ characters for high-security needs
  • Reset Code: If used, should be at least 8 characters and stored securely
  • Use a mix of numbers, uppercase, lowercase, and special characters when supported
  • Never use the same PIN across multiple YubiKeys or for other applications

Recovery Scenarios and Solutions

Scenario 1: User PIN Is Locked (Admin PIN Available)

This is the simplest recovery scenario. If you've locked your User PIN by entering it incorrectly three times, but you still know your Admin PIN, you can reset it.

Step-by-Step: Resetting User PIN

  1. Check the card status to confirm the User PIN is locked 
          
        
# Check card status
gpg --card-status

    Look for "PIN retry counter" - if it shows "0 0 3" for the first value, the User PIN is locked.

  2. Enter the card administration mode 
          
        
# Enter card edit mode
gpg --card-edit

# At the gpg> prompt, enter admin mode
admin
  3. Access the password management menu 
          
        
# At the gpg/card> prompt
passwd
  4. Reset the User PIN

    At the password command menu:

    • Select option 1 for changing the PIN
    • You'll be prompted for the Admin PIN
    • Enter your current Admin PIN
    • Enter and confirm your new User PIN
  5. Verify the PIN has been reset 
          
        
# Quit the password menu
q

# Check the card status again
gpg --card-status

    The PIN retry counter should now show "3 0 3" for the first value.

Scenario 2: User PIN Is Locked (Reset Code Available)

If you previously set up a Reset Code on your YubiKey, you can use it to unlock your User PIN without needing the Admin PIN.

Step-by-Step: Using Reset Code

  1. Enter the card administration mode 
          
        
gpg --card-edit
admin
  2. Access the password management menu 
          
        
passwd
  3. Use the Reset Code to unlock the User PIN

    At the password command menu:

    • Select option 4 for unblocking PIN using Reset Code
    • Enter your Reset Code when prompted
    • Enter and confirm your new User PIN
  4. Verify the PIN has been reset 
          
        
# Quit the password menu
q

# Check the card status
gpg --card-status

Scenario 3: Admin PIN Is Locked (Full Reset Required)

If your Admin PIN is locked or forgotten, you'll need to completely reset the OpenPGP application on your YubiKey. This will erase all keys currently stored on the device.

Warning

This Process Will Delete Your Keys

Resetting the OpenPGP application completely wipes all keys from your YubiKey. You will need to restore your keys from backups after the reset. If you don't have backups of your keys, you will lose access to any data encrypted with those keys.

Step-by-Step: Complete Reset and Key Restoration

  1. Verify you have key backups before proceeding

    Either:

    • Confirm you have your keys in your GnuPG keyring (~/.gnupg/)
    • Verify you have exported key backups (e.g., master key backup file)
  2. Reset the OpenPGP application using YubiKey Manager 
          
        
# Reset the OpenPGP application
ykman openpgp reset

    You will be asked to confirm this destructive operation.

  3. Import your keys if necessary

    Skip this step if your keys are already in your GPG keyring.

          
        
# Import your master key backup
gpg --import ~/path/to/your/key-backup.asc
  4. Verify your keys are available 
          
        
# List your secret keys
gpg --list-secret-keys

# Look for your key ID, for example:
# sec   rsa4096/E6275DBD 2020-01-15 [SC]
# The key ID here is E6275DBD
  5. Transfer your keys to the YubiKey 
          
        
# Edit your key (replace with your actual key ID)
gpg --edit-key E6275DBD

    At the gpg> prompt:

          
        
# For the Signature key (first subkey or master key)
keytocard
# Select 1 when prompted (for Signature key)

# For the Encryption key (usually the second subkey)
key 2  # Select your encryption subkey
keytocard
# Select 2 when prompted (for Encryption key)

# For the Authentication key (usually the third subkey)
key 2  # Deselect previous key
key 3  # Select your authentication subkey
keytocard
# Select 3 when prompted (for Authentication key)

# Save and exit
save
  6. Set new PINs 
          
        
# Enter card editing mode
gpg --card-edit

# Enter admin mode
admin

# Enter PIN changing menu
passwd

# Change Admin PIN (option 3)
# - Enter current Admin PIN (default: 12345678)
# - Enter and confirm new Admin PIN

# Change User PIN (option 1)
# - Enter current User PIN (default: 123456)
# - Enter and confirm new User PIN

# Exit
quit
  7. Verify your configuration 
          
        
# Check the card status
gpg --card-status

# You should see your keys listed under the Authentication,
# Encryption, and Signature key sections
  8. Test your keys 
          
        
# Create a test signature
echo "test" | gpg --sign

# Verify the signature
echo "test" | gpg --sign | gpg --verify

    You should see a "Good signature" message if everything is working correctly.

Tip

Setting Up a Reset Code (Preventative Measure)

To avoid needing a full reset in the future, consider setting up a Reset Code on your YubiKey: 

      
        
# Enter card edit mode
gpg --card-edit

# Enter admin mode
admin

# Enter password menu
passwd

# Select option 8 for setting the Reset Code
# Follow the prompts to set your Reset Code

Note: This option may not be available on all YubiKey models or firmware versions. Store your Reset Code securely; it functions as a backup for your Admin PIN.

Advanced Recovery Techniques

Managing Key Stubs After Reset

When you reset a YubiKey that previously contained keys, you may need to manage the "stubs" (references to the card-stored keys) in your GPG keyring:

Working with Key Stubs

Identifying Stubs

When you list your secret keys, stubs typically show with a > character, indicating they point to an external card: 

      
        
gpg --list-secret-keys

Look for entries like:

sec#  rsa4096/E6275DBD 2020-01-15 [SC]
      ABCDEF1234567890ABCDEF1234567890ABCDEF12
uid           [ultimate] Your Name <[email protected]>
ssb>  rsa2048/1A2B3C4D 2020-01-15 [E]
ssb>  rsa2048/5E6F7G8H 2020-01-15 [A]
ssb>  rsa2048/9I0J1K2L 2020-01-15 [S]

The # indicates a stub for your master key, and > indicates stubs for your subkeys.

Re-importing Your Actual Keys

If you have stubs but need the actual keys: 

      
        
# Import your full key backup
gpg --import /path/to/full/key/backup.asc
Deleting Old Stubs

If you're having issues with conflicting stubs: 

      
        
# Delete the key from your keyring
gpg --delete-secret-keys E6275DBD

# Re-import your actual keys
gpg --import /path/to/full/key/backup.asc

Handling Multiple YubiKeys

If you use multiple YubiKeys with the same keys (e.g., a backup YubiKey), there are some special considerations:

Setting Up Identical YubiKeys

  1. 1. Prepare your keys

    Ensure you have your master key and subkeys in your GPG keyring

  2. 2. Configure first YubiKey

    Follow the standard key transfer process

  3. 3. Reset second YubiKey

    If needed, reset the OpenPGP application

  4. 4. Reimport backup keys

    Since the first transfer moved keys to card, reimport your full backup

  5. 5. Configure second YubiKey

    Repeat the key transfer process for the second device

  6. 6. Use consistent PINs

    For ease of use, consider setting the same PINs on both devices

Managing Multiple YubiKey Configurations

  • •
    Serial number awareness - GPG can distinguish YubiKeys by their serial numbers
  • •
    Key handles - After setup, the keys should work with any configured YubiKey
  • •
    Card switching - GPG will prompt for the relevant card if needed
  • •
    Inventory management - Label your YubiKeys to avoid confusion
  • •
    PIN management - Track which PINs are used for which devices
Complete Multiple YubiKey Setup Script

Troubleshooting Common Reset Issues

Common Problems and Solutions

Card Not Available Error

Problem: "gpg: error card not available: No SmartCard daemon"

Solutions:

  • →
    Check if pcscd service is running: systemctl status pcscd
  • →
    Start the service if needed: sudo systemctl start pcscd
  • →
    Restart the service: sudo systemctl restart pcscd
  • →
    Try removing and reinserting your YubiKey
Error Transferring to Card

Problem: "gpg: error transferring keys to the card: Invalid value"

Solutions:

  • →
    Make sure you have the actual private key material, not just stubs
  • →
    Check that your key type is compatible with your YubiKey model
  • →
    Try reimporting your full key backup
Operation Not Supported

Problem: "gpg: OpenPGP card not available: Operation not supported by device"

Solutions:

  • →
    Verify your YubiKey model supports OpenPGP
  • →
    Check if the OpenPGP applet is enabled using YubiKey Manager
  • →
    Make sure you're not in FIDO-only mode (check the touch button color)
Invalid Admin PIN Error

Problem: "gpg: 3 Admin PIN attempts remaining before card is permanently locked"

Solutions:

  • →
    Double-check you're entering the correct Admin PIN
  • →
    If using a brand new YubiKey, try the default Admin PIN: 12345678
  • →
    If you've forgotten your Admin PIN and attempts are low, consider resetting the OpenPGP application

Best Practices for YubiKey Recovery Preparedness

Preventative Measures

  • •
    Document your PINs securely in a password manager
  • •
    Create and maintain key backups in multiple secure locations
  • •
    Set up a Reset Code on your YubiKey if supported
  • •
    Have backup YubiKeys configured identically
  • •
    Label all YubiKeys with their purpose or serial number
  • •
    Implement alternative authentication methods for critical services

Recovery Kit Essentials

  • •
    Full key backups on encrypted USB drives or secure offline storage
  • •
    Recovery procedures documentation with step-by-step instructions
  • •
    Command reference guide with common GPG and YubiKey operations
  • •
    List of services using your YubiKey for authentication
  • •
    Backup authentication methods for critical services
  • •
    Spare, pre-configured YubiKey for immediate use

Security Alert

Key Backup Security

When storing backups of your GPG keys:

  • Always encrypt your key backups with a strong passphrase
  • Store backups on media that's not connected to any network
  • Consider splitting your master key using techniques like Shamir's Secret Sharing for high-value keys
  • Regularly check the integrity and readability of your backups
  • Secure physical access to your backups with appropriate physical security measures

Conclusion

YubiKey recovery and reset procedures are critical skills for anyone using hardware security keys for PGP operations. By understanding the different PIN types, recovery options, and proper reset procedures, you can ensure that you never lose access to your encrypted data, even if you encounter PIN lockouts or other issues.

Remember that the security of your YubiKey depends not just on the device itself, but on the entire system of key management, backups, and recovery procedures you put in place. A well-planned recovery strategy turns a potential catastrophe into a minor inconvenience.

Next Steps

To enhance your YubiKey security knowledge:

  • Create or update your key backup strategy
  • Document your PINs securely in your password manager
  • Consider setting up a Reset Code on your YubiKey
  • Prepare a backup YubiKey with the same keys
  • Practice the reset and recovery procedures in a controlled environment
  • Review the YubiKey Bio Setup guide for biometric authentication options

In This Module

Share This Module

Related Modules