佩璃的小屋

yubikey配置：基于resident-key实现在任意设备上安全使用ssh密钥。

Tue, 26 May 2026 00:00:00 GMT

前言#

YubiKey 是一款由 Yubico 出品的硬件安全密钥，主要用于多因素认证（MFA）、密码管理、数字签名以及 SSH 身份验证等场景。它通过 USB、NFC 或 Lightning 接口与设备连接，可以生成一次性密码（OTP）、支持 FIDO2/WebAuthn、PIV（智能卡）以及 OpenPGP 等多种安全协议。YubiKey 的核心优势在于私钥永不离开硬件设备，即使电脑或网络被攻破，密钥仍然安全。

驻留密钥（Resident Key, RK）是 YubiKey 和 OpenSSH 中的一项功能，允许将 SSH 私钥直接存储在硬件设备内部，而不是依赖本地文件系统。与传统的 SSH 私钥文件不同，驻留密钥具备以下特点：

便携性：密钥随 YubiKey 携带，无需在每台设备上复制私钥。
安全性：私钥不会离开硬件设备，即使设备被接入不可信计算机，也无法导出密钥。
便捷性：支持在陌生设备上即插即用，通过硬件认证即可完成 SSH 登录，无需额外传输私钥。
多密钥管理：同一个 YubiKey 可存储多个 SSH 驻留密钥，并通过用户名或服务器标识选择使用。

问题背景

传统ssh需要在设备上提前配置好ssh密钥，与设备绑定在一起。一旦遇到突发情况，身边没有自己设备，需要在陌生设备上使用ssh密钥就会非常麻烦。

解决方案

通过yubikey驻留密钥将ssh私钥储存在物理密钥中，这样只需要携带有yubikey，可以在任何设备上使用ssh密钥，也可以有效避免对密钥的误操作。

准备环境#

openSSH在8.2后添加了对fido驻留密钥的支持，只需要安装openSSH版本大于8.2，并启用fido库即可使用。

Windows#

Window11自带全部环境，插上即用，无须配置。（win易用性这块还是不错的）

Linux#

主流发行版openSSH均支持驻留密钥，只需要安装fido库即可。如果不确定自己的openSSH版本是否支持可以使用ssh -V来检查。

Debian/Ubuntu

Terminal window

1
sudo apt install libfido2-1

Fedora/RHEL

Terminal window

1
sudo dnf install libfido2

macOS#

警告

从macOS12开始，默认openSSH已经支持驻留密钥。但不幸的，苹果出于一些原因在编译openSSH时添加了--disable-security-key参数禁用了安全密钥的支持。这使得在macOS12无法使用安全密钥功能，除非重新编译安装openSSH。但已有openSSH和icloud钥匙串存在联系，重新编译会破坏功能。我认为这并不是一个好的解决方案，所以不在考虑。幸运的，社区对苹果禁用安全密钥的问题作出了许多积极的反馈，在macOS Sonoma中安全密钥重新可用，只是不再提供中间件。本文基于此解决方案编写，仅适用于macOS Sonoma及以上。

基于社区的讨论，在macOS Sonoma之后的openSSH中已经可以使用安全密钥，只需要自己编译 libfido2 来提供自己的 SSH_SK_PROVIDER。可以使用如下脚本来实现编译安装，脚本来自GitHub。

macskeyinstaller.sh展开收起

1
#!/bin/bash
2

3
################################################################################################
4
# Last Updated: January 13, 2025
5
#
6
# macOS OpenSSH Client Patcher for Hardware Security Key Support (ED25519-SK With YubiKey Etc.)
7
# Check out https://gist.github.com/BertanT/9d222da115ca2d1274ef34735c4260cf for details!
8
#
9
# Copyright 2025 Mehmet Bertan Tarakcioglu (github.com/BertanT), under the MIT License.
10
################################################################################################
11

12
# Exit early if there is an error
13
set -e
14

15
printf "\n* Hello! This script compiles and installs the security key provider for the built-in macOS Open SSH client to enable support for hardware security keys (such as a YubiKey)."
16

17
# Check if the script is running as root
18
if [ "$(id -u)" -eq 0 ]; then
19
  printf "\n!!! Error: For safety reasons, this script cannot be run as root. If using sudo, please try again without it.\n" >&2
20
  exit 1
21
fi
22

23
# Function to compare macOS version strings
24
version_ge() {
25
  [[ "$(echo -e "$1\n$2" | sort -V | head -n1)" == "$2" ]]
26
}
27

28
# function to get the current macOS Version
29
macos_version=$(sw_vers -productVersion | cut -d '.' -f1,2)
30

31
# Check if running at least macOS Sonoma
32
if ! version_ge "$macos_version" "14.0"; then
33
  printf "\n!!! Error: macOS version is $macos_version. This script requires at least macOS Sonoma (14.0).\n" >&2
34
  exit 1
35
fi
36
printf "\n* macOS version is supported!"
37

38
# Check if Homebrew is installed
39
if ! which brew &>/dev/null; then
40
  printf "\n!!! Error: This script requires Homebrew to install dependencies! Please install Homebrew and try again\n" >&2
41
  exit 1
42
fi
43
printf "\n* Homebrew is installed!"
44

45
printf "\n* Cloning the latest main branch of openssh-portable from GitHub. This may take a while..."
46
git clone --quiet https://github.com/openssh/openssh-portable.git
47
cd openssh-portable
48

49
printf "\n* Installing dependencies from Homebrew: libfido2, openssl, autoconf, automake, libtool\n"
50
brew install libfido2 openssl autoconf automake libtool pkgconf
51

52
printf "\n* Generating configuration script."
53
autoreconf -i
54

55
printf "\n* Exporting flags."
56

57
# Determine the CPU architecture and set the appropriate Homebrew base path
58
if [[ "$(uname -m)" == "arm64" ]]; then
59
  BREW_PREFIX="/opt/homebrew"
60
elif [[ "$(uname -m)" == "x86_64" ]]; then
61
  BREW_PREFIX="/usr/local"
62
else
63
  echo "!!! Error: Unknown CPU architecture $(uname -m).\n" >&2
64
  exit 1
65
fi
66

67
# Get the appropriate paths for the Homebrew dependecies as they differ through version
68
BREW_OPENSSL_PATH=$(ls -d $BREW_PREFIX/Cellar/openssl@3/*)
69
BREW_LIBFIDO2_PATH=$(ls -d $BREW_PREFIX/Cellar/libfido2/*)
70
export CFLAGS="-L$BREW_OPENSSL_PATH/lib -I$BREW_OPENSSL_PATH/include -L$BREW_LIBFIDO2_PATH/lib -I$BREW_LIBFIDO2_PATH/include -Wno-error=implicit-function-declaration"
71
export LDFLAGS="-L$BREW_OPENSSL_PATH/lib -L$BREW_LIBFIDO2_PATH/lib"
72

73
printf "\n* Configuring build. This may take a while..."
74
./configure --quiet --with-security-key-standalone
75

76
printf "\n* Cleaning previous build for good measure."
77
make --quiet clean
78

79
printf "\n* Building OpenSSH Portable."
80
make --quiet
81

82
printf "\n* Copying the Security Key Provider library to /usr/local/lib."
83
printf "\n  We need root privileges to modify system files.\n"
84
sudo mkdir -p /usr/local/lib
85
sudo mv sk-libfido2.dylib /usr/local/lib/
86

87
# Check if the script is running in ZSH. If not, give the user instructions.
88
# Otherwise, modify .zshenv to set the environment variable if not already present.
89
if [[ "$SHELL" == *zsh* ]]; then
90
  printf "\n* Configuring the ~/.zshenv for the System SSH use the Security Key Provider we just built"
91
    if ! grep -q "export SSH_SK_PROVIDER=/usr/local/lib/sk-libfido2.dylib" "$HOME/.zshenv" &>/dev/null; then
92
        echo "export SSH_SK_PROVIDER=/usr/local/lib/sk-libfido2.dylib" >> "$HOME/.zshenv"
93
        printf "\n* Added SSH_SK_PROVIDER to ~/.zshenv."
94
    else
95
        printf "\n* SSH_SK_PROVIDER is already configured in ~/.zshenv."
96
    fi
97
else
98
  printf "*\n Since you are not on ZSH, you will need to manually configure your shell profile to tell the System SSH client to use the Security Key Provider we just built."
99
  printf "\n  The shell profile should export the environment variable as follows:"
100
  printf "\n  export SSH_SK_PROVIDER=/usr/local/lib/sk-libfido2.dylib"
101
fi
102

103
printf "\n* Exiting the directory and deleting the repository we cloned. We don't need it anymore"
104
cd ..
105
rm -rf openssh-portable
106

107
printf "\n\n* That's it! After restarting your terminal session, you can plug in your hardware security key and test the installation using:"
108
printf "\n  ssh-keygen -t ed25519-sk -O resident -O verify-required -C \"Your Comment\""
109
printf "\n\nHave a nice day! :)\n\n"

展开收起

yubikey配置#

生成驻留密钥#

创建 SSH 驻留密钥（Resident Key）非常简单，只需要在生成密钥时添加 -O resident 选项。

Terminal window

1
ssh-keygen \
2
  -t ed25519-sk \
3
  -O resident \
4
  -O verify-required

参数说明

-t ed25519-sk：指定证书类型为Ed25519
-O resident：将私钥存储在 YubiKey 内部（驻留密钥）
-O verify-required：每次使用时需要验证pin码

之后安装提示输入PIN码并触碰金属触点即可完成配置。

从yubikey导出驻留密钥公钥#

在新设备上使用驻留密钥也很简单，只需要使用使用

Terminal window

1
ssh-keygen -K

即可从yubikey中导出所有驻留密钥的公钥。之后把导出的文件移动到~/.ssh文件夹下，并重命名为id_ed25519_sk即可被ssh-agent自动加载。

到此配置完成，是不是非常简单。从此走向忘记密码的道路，enjoy it！

参考资料#

零信任内网远程访问:基于WireGuard部署私有网络远程接入，并实现远程访问内网设备

Sun, 24 May 2026 00:00:00 GMT

前言#

WireGuard是一种实现加密虚拟专用网络(VPN) 的通信协议和免费开源软件，其设计目标是易于使用、高速性能和低攻击面。它旨在比IPsec和OpenVPN这两种常见的隧道协议具有更好的性能和更强大的功能。

问题背景

家中服务器已经获取公网IPv6地址，并配置DDNS动态域名解析。受限于IPv6不兼容IPv4,导致部分服务无法远程访问。并且家庭内网直接暴露在公网环境上过于不安全。

解决方案

通过已经配置DDNS的域名连接WireGuard服务，建立VPN连接，在VPN内通过IPv4来访问服务。这样既解决了IPv6不兼容的问题，也避免了将家庭设备直接暴露到公网的危险。

服务器配置#

安装 WireGuard#

WireGuard是一个开源项目，在主流Linux系统上都可以通过包管理器进行安装

提示

目前WireGuard代码已经进入Linux主线内核（Linux 5.6+），所以部分主流Linux发行版只需要安装WireGuard-tool工具即可

Fedora/RHEL

Terminal window

1
sudo dnf install wireguard-tools

Debian/Ubuntu

Terminal window

1
sudo apt install wireguard

其他发行版 可以参考官方指南

编写配置文件#

在开始配置前，需要先完成公私钥的准备和服务器网段的规划

生成公私钥#

Terminal window

1
wg genkey | tee privatekey | wg pubkey > publickey

这将在当前目录下生成存有公钥和私钥的publickey和privatekey文件，可以通过cat来查看。

Terminal window

1
cat privatekey && cat privatekey

规划网段#

出于避免冲突和兼容性的考虑，VPN应当选择IPv4内网网段来配置。

为了避免和家庭网络中的ip冲突，故放弃使用192.168.0.0/16网段，选择使用10.10.0.0/24网段。

所以设置家庭服务器VPN内IP为10.10.0.1/32, 笔记本VPN内IP为10.10.0.2/32。

将规划写入配置文件#

在/etc/wireguard/wg0.conf下创建配置文件

Terminal window

1
sudo vim /etc/wireguard/wg0.conf

示例配置文件如下所示：

1
[Interface]
2
Address = 10.10.0.1/24
3
ListenPort = 51820
4
PrivateKey = XXX（填入刚刚生成的私钥）

参数说明

[Interface] 下为本机 WireGuard 网卡配置
- Address: WireGuard 虚拟网卡的 IP 地址
- ListenPort: 服务器监听端口
- PrivateKey:当前机器自己的私钥（填入刚刚生成的私钥）

运行服务#

使用 wg-quick 服务配置 WireGuard 服务器

Terminal window

1
systemctl enable --now wg-quick@wg0

验证#

使用wg查看服务状态来确认是否成功运行

Terminal window

1
sudo wg

配置防火墙#

在服务器放行WireGuard的udp端口

Terminal window

1
firewall-cmd --permanent --add-port=51820/udp --zone=public

拓展

可以将WireGuard网络加入trust区域，以此来实现在vpn内不受限制访问服务器所有端口。添加指令如下: sudo firewall-cmd —permanent —zone=trusted —add-interface=wg0

提示

到此WireGuard已经正常运行，如果没有远程访问内网其他设备的需求，可以直接跳转到客户端配置。

配置远程内网访问#

目前WireGuard只是做到可以访问在vpn内的设备，但如果我们想访问家庭网络内（192.168.xxx.xxx）中的其他设备，是无法建立连接的。这时我们就需要以家庭服务器为跳板，来帮我们转发发向192.168.xxx.xxx网段的网络包

开启内核转发并持久化#

首先要开启内核相关的配置

Terminal window

1
sudo sysctl -w net.ipv4.ip_forward=1

但上面的指令在重启后失效，我们需要进行持久化配置。

linux系统会按照文件名加载/etc/sysctl.d/目下的文件作为内核参数,所以要持久化内核参数需要在该目录下建立配置文件

Terminal window

1
sudo vim /etc/sysctl.d/99-wireguard.conf

关于文件名加载顺序

sysctl会按文件名前数字，从小到大进行加载。后加载的会覆盖先加载的参数，所以越靠后优先级越高，最大为99

在99-wireguard.conf文件里面填写如下内容来持久化开启内核转发

1
net.ipv4.ip_forward=1

开启地址伪装#

在开启内核转发后，我们发向内网网段的数据包已经可以被服务器中转到192.168.xxx.xxx网段了。但由于我们是从VPN内发的数据包，经家庭服务器转发到达内网。所以数据包的发送地址为我们在VPN内的地址。但我们VPN的IP在内网中是不能被除了家庭服务器外的设备访问到的，所以因为内网的设备无法回包导致无法访问。

sequenceDiagram participant Client as VPN客户端 10.10.0.2 participant Gateway as 家庭服务器 10.10.0.1 participant NAS as 内网设备 192.168.1.100 Client->>Gateway: 访问内网设备 Note over Client,Gateway: 源IP: 10.10.0.2 Gateway->>NAS: 转发请求 Note over Gateway,NAS: 源IP仍然是 10.10.0.2 NAS--xClient: 尝试直接回复 10.10.0.2 Note over NAS: 不在同一网段，无法回复。

而解决方法也很简单，让家庭服务器在转发数据包时把数据包源IP也一起修改，由自己进行路由。

sequenceDiagram participant Client as VPN客户端 10.10.0.2 participant Gateway as 家庭服务器 10.10.0.1 192.168.1.10 participant NAS as 内网设备 192.168.1.100 Client->>Gateway: 访问 NAS Note over Client,Gateway: 源IP: 10.10.0.2 Gateway->>NAS: SNAT / Masquerade Note over Gateway,NAS: 源IP伪装为 192.168.1.10 NAS->>Gateway: 回复 192.168.1.10 Gateway->>Client: 反向转换后返回 Note over Gateway,Client: 目标恢复为 10.10.0.2

而开启伪装的方法也很简单，只需要一行指令

Terminal window

1
iptables -t nat -A POSTROUTING -j MASQUERADE

但这里更推荐使用firewall来开启，可以更精确伪装的范围，并且持久化。

Terminal window

1
sudo firewall-cmd --permanent --add-masquerade

客户端配置#

下载客户端#

建议使用带有gui的客户端，便于使用。

Windows可以点击此处下载。

macOS上需要从App Store上下载，可自行注册美区账号后下载。

提示

Windows上exe格式安装程序会自动下载目前最新版本安装，如果上网环境不好建议下载msi格式。

添加客户端隧道配置#

打开WireGuard的GUI客户端，点击右下角加号选择新建空隧道。之后会自动生成公钥和私钥，并显示如下配置文件内容:

1
[Interface]
2
PrivateKey = xxxxx

之后根据之前的规划将配置文件补全

1
[Interface]
2
PrivateKey = xxxxx
3
Address = 10.0.0.2/32
4
MTU = 1420
5

6
[Peer]
7
PublicKey = xxx
8
AllowedIPs = 10.0.0.0/24, 192.168.1.0/24
9
Endpoint = 服务器IP:端口
10
PersistentKeepalive = 25

参数说明

[Interface] 下为本机 WireGuard 网卡配置
- PrivateKey:当前机器自己的私钥（使用自动生成的，不需要改动）
- Address: 客户端VPN内的 IP 地址
- MTU:最大传输单元
[Peer] 下为对端节点配置
- PublicKey: 对端节点的公钥（填入服务器公钥）
- AllowedIPs: 需要通过VPN访问的IP（填入的IP再被访问时会自动转发到VPN上）
- Endpoint: 接入点，填入之前配置的服务器地址和端口
- PersistentKeepalive: 发送心跳包的时间，用于在多层NAT环境下保活隧道连接

将客户端信息写入服务器配置文件#

在服务器WireGuard配置文件/etc/wireguard/wg0.conf中添加客户端信息

1
[Interface]
2
Address = 10.10.0.1/24
3
ListenPort = 51820
4
PrivateKey = XXX
5

6
#添加下面内容
7
[Peer]
8
PublicKey = XXX #填写刚刚客户端生成的公钥
9
AllowedIPs = 10.10.0.2/32 #填写为客户端规划的IP

保存后重启WireGuard服务

1
sudo wg-quick down wg0
2
sudo wg-quick up wg0

到此大功告成，点击客户端点击连接即可接入VPN