🪪 OpenPGP Applications

Overview Windows Linux WSL2 Troubleshooting

📌 Overview

This guide explains how to use MiixKey's OpenPGP functionality for SSH authentication on three platforms:

Windows
Linux
WSL2 (Windows Subsystem for Linux)

⚠️ Important
On first use, you will need to enter the Admin PIN (default: 12345678) and the User PIN (default: 123456).

🪟 SSH Authentication on Windows

Tested environment: Windows 11

Step 1: View Keys

Run the following command to list keys:

gpg -k --keyid-format short --fingerprint --with-keygrip

Example output:

[keyboxd]---------
pub   rsa4096/67593603 2024-04-02 [SC]
      Key fingerprint = 0DD2 20B4 4255 5A4A 8A08  A1F4 72E3 910067593603
      Keygrip = 96111D8C38A28F0058DC0B1DE016336B7B76FBAA
uid         [ultimate] Metoo <linhui62@live.com>
sub   rsa4096/A04407D2 2024-04-02 [E]
      Keygrip = 0765BC114A6BA09BA2B6EB42412A7567D9A88534
sub   rsa4096/E96FF207 2024-04-02 [S]
      Keygrip = 6727D76635C2AE60C1CACE2D6BCD309C51CC020A
sub   rsa4096/11C9F011 2024-04-02 [A]
      Keygrip = 07F027D3697B4F26B88FE42C081C52FE51FF3328

Find the key marked [A] (authentication) and note its Keygrip and key ID.

Step 2: Export SSH Public Key

gpg --export-ssh-key 11C9F011

Example output:

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCqo+pBue94VZovQKrZ/3fVNGgvVbwLlbuTutNfK29juKE3eWuPv+n3RIELvtASrWua+1MLS1Up+g2soOjgozh85qvAxm1SWCFUkwvNdpgiydXH5G4xYwfdKMWzE7hKlblpMcKIGp/56AzNMoNIQr1hwocPIwT6E73gtWzSz4LRM6bKcwXrppVNbUeU8nYnMWSeaEHmMy5gnQKAXZfJALybW/Ir0iX7Q7mZGVBYUejY0tslqMyEaGOSLymeCNsFk3xIDp002DSj34C0HZXGKQdsYOa5PkyTC4JFcZ7CtV2zhQX2y7+9EHP73cY0kxNRinML2lE/6PpFhF5LqwhSqsW33QoU9cYiu4k2YvBGoRRgREYlZJZPZEF0XRmun0ZlhoYCbrgZpUum+9xMYXdBs67KszGwYqCERRn64Js+uBLTUqVbvCv8koOqjmcAWp6CAMwhZNbg05DRAzFpUBUb4GG156bKwOe28RS/pYNzm/RdjB2S3l/FHxECnfvAR6KLZDAkOhRTxEE8/PRag0INgx+7ifKiYQEE+aryconbJ5DvMLq1wZBbLPUtFjB6K+MOI4kXxaRLW7dJQ3eYq92pE8sIDDmObjXWm7jG+BeXIPN8XbCzmOQ+lapGHevW6XjviF3cbup94UT2tO5svLcz1Azk1tgYCUCphKC/lD+u3ZC2+w== openpgp:0x11C9F011

Add the output to the server's ~/.ssh/authorized_keys file.

Step 3: Configure GPG Agent

Edit the GPG agent config file at C:\Users\YourName\AppData\Roaming\gnupg\gpg-agent.conf and add:

enable-ssh-support
enable-putty-support
enable-win32-openssh-support

Then add the Keygrip of the [A] key to the sshcontrol file (each Keygrip on its own line).

🐧 SSH Authentication on Linux

Tested environment: Ubuntu 25

Install required packages:

sudo apt update && sudo apt install -y gnupg scdaemon pcscd

Configure device recognition — edit /etc/libccid_Info.plist and add the device VID/PID.

Disable CCID mode:

echo "disable-ccid" >> ~/.gnupg/scdaemon.conf

Restart the GPG agent:
```
gpg-connect-agent killagent /bye
```
Verify the connection:
```
gpg --card-status
```

Enable SSH support:

echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf

Set the environment variable:
```
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
```
Add this line to your ~/.bashrc or ~/.zshrc.
Verify the SSH key:
```
ssh-add -L
```
Test GitHub authentication:
```
ssh -T git@github.com
```

🔄 SSH Authentication on WSL2

Tested environment: Windows 11 host + Ubuntu on WSL2

Step 1: USB Passthrough

Run in PowerShell as Administrator:

winget install usbipd
usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

For details, refer to the Microsoft documentation.

Step 2: Install Packages

sudo apt update && sudo apt install -y gnupg scdaemon

Step 3: UDEV Rules

Create a rules file:

sudo nano /etc/udev/rules.d/98-miixkey.rules

Add the following content:

ACTION=="add", SUBSYSTEMS=="usb", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="0030", GROUP="plugdev", MODE="0660"

Step 4: GPG Configuration

Check device: gpg --card-status
Import public key: gpg --keyserver hkps://keyserver.ubuntu.com --search-keys "email or name"
Enable SSH support in ~/.gnupg/gpg-agent.conf
Configure the PIN entry program to point to the Windows path
Set the SSH_AUTH_SOCK environment variable

Step 5: SSH Configuration

nano ~/.ssh/config

Add the following:

Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"

Step 6: Verify

echo "test" | gpg --clearsign
ssh -T git@github.com

🔧 Troubleshooting

Problem	Solution
Device not recognized	Run `lsusb`, re-execute `usbipd wsl attach`, restart WSL with `wsl --shutdown`
Permission denied	`sudo usermod -aG plugdev $USER`, then `sudo reboot`
GPG agent issues	`gpgconf --kill gpg-agent`, then `gpg-connect-agent /bye`
SSH connection failed	Confirm the public key has been added to GitHub, update the agent status

MiixKey Mode Explanation PIV Applications