概述

wfb_keygen 是 WFB-ng 的密钥对生成工具，用于生成通信双方所需的加密密钥文件。WFB-ng 使用 libsodium 库提供的 crypto_box（X25519-XSalsa20-Poly1305）进行端到端加密和认证，确保无线传输数据的机密性和完整性。

该工具一次性生成两对非对称密钥：无人机端（drone）和地面站端（ground station），并将它们交叉组合成两个密钥文件。

使用方式

1
wfb_keygen [password]

参数详解

参数 说明
password （可选）密码字符串。如果提供，则使用该密码通过 Argon2i 派生密钥种子，生成确定性（可重复）的密钥对。如果不提供，则从系统的随机数源（/dev/random 或 /dev/urandom）生成完全随机的密钥对。

无其他命令行参数。输入超过一个参数时会显示用法提示并退出。

输出文件

运行后在当前工作目录生成两个密钥文件：

drone.key

  • 用途：放置在无人机端（发送端），供 wfb_tx 使用
  • 内容结构：drone 私钥（32字节） + ground station 公钥（32字节） = 共 64 字节
  • 说明：包含无人机自己的私钥和地面站的公钥，用于加密发送的数据并验证接收的数据

gs.key

  • 用途：放置在地面站端（接收端），供 wfb_rx 使用
  • 内容结构：ground station 私钥（32字节） + drone 公钥（32字节） = 共 64 字节
  • 说明：包含地面站的私钥和无人机的公钥，用于解密接收的数据并验证发送方的身份

密钥派生机制

随机模式（无密码参数）

1
系统熵源 (/dev/random) --> libsodium crypto_box_keypair() --> 生成 drone 和 gs 的公私钥对
  • 使用系统的加密安全随机数生成器
  • 每次运行产生不同的密钥对
  • 启动前会检查 /dev/random 的熵池是否 >= 160 bits，不足时会等待
  • 在虚拟化环境中可能需要安装 rng-tools、jitterentropy 或 haveged 来加速熵收集

密码派生模式（提供密码参数）

1
2
3
password + salt("wifibroadcastkey") --> Argon2i (interactive) --> seed (64字节)
seed[0:32] --> crypto_box_seed_keypair() --> drone 公私钥对
seed[32:64] --> crypto_box_seed_keypair() --> gs 公私钥对
  • 使用固定的 salt：wifibroadcastkey（16字节）
  • 哈希算法：Argon2i（libsodium 的 crypto_pwhash_ALG_ARGON2I13）
  • 操作限制：OPSLIMIT_INTERACTIVE（低 CPU 消耗）
  • 内存限制：MEMLIMIT_INTERACTIVE（约 64MB RAM）
  • 相同密码总是生成相同的密钥对，便于备份和恢复

典型使用场景

1. 随机密钥生成（推荐用于生产环境）

1
2
3
4
5
6
7
8
# 在当前目录生成 drone.key 和 gs.key
wfb_keygen

# 将 drone.key 复制到无人机端
scp drone.key user@drone:/etc/

# 将 gs.key 保留在地面站端
sudo cp gs.key /etc/

2. 密码派生密钥（便于备份和恢复）

1
2
3
4
5
# 使用密码生成可重复的密钥对
wfb_keygen "my-secret-password"

# 在任何机器上重新执行相同命令即可得到相同的密钥对
# 只需记住密码，无需保存密钥文件

3. 开发环境快速设置

1
2
3
# Makefile 中自动调用（如果 gs.key 不存在）
make
# 内部执行: ./wfb_keygen (如果 gs.key 不存在)

安全注意事项

  1. 保护私钥：密钥文件包含私钥，应设置为仅 root 可读的权限（chmod 600）
  2. 定期轮换：建议定期重新生成密钥对以增强安全性
  3. 密码强度：使用密码派生模式时，务必使用足够强的密码（至少 16 个字符，包含大小写字母、数字和特殊字符）
  4. 不要共享密钥文件：drone.key 只应存在于无人机端，gs.key 只应存在于地面站端

加密协议说明

WFB-ng 使用两层加密架构：

第一层：会话密钥交换（crypto_box）

  • 算法：X25519（密钥交换）+ XSalsa20-Poly1305（加密认证）
  • 用途：安全地传输临时的会话密钥
  • 每个会话只发送一次 session packet

第二层：数据流加密（crypto_aead_chacha20poly1305）

  • 算法：ChaCha20-Poly1305 AEAD
  • 用途：加密实际的数据载荷
  • 使用第一层安全传输的会话密钥进行加解密
  • 每个数据包都有独立的 nonce（block_idx << 8 | fragment_idx）

依赖库

  • libsodium（>= 1.0.16，提供 crypto_box、crypto_aead_chacha20poly1305、crypto_pwhash_argon2i）