测试流程首页

# 第 0 步：手动生成本轮密钥（你自己跑 gen-keys，生成一次）
target/release/sign-tool gen-keys
# 记下：云端种子、云端公钥、设备 A 解密私钥、设备 A 加密公钥
# 再跑一次 gen-keys，只取其中的设备对作设备 B（另一台设备）
target/release/sign-tool gen-keys
# 记下：设备 B 私钥、设备 B 公钥

# 版本号只在这里填一次，造 bin 时填进版本块；pack 从 bin 块读，不用再传；
# 预期输出里的 1.2.3 就是 VERSION 的值
VERSION=1.2.3

# 造带格式 2 版本块的测试固件（4324 字节，版本块在 0x1000，型号 stm32h743vi、固件名 gateway、版本取 $VERSION、构建日期与构建时间取当前 UTC 时间）
python3 - "$VERSION" <<'EOF'
import os, struct, sys
from datetime import datetime, timezone
major, minor, patch = (int(x) for x in sys.argv[1].split('.'))
now = datetime.now(timezone.utc)
body = bytearray(os.urandom(0x1000 + 228))
blk = bytearray(228)
blk[0:4] = b'FWVR'
blk[4] = 2
blk[5:5+11] = b'stm32h743vi'
blk[105:105+7] = b'gateway'
struct.pack_into('<HHH', blk, 205, major, minor, patch)
blk[211:219] = now.strftime('%Y%m%d').encode()
blk[219:225] = now.strftime('%H%M%S').encode()
body[0x1000:0x1000+228] = blk
open('test-fw.bin', 'wb').write(body)
EOF

# 打包：签名 + 加密一次，出共用包；pack 只传 --sign-key，不传设备密钥（传 --encrypt-key 直接拒绝，见 T1-5）
# 包名永远从块信息生成（版本从 bin 版本块读，块里就是上面的 $VERSION；包落在输入 bin 旁边）
target/release/sign-tool pack --bin test-fw.bin \
  --sign-key <签名私钥种子>
# 生成的包名记下来，后面各步都用它（日期与时间是造 bin 的当时 UTC 日期／时间）
PKG=$(ls gateway-stm32h743vit6-release-v*.pkg)
# pack 输出三行：packed 4324 bytes of firmware (v1.2.3, model stm32h743vi, firmware gateway) into 4652 bytes: <包名>
#   header 312 bytes + body 4340 bytes (ciphertext + 16-byte tag)，即包头 312 ＋固件 4324 ＋标签 16
#   package key (keep secret; wrap it per device with wrap-key): <64 位十六进制包密钥>
# 注意括号里打印的型号是块里的家族前缀 stm32h743vi，文件名里拼的是完整订货型号 stm32h743vit6，两者是同一颗芯片

# 给设备 A 包包密钥：包密钥包 80 字节（临时公钥 32 ＋包装后包密钥 48），--out 必填（包密钥包没有可推导名）
target/release/sign-tool wrap-key --package-key <包密钥> \
  --encrypt-key <设备加密公钥A> --out keypkg-a.bin
# 应打印 wrapped package key (80 bytes) written to keypkg-a.bin

# 解包：先解包密钥、再解密、再验签，全过才写出明文（默认输出为包头生成名加 -out.bin，即 ${PKG%.pkg}-out.bin，在包旁边）
target/release/sign-tool unpack --pkg "$PKG" \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应打印 unpacked OK: firmware v1.2.3 (4324 bytes) written to gateway-stm32h743vit6-release-v1.2.3-<造 bin 的当时 UTC 日期>-<当时 UTC 时间>-out.bin
# sign-tool cmp：逐字节比对原固件与解包明文是否一致；一致打印
# PASS: identical（字节数）并退出 0，不一致报第一个不同字节并退出 1。内建命令，
# 不依赖系统 cmp，Windows 上也一样跑。
target/release/sign-tool cmp test-fw.bin "${PKG%.pkg}-out.bin"
# 应打印 PASS: identical (4324 bytes)

# 包头区（第 200 字节落在固件名字段）：身份校验先挂
python3 -c "
d = bytearray(open('$PKG','rb').read()); d[200] ^= 0xFF; open('test-fw-bad.pkg','wb').write(d)"
target/release/sign-tool verify --pkg test-fw-bad.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 先清掉 T1-1 的解包输出，避免旧文件干扰“不生成”的判断
rm -f "${PKG%.pkg}-out.bin"
target/release/sign-tool unpack --pkg test-fw-bad.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 预期：退出码均为 1，报错 error: firmware name has non-NUL bytes after the terminator，且不生成 ${PKG%.pkg}-out.bin
# 包体区（第 1000 字节在包体）：解密校验挂
python3 -c "
d = bytearray(open('$PKG','rb').read()); d[1000] ^= 0xFF; open('test-fw-bad2.pkg','wb').write(d)"
target/release/sign-tool verify --pkg test-fw-bad2.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
target/release/sign-tool unpack --pkg test-fw-bad2.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 预期：退出码均为 1，报错 error: body decryption failed: body tampered, or wrong package key，且不生成 ${PKG%.pkg}-out.bin

# 用一份拷贝测包名生成，避免覆盖原固件；注意 t15.bin 与 test-fw.bin 是同一块（同一构建日期／时间），
# 所以包名与 T1-1 的相同、会覆盖同名包文件（每包包密钥现生，包字节不同，但解包明文相同，属正常现象）
cp test-fw.bin t15.bin
target/release/sign-tool pack --bin t15.bin \
  --sign-key <签名私钥种子>
# 应生成 gateway-stm32h743vit6-release-v1.2.3-<造 bin 的当时 UTC 日期>-<当时 UTC 时间>.pkg（在 t15.bin 旁边），不是 t15.pkg
# 默认输出为包头生成名加 -out.bin（在包旁边），即 ${PKG15%.pkg}-out.bin
PKG15=$(ls gateway-stm32h743vit6-release-v*.pkg)
target/release/sign-tool unpack --pkg "$PKG15" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应生成 ${PKG15%.pkg}-out.bin，且与 test-fw.bin 逐字节一致
target/release/sign-tool cmp test-fw.bin "${PKG15%.pkg}-out.bin"
# verify 只给结论，不写文件
target/release/sign-tool verify --pkg "$PKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应打印 verified OK: firmware v1.2.3 (4324 bytes)，不生成任何文件
# pack 传设备密钥直接拒绝（不是静默忽略）
target/release/sign-tool pack --bin test-fw.bin \
  --sign-key <签名私钥种子> --encrypt-key <设备加密公钥A>
# 应退出码 1，报错 pack takes no --encrypt-key: pack produces a shared package for all devices; wrap its package key per device with wrap-key
# pack 传 --out 同样拒绝（包名永远从块生成）
target/release/sign-tool pack --bin test-fw.bin \
  --sign-key <签名私钥种子> --out custom.pkg
# 应退出码 1，报错 pack takes no --out: the package filename always comes from the firmware version block
# verify 传 --out 同样拒绝（verify 不写文件）
target/release/sign-tool verify --pkg "$PKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin --out custom.bin
# 应退出码 1，报错 verify writes no file; use unpack to write the decrypted firmware
# unpack 传 --out 与 --expect 同样拒绝（输出名永远从包头生成；比对用 cmp）
target/release/sign-tool unpack --pkg "$PKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin --out custom.bin
# 应退出码 1，报错 unpack takes no --out: the output filename always comes from the package header

# bin 信息：型号、固件名、版本、构建日期、构建时间来自版本块（日期与时间是造 bin 时写进块里的 UTC 日期／时间，YYYYMMDD／HHMMSS）
target/release/sign-tool info --bin test-fw.bin
# 应打印：size: 4324 bytes、model: stm32h743vi、firmware name: gateway、version: v1.2.3、
# version block: offset 0x1000 (228 bytes)、build date: 造 bin 的当时 UTC 日期、build time: 造 bin 的当时 UTC 时间
# pkg 信息（不用密钥）：型号、固件名、版本、构建日期、构建时间、长度、标志都来自 v3 包头，不用解密
target/release/sign-tool info --pkg "$PKG"
# 应打印：format: GWPK v3、model: stm32h743vi、firmware name: gateway、firmware version: v1.2.3、
# build date / build time（造 bin 的当时 UTC 日期／时间）、firmware length: 4324 bytes、
# flags: 0x3 (encrypted, signed)、header: 312 bytes、body: 4340 bytes (ciphertext + 16-byte tag)、total: 4652 bytes
# pkg 信息（给齐三个密钥参数）：解密后读内嵌版本块，型号、固件名、版本应与包头一致
target/release/sign-tool info --pkg "$PKG" \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应在上面各项后追加 embedded firmware version block 一节：model / firmware name / version 三项带 (matches header)，
# build date / build time 与包头相同（不带 matches header 字样）

# 8a 文件过短（100 字节，够读魔数与格式、但不够一个包头）：跑完跑一次 verify（下面模板块里那条），预期 package too short: 100 bytes, v3 header alone is 312 bytes
head -c 100 "$PKG" > test-fw-t8.pkg
# 8b 空文件（不够 8 字节，连格式都读不出）：同上，预期 package too short: 0 bytes, header alone is 312 bytes
: > test-fw-t8.pkg

# 篡改模板：<改动> 由下表给出
python3 -c "import struct; d = bytearray(open('$PKG','rb').read()); <改动>; open('test-fw-t8.pkg','wb').write(d)"
target/release/sign-tool verify --pkg test-fw-t8.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin

# 篡改模板：<改动> 由下表给出
python3 -c "import struct; d = bytearray(open('$PKG','rb').read()); <改动>; open('test-fw-t9.pkg','wb').write(d)"
target/release/sign-tool verify --pkg test-fw-t9.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin

# 9j 错云端公钥：不改包，verify 传第二次 gen-keys 的云端公钥
target/release/sign-tool verify --pkg "$PKG" \
  --verify-key <第二次 gen-keys 的云端公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应退出码 1，报错 signature verification failed: wrong verify key, or header/firmware tampered
# 9k 包体截断：不套模板
head -c 1000 "$PKG" > test-fw-t9.pkg
target/release/sign-tool verify --pkg test-fw-t9.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应退出码 1，报错 body length mismatch: body is 688 bytes, expected plaintext 4324 + tag 16
# 9l 包体后追加：不套模板，整条 python 命令直接跑
python3 -c "open('test-fw-t9.pkg','wb').write(open('$PKG','rb').read() + __import__('os').urandom(16))"
target/release/sign-tool verify --pkg test-fw-t9.pkg \
  --verify-key <签名公钥> \
  --decrypt-key <解密私钥A> \
  --key-package keypkg-a.bin
# 应退出码 1，报错 body length mismatch: body is 4356 bytes, expected plaintext 4324 + tag 16

# 10a：bin 无版本块（全零 bin 不可能撞上 FWVR）
head -c 4324 /dev/zero > noblock.bin
target/release/sign-tool pack --bin noblock.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 firmware has no version block at bin offset 0x1000: build firmware with the version block，不生成包
# 10b：版本块格式不是 2
python3 -c "d = bytearray(open('test-fw.bin','rb').read()); d[0x1004] = 1; open('badfmt.bin','wb').write(d)"
target/release/sign-tool pack --bin badfmt.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 unsupported version block format: 1 (expected 2)，不生成包
# 10c：版本块截断（只有魔数与格式，缺后半段）
head -c 4196 test-fw.bin > shortblk.bin
target/release/sign-tool pack --bin shortblk.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 version block truncated: 4196 bytes, need 4324 bytes，不生成包
# 10d：只有魔数、缺格式字节
head -c 4100 test-fw.bin > magicblk.bin
target/release/sign-tool pack --bin magicblk.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 version block truncated: magic present but format byte missing，不生成包
# 10e：版本块保留字节非零
python3 -c "d = bytearray(open('test-fw.bin','rb').read()); d[0x10E1] = 1; open('resvblk.bin','wb').write(d)"
target/release/sign-tool pack --bin resvblk.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 version block reserved bytes must be zero，不生成包
# 10f：版本块固件名填充坏（走 pack 路径，文案与 T1-2 相同）
python3 -c "d = bytearray(open('test-fw.bin','rb').read()); d[0x1000+150] ^= 0xFF; open('badnameblk.bin','wb').write(d)"
target/release/sign-tool pack --bin badnameblk.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 firmware name has non-NUL bytes after the terminator，不生成包
# 10g：版本块日期月份越界（走 pack 路径）
python3 -c "d = bytearray(open('test-fw.bin','rb').read()); d[0x10D7:0x10D9] = b'13'; open('badmonblk.bin','wb').write(d)"
target/release/sign-tool pack --bin badmonblk.bin \
  --sign-key <签名私钥种子>
# 应退出码 1，报错 build date month out of range: 13，不生成包
# 10h：info --bin 无版本块（文案比 pack 的短）
target/release/sign-tool info --bin noblock.bin
# 应退出码 1，报错 firmware has no version block at bin offset 0x1000
# 10i：info --pkg 只给一个密钥（三个密钥参数必须齐全或全不给）
target/release/sign-tool info --pkg "$PKG" --verify-key <签名公钥>
# 应退出码 1，报错 info --pkg needs --verify-key, --decrypt-key, and --key-package together to decrypt
# 10j：info 既不给 --bin 也不给 --pkg（两者都给同样报错）
target/release/sign-tool info
# 应退出码 1，报错 info takes exactly one of --bin <bin> or --pkg <pkg>

# 11a：缺必需参数（缺 --decrypt-key）
target/release/sign-tool verify --pkg "$PKG" --verify-key <签名公钥> --key-package keypkg-a.bin
# 应退出码 1，报错 missing required flag --decrypt-key
# 11a2：缺 --key-package
target/release/sign-tool verify --pkg "$PKG" --verify-key <签名公钥> --decrypt-key <解密私钥A>
# 应退出码 1，报错 missing required flag --key-package
# 11b：参数无值（下一个 token 又是参数）
target/release/sign-tool verify --pkg --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 missing value for --pkg
# 11c：裸参数（不是 --flag 形式）
target/release/sign-tool verify foo --pkg "$PKG" --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 unexpected argument 'foo': expected --flag value
# 11d：重复参数
target/release/sign-tool verify --pkg "$PKG" --pkg "$PKG" --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 duplicate flag --pkg
# 11e：未知短参数
target/release/sign-tool verify -x --pkg "$PKG" --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 unexpected argument '-x': expected --flag value
# 11f：未知子命令（裸跑 sign-tool 同样报错）
target/release/sign-tool frobnicate
# 应退出码 1，报错 missing or unknown subcommand
# 11g：密钥非十六进制
target/release/sign-tool verify --pkg "$PKG" --verify-key zz --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 bad hex string 'zz': expected 64 hex characters
# 11h：密钥长度不对（62 位十六进制＝31 字节）
target/release/sign-tool verify --pkg "$PKG" --verify-key aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 bad key length: 31 bytes, expected 32 bytes (64 hex characters)
# 11i：验证公钥无法解析（y=2 没有对应曲线点；包用好包、解密私钥用设备 A 的）
target/release/sign-tool verify --pkg "$PKG" --verify-key 0200000000000000000000000000000000000000000000000000000000000000 --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 invalid verify key
# 注意：全 f 的 32 字节能解析（y 取模后是 18，有对应点），不触发本条，错钥匙时报 signature verification failed
# 11j：文件不存在（三处同 pattern，后缀是系统文案）
target/release/sign-tool verify --pkg 不存在.pkg --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-a.bin
# 应退出码 1，报错 cannot read package file '不存在.pkg': No such file or directory (os error 2)
target/release/sign-tool pack --bin 不存在.bin --sign-key <签名私钥种子>
# 应退出码 1，报错 cannot read firmware file '不存在.bin': No such file or directory (os error 2)
target/release/sign-tool cmp 不存在1 不存在2
# 应退出码 1，报错 cannot read file '不存在1': No such file or directory (os error 2)
# 11k：cmp 参数个数不对（一个或三个都一样报错）
target/release/sign-tool cmp test-fw.bin
# 应退出码 1，报错 cmp takes exactly two file arguments: sign-tool cmp <file1> <file2>
# 11l：cmp 长度不同（other.bin 是 256 字节随机文件）
head -c 256 /dev/urandom > other.bin
target/release/sign-tool cmp test-fw.bin other.bin
# 应退出码 1，报错 files differ in length: 4324 vs 256 bytes
# 11m：cmp 同长首个不同字节（位置从 1 数；hex 值随随机固件而变，只认位置）
cp test-fw.bin same.bin
python3 -c "d = bytearray(open('same.bin','rb').read()); d[100] ^= 0xFF; open('same.bin','wb').write(d)"
target/release/sign-tool cmp test-fw.bin same.bin
# 应退出码 1，报错 files differ: byte 101: 0x.. vs 0x..（101 是改动位置 100 从 1 数）
# 11n：derive-pub 坏 kind（--input 须给合法 64 位十六进制，否则先报密钥错）
target/release/sign-tool derive-pub --kind foo --input <64 位十六进制>
# 应退出码 1，报错 unknown --kind 'foo': expected ed25519 or x25519
# 11o：derive-pub 缺 --input
target/release/sign-tool derive-pub --kind ed25519
# 应退出码 1，报错 missing required flag --input
# 11p：cmp 第二个文件不存在（第一个存在，走到第二个读文件分支）
target/release/sign-tool cmp test-fw.bin 不存在2
# 应退出码 1，报错 cannot read file '不存在2': No such file or directory (os error 2)

# 12a：1MB 固件往返（先造一个带版本块的 big-fw.bin，构建时间取当前 UTC，与 test-fw.bin 不同，包名不撞；再追加随机字节到 1048576）
python3 - "1.2.3" <<'EOF'
import os, struct, sys
from datetime import datetime, timezone
major, minor, patch = (int(x) for x in sys.argv[1].split('.'))
now = datetime.now(timezone.utc)
body = bytearray(os.urandom(0x1000 + 228))
blk = bytearray(228)
blk[0:4] = b'FWVR'
blk[4] = 2
blk[5:5+11] = b'stm32h743vi'
blk[105:105+7] = b'gateway'
struct.pack_into('<HHH', blk, 205, major, minor, patch)
blk[211:219] = now.strftime('%Y%m%d').encode()
blk[219:225] = now.strftime('%H%M%S').encode()
body[0x1000:0x1000+228] = blk
open('big-fw.bin', 'wb').write(body)
EOF
python3 -c "open('big-fw.bin','ab').write(__import__('os').urandom(1048576-4324))"
target/release/sign-tool pack --bin big-fw.bin \
  --sign-key <签名私钥种子>
# 应生成 gateway-stm32h743vit6-release-v1.2.3-<big-fw 构建日期>-<big-fw 构建时间>.pkg，输出 packed 1048576 bytes of firmware (v1.2.3, model stm32h743vi, firmware gateway) into 1048904 bytes
# header 312 bytes + body 1048592 bytes (ciphertext + 16-byte tag)，外加 package key 一行
BIGPKG=$(ls -t gateway-stm32h743vit6-release-v1.2.3-*.pkg | head -1)
# 给设备 A 包 big 包的包密钥（pack 输出的 package key 行，记下来填进占位符）
target/release/sign-tool wrap-key --package-key <big 包的包密钥> \
  --encrypt-key <设备加密公钥A> --out keypkg-big-a.bin
target/release/sign-tool verify --pkg "$BIGPKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-big-a.bin
# 应打印 verified OK: firmware v1.2.3 (1048576 bytes)
target/release/sign-tool unpack --pkg "$BIGPKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-big-a.bin
target/release/sign-tool cmp big-fw.bin "${BIGPKG%.pkg}-out.bin"
# 应打印 PASS: identical (1048576 bytes)
# 12b：gen-keys 输出形状（值每次随机，只认形状）
target/release/sign-tool gen-keys
# 应打印 1 行表头 === TEST KEYS - 测试密钥，切勿用于量产 ===，再加 4 行：sign key (seed, private key)、verify key (public key)、decrypt key (private key)、encrypt key (public key)，每行值 64 位十六进制（private key 是私钥、public key 是公钥）

# 13a：缺 --out（包密钥包没有可推导名，--out 必填）
target/release/sign-tool wrap-key --package-key <包密钥> --encrypt-key <设备加密公钥A>
# 应退出码 1，报错 missing required flag --out
# 13b：包密钥长度不对（62 位十六进制＝31 字节）
target/release/sign-tool wrap-key --package-key aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa --encrypt-key <设备加密公钥A> --out keypkg-bad.bin
# 应退出码 1，报错 bad key length: 31 bytes, expected 32 bytes (64 hex characters)
# 13c：同一包密钥包两次，结果不同、但都解出同一包密钥（临时密钥对每次现生，包装密钥永不重复）
target/release/sign-tool wrap-key --package-key <包密钥> --encrypt-key <设备加密公钥A> --out keypkg-a2.bin
# keypkg-a2.bin 与 keypkg-a.bin 字节不同（临时公钥不同）
target/release/sign-tool cmp keypkg-a.bin keypkg-a2.bin
# 应退出码 1（两文件不同，属正常现象，不是不通过）
target/release/sign-tool verify --pkg "$PKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥A> \
  --key-package keypkg-a2.bin
# 应打印 verified OK: firmware v1.2.3 (4324 bytes)（第二个包密钥包同样解出同一包密钥）
# 13d：给设备 B 包同一包密钥，设备 B 也能解（同一共用包、不同包密钥包）
target/release/sign-tool wrap-key --package-key <包密钥> --encrypt-key <设备加密公钥B> --out keypkg-b.bin
target/release/sign-tool verify --pkg "$PKG" \
  --verify-key <签名公钥> --decrypt-key <解密私钥B> \
  --key-package keypkg-b.bin
# 应打印 verified OK: firmware v1.2.3 (4324 bytes)

# 1. 登录拿会话（表单字段 password），再建凭证（只显示一次 secret，记下来）
curl -c jar -b jar -X POST -d 'password=<管理员密码>' http://127.0.0.1:3009/login
curl -b jar -X POST -H 'Content-Type: application/json' -d '{"name":"srvtest"}' \
  http://127.0.0.1:3009/api-keys
# 应返回 {"key_id":"gwk_...","secret":"..."}；再查列表应只见 key、不见 secret

# 2. 机器调 /pack：multipart bin + product + remark（不带 device_pub），带 4 个签名头
TS=$(date +%s)
NONCE=$(python3 -c "import os; print(os.urandom(16).hex())")
SIG=$(python3 - "$TS" "$NONCE" <<'PY'
import sys, hashlib, hmac
ts, nonce = sys.argv[1:3]
fw = open('test-fw.bin','rb').read()
canon = '\n'.join(['POST','/pack',ts,nonce,hashlib.sha256(fw).hexdigest(),
  'gateway','srvtest'])
print(hmac.new('<secret>'.encode(), canon.encode(), hashlib.sha256).hexdigest())
PY
)
curl -o srv.pkg -X POST \
  -H "X-Gwpack-Key: <key>" -H "X-Gwpack-Timestamp: $TS" \
  -H "X-Gwpack-Nonce: $NONCE" -H "X-Gwpack-Signature: $SIG" \
  -F "bin=@test-fw.bin" \
  -F "product=gateway" -F "remark=srvtest" \
  http://127.0.0.1:3009/pack
# 应直接返回包文件（attachment），大小 4652 字节（312 头＋4324 固件＋16 标签）
# 验包与解包：先按 4.4 节给测试设备分发并取包密钥包（keypkg-srv.bin），再验
target/release/sign-tool verify --pkg srv.pkg --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-srv.bin
target/release/sign-tool unpack --pkg srv.pkg --verify-key <签名公钥> --decrypt-key <解密私钥A> --key-package keypkg-srv.bin
# 应通过，写出包头生成名加 -out.bin（在 srv.pkg 旁边）
target/release/sign-tool cmp "$(ls -t gateway-*-out.bin | head -1)" test-fw.bin
# 应打印 PASS: identical (4324 bytes)
# 两条都应通过，解出的明文与上传的 bin 一致

# 3. 负向：签名改一位应 401；未登录打开管理页应跳登录页

# 1. 管理员建操作员（管理员会话），再用操作员账号登录（操作员会话 Cookie，HttpOnly，12 小时）
curl -b jar -X POST -H 'Content-Type: application/json' -d '{"username":"<操作员>","password":"<操作员密码>"}' \
  http://127.0.0.1:3009/operators
curl -c ojar -b ojar -X POST -H 'Content-Type: application/json' -d '{"username":"<操作员>","password":"<操作员密码>"}' \
  http://127.0.0.1:3009/operator/login
# 错用户名或错密码一律 401 invalid username or password（不区分是哪项错）

# 2. 管理员批量领号（管理员会话，数量 1-1000；序列号 GW{YYYYMMDD}{序号:04}，按天计数、不重复）
curl -b jar -X POST -H 'Content-Type: application/json' -d '{"count":3}' \
  http://127.0.0.1:3009/devices/allocate
# 应返回 {"serials":["GW<日期>0001","GW<日期>0002","GW<日期>0003"]}；数量超限 400 bad count: use 1-1000

# 3. 操作员分发（操作员会话）：序列号须在已领出批次里，否则 400 serial not allocated
curl -b ojar -X POST -H 'Content-Type: application/json' -d '{"serial":"<序列号>","model":"stm32h743vi"}' \
  http://127.0.0.1:3009/devices/issue
# 应返回 {"serial","model","device_pub","device_priv","issued_at","issued_by"}；私钥只在这次响应里给，记下来给写入工具用
# 重发不带 reissue：400 serial already issued: pass reissue=true to re-deliver stored keys
# 重发带 reissue=true：返回存量密钥，不轮换（同一对密钥原样返回）
# 没分发过就带 reissue=true：400 serial not issued: issue without reissue first
# 已用写入工具上报登记过的序列号（无后台存钥）再分发：400 serial already registered
# 已分发过的序列号用写入工具上报登记：400 serial already registered（分发即登记，不重复登记）

# 4. 取包密钥包（会话或机器凭证）：版本＋序列号，返回 80 字节包密钥包原值（不是 JSON）
curl -b ojar "http://127.0.0.1:3009/key-package?version=<版本>&serial=<序列号>" -o keypkg-srv.bin
# 未登记的序列号 404 no such device；无该版本的共用包 404 no such firmware
# 包密钥记录区：列表只给元数据（版本、指纹 SHA-256、创建时间、状态）；点眼睛单独取原值（仅管理员会话），30 秒自动隐藏并清状态

# 5. 禁用操作员（管理员会话，幂等；禁用后该操作员会话失效；本版无恢复接口）
curl -b jar -X POST http://127.0.0.1:3009/operators/<操作员>/disable
# 禁用后用原操作员会话调 /devices/issue 应 401

# 1. 单个推送（管理员会话）：版本不传取该型号最新共用包；总是发送（即使设备已是目标版本）
curl -b jar -X POST http://127.0.0.1:3009/devices/<序列号>/push
# 应返回 {"cmd_id","topic","pkg_url"}（不含 key_package 本身）；订阅者应在 v1/tenants/default/devices/<序列号>/cmd 收到
# firmware_update（QoS 1）：{"cmd_id","action":"firmware_update","params":{"version","pkg_url","key_package"}}
# 其中 key_package 是 80 字节包密钥包的 160 位十六进制；cmd_id 与设备回执配对用
# 未配 MQTT 时 503（fail-closed）；未配公开地址时 500 push requires SIGN_SERVER_PUBLIC_BASE_URL to be configured；
# 未登记的序列号 404 no such device；未指定版本且该型号无共用包 404 no firmware for this model

# 2. 批量推送（管理员会话）：筛选 version / model（精确）/ online / only_outdated 全部可选；单次上限 500 台
curl -b jar -X POST -H 'Content-Type: application/json' -d '{"model":"stm32h743vi","only_outdated":true}' \
  http://127.0.0.1:3009/devices/push-batch
# 应返回每台结果 pushed / failed / skipped（only_outdated 跳过已是目标版本的台，记 skipped 不是失败）；
# 一台失败不中断整批；超 500 台 400 batch too large: <匹配数> devices match, narrow filters (max 500)；空批量返回空结果，不报错

# 3. 状态接入：服务端订阅 v1/tenants/+/devices/+/status（QoS 1，每次连接重订阅）；
# 设备（或测试订阅者）向 v1/tenants/default/devices/<序列号>/status 发 {"device_id":"<序列号>","online":true,"version":"<版本>"}
# 设备列表里该台的 online 与当前版本应随之更新；未登记的序列号忽略；device_id 与话题不一致跳过；格式错只记日志、不写库

# 编译
cargo build --release --workspace

# 手动生成密钥（测试前自己跑）
sign-tool gen-keys

# 命令行
sign-tool derive-pub --kind ed25519|x25519 --input <hex 32 字节>
sign-tool pack --bin <bin> --sign-key <hex>
sign-tool wrap-key --package-key <hex> --encrypt-key <hex> --out <key-package-file>
sign-tool verify --pkg <pkg> --verify-key <hex> --decrypt-key <hex> --key-package <key-package-file>
sign-tool unpack --pkg <pkg> --verify-key <hex> --decrypt-key <hex> --key-package <key-package-file>
sign-tool cmp <file1> <file2>
sign-tool info --bin <bin>
sign-tool info --pkg <pkg> [--verify-key <hex> --decrypt-key <hex> --key-package <key-package-file>]

# 单测
cargo test -p sign-tool
cargo test --workspace

# 设备验证（gateway 仓 bootloader 目录）
cargo test

int configure(
    const char *base_url,
    const char *api_key,
    const char *api_secret);

int pack(
    const unsigned char *firmware, size_t firmware_len,
    const char *product,
    const char *remark,
    unsigned char *out, size_t *out_len);

int last_filename(char *buf, size_t buf_len);

int last_error(char *buf, size_t buf_len);

const char *lib_version(void);

int configure(String baseUrl, String apiKey, String apiSecret);
int pack(byte[] firmware, long firmwareLen,
        String product, String remark, byte[] out, LongByReference outLen);
int last_filename(byte[] buf, long bufLen);
int last_error(byte[] buf, long bufLen);
String lib_version();

static byte[] servicePack(Gwpack lib, byte[] firmware, String product, String remark);
static String serviceLastFilename(Gwpack lib);
static String lastError(Gwpack lib);

import com.sun.jna.Native;
import java.nio.file.Files;
import java.nio.file.Path;

public class GwpackExample {

    public static void main(String[] args) throws Exception {
        if (args.length != 4) {
            System.err.println("usage: GwpackExample <base-url> <api-key> <api-secret> <firmware-file>");
            System.exit(2);
        }
        Gwpack lib = Native.load("sign_tool", Gwpack.class);
        System.out.println("lib version: " + lib.lib_version());

        int rc = lib.configure(args[0], args[1], args[2]);
        if (rc != Gwpack.OK) {
            throw new IllegalStateException("configure failed: " + Gwpack.lastError(lib));
        }

        byte[] firmware = Files.readAllBytes(Path.of(args[3]));
        byte[] pkg = Gwpack.servicePack(lib, firmware, "gateway", "java example");
        String filename = Gwpack.serviceLastFilename(lib);
        Files.write(Path.of(filename), pkg);
        System.out.println("service pack: " + pkg.length + " bytes, filename=" + filename);
    }
}

# 编译（原生库随 workspace 编出）
cargo build --release --workspace

# C 动态加载服务检查（用 sign-server 已起好的服务和凭证）
gcc -o /tmp/c_dlopen_test tool/native/ffi-test/c_dlopen_test.c -ldl
/tmp/c_dlopen_test ./target/release/libsign_tool.so http://127.0.0.1:3009 "<key>" "<secret>"

# Java 示例（在 tool/native/java/ 下，先下 JNA，库路径指到编出的原生库）
curl -fsSL -o jna-5.14.0.jar https://repo1.maven.org/maven2/net/java/dev/jna/jna/5.14.0/jna-5.14.0.jar
javac -cp jna-5.14.0.jar:. Gwpack.java GwpackExample.java
java -Djna.library.path=../../../target/release -cp jna-5.14.0.jar:. GwpackExample http://127.0.0.1:3009 <api-key> <api-secret> <firmware-file>