Latchwire
简体中文

开源 · 兼容 WireGuard®

让你的 VPN 密钥​无法被复制。

Latchwire 将你的 WireGuard 私钥保存在 YubiKey 内部。密钥在卡内生成，绝不离开卡片。协议和服务器都无需改变。没有卡，就没有隧道。

预发布版：面向 macOS 和 Linux 的命令行工具

在 GitHub 上查看 查看测试情况

工作原理

  1. 在 YubiKey 上生成密钥

    使用固件 5.7 或更高版本的 YubiKey 运行 keygen。密钥在卡内的 PIV 保留槽位（82–95）中生成，其他槽位保持不变。出厂设置的卡会先更换 PIN 和 PUK。

  2. 把公钥添加到服务器

    服务器看到的是一个普通的 WireGuard 对等端，因此无需插件或更新。Latchwire 面向 OPNsense、pfSense、Linux 和 MikroTik 等标准服务器设计。目前只在 Linux 容器中用测试服务器做过端到端测试。

  3. 输入 PIN 并连接

    PIN 直接发送给卡片，不会被保存。通常只需输入一次；系统休眠后或其他程序重置卡片后会再次询问。拔出卡片，隧道就会关闭。目标是两秒内完成；用模拟卡测试时约为一秒。

传统 WireGuard 与 Latchwire 对比

问题传统 WireGuardLatchwire
私钥在哪里？电脑上的一个文件里YubiKey 内部
能被复制吗？能，而且不留痕迹不能。密钥无法从卡中取出
笔记本被盗，卡不在身边？必须在每台服务器上更换密钥磁盘上的任何内容都无法完成握手
电脑上有恶意软件？它可以窃取密钥，日后继续使用卡插着时它可以使用隧道，但无法带走密钥
备份文件的副本第二把 YubiKey，作为第二个对等端添加到服务器
服务器端标准 WireGuard相同：标准 WireGuard
成熟度成熟，有官方客户端预发布版

硬件

目前代码中只有下方第一项。标签说明了每一项的状态。

YubiKey 5

v1

支持 X25519 的 PIV，固件 5.7 或更高版本。密钥在卡内生成，绝不离开卡片。目前的测试使用模拟卡，真实卡片的检查尚未完成。

OpenPGP 卡

即将支持

计划在 v1 之后紧接着支持。尚未实现。

PKCS#11 与 HSM

即将支持

计划在 v1 之后紧接着支持，面向支持 X25519 的设备。尚未实现。

TPM、Secure Enclave、FIDO2

远期规划

安全等级较低，不在 v1 范围内。密钥由硬件加密，但使用时会暴露在内存中，因此这些设备永远不会声称密钥无法被复制。

安全

这项声明针对的是密钥被取走，而不是密钥被使用。以下是它涵盖和不涵盖的范围。

可以防护

  • 从磁盘或备份中复制密钥：私钥从不写入这些位置
  • 笔记本被盗或被制作磁盘镜像，而卡不在其中
  • 包含私钥的配置文件：Latchwire 会拒绝它们
  • 并非在卡内生成的密钥：Latchwire 会拒绝它们
  • 开启断网保护（kill switch）时流量绕过隧道，具体限制见威胁模型

无法防护

  • 卡已插入且已输入 PIN 时，以你的身份运行的恶意软件：它可以使用卡和隧道，且无需触摸
  • 输入 PIN 后能够访问卡的其他程序；在某些系统上还包括其他本地用户
  • 已被攻破的 root 账户或内核
  • 笔记本连同卡和 PIN 一起被盗
  • 读取进程内存：会话密钥和一项缓存的秘密值位于内存中，也可能进入交换空间。它们不是私钥，没有卡也无法完成握手
  • 伪造的令牌：Latchwire 信任卡片报告的内容，目前还不验证证明（attestation）

须知

  • PIN 从不保存，但在你输入时会经过内存。
  • 绝不尝试默认 PIN。
  • 如果使用预共享密钥，它保存在磁盘上，不受硬件保护。
  • 威胁模型列出了每项防护对应的代码。如果两者不一致，以代码为准，说明文档有误。
阅读威胁模型 报告漏洞

项目状态

Latchwire 是预发布软件。以下是目前已有的内容和已检查的内容。

  • Linux 命令行与网络

    在特权容器中用软件密钥和测试服务器做过端到端测试。

    已测试

  • macOS 命令行与网络

    已实现。手动检查尚未完成。

    未验证

  • 真实 YubiKey 的行为

    自动测试使用模拟卡。真实卡片的检查尚未完成。

    未验证

  • Windows

    尚未实现。Windows 版本目前无法编译。

    未就绪

  • 桌面应用

    开发中。目前只有命令行工具。

    未就绪

  • 签名版本与软件包

    尚无发布版本，需要从源码构建。

    尚无

  • 独立安全审查

    尚未进行过独立审查。

    尚无

安装

从源码构建。目前还没有软件包或签名的二进制文件，此安装方式仅用于测试。

需要 Go 1.25 或更高版本，以及固件 5.7 或更高版本的 YubiKey 5。在 Linux 上构建时还需要 C 编译器和 libpcsclite-dev，运行时需要 pcscd。

构建

git clone https://github.com/Kodviva/latchwire
cd latchwire
go build -o latchwire ./cmd/latchwire
sudo install -o root -m 0755 latchwire /usr/local/bin/latchwire

分别在各自的终端中启动守护进程和代理

sudo latchwire daemon
latchwire agent

生成密钥并连接

latchwire devices
latchwire keygen --serial <serial> --address <tunnel-ip>
sudo latchwire add office office.conf
latchwire up office

keygen 会输出一个用于服务器的 [Peer] 块。隧道文件是普通的 WireGuard 文件，用 KeyRef 和 PublicKey 代替 PrivateKey。

计划提供 Homebrew、.deb、.rpm 和 Microsoft Store 软件包，但目前都还没有。

作为服务运行 硬件测试清单

路线图

  1. 核心已实现

    面向 macOS 和 Linux 的命令行客户端

  2. 完整网络功能已实现

    全局隧道、DNS、断网保护、按需连接和允许用户。已在 Linux 上测试；macOS 待检查

  3. 真实硬件检查待完成

    按公开清单检查真实 YubiKey 和 macOS 网络

  4. Windows进行中

    服务、网络层和断网保护

  5. 桌面应用与翻译进行中

    面向 macOS、Windows 和 Linux 的桌面应用

  6. 签名版本计划中

    Homebrew、直接下载、.deb、.rpm、Microsoft Store