深入google_auth.proto:google-authenticator-exporter背后的MigrationPayload协议与OtpParameters字段详解
深入google_auth.proto:google-authenticator-exporter背后的MigrationPayload协议与OtpParameters字段详解
google-authenticator-exporter 是一款将 Google Authenticator 导出的 2FA 二维码解码为 TOTP 密钥的开源命令行工具。它的核心是逆向自 Google 官方迁移协议的 google_auth.proto 文件:通过解析 MigrationPayload 消息和其中的 OtpParameters 字段,把 otpauth-migration:// URI 里的 Base64 + Protobuf 编码数据还原成可直接导入其他验证器 App 的密钥。本文将带你完整看懂这份协议。
一、为什么需要破解这个迁移协议?
当你在 Google Authenticator 中执行「设置 → 转移账户 → 导出账户」时,App 会显示一个二维码。用任意扫码工具读取它,会得到类似这样的 URI:
otpauth-migration://offline?data=CiIKCkhlbGwP...
注意 data 参数并不是明文,它经历了三重包装:
- URI 编码(如
%3D实际是=) - Base64 编码
- Protobuf 二进制编码(遵循
MigrationPayload协议)
google-authenticator-exporter 的工作就是把这三层依次剥开,取出每个账户的 TOTP 密钥。入口逻辑在 src/index.js 的 decode() 函数中:先 decodeURIComponent + Base64 解码,再交给 src/google_auth.proto 定义的 MigrationPayload 类型做 Protobuf 反序列化。
二、MigrationPayload 消息总览:一次导出的完整信封
google_auth.proto 定义了 googleauth 包下的顶层消息 MigrationPayload,它是整个导出数据的"信封":
message MigrationPayload {
repeated OtpParameters otp_parameters = 1; // 账户列表(核心)
int32 version = 2; // 协议版本,目前 Google 使用 1
int32 batch_size = 3; // 本次导出被拆成了几批
int32 batch_index = 4; // 当前二维码是第几批
int32 batch_id = 5; // 同一组二维码的批次标识
}
几个值得注意的细节:
| 字段 | 含义 | 新手须知 |
|---|---|---|
otp_parameters |
账户参数数组 | repeated 表示一个二维码里可以装多个账户 |
version |
协议版本号 | 源码 index.js 会校验它必须为 1,否则报错提示 |
batch_size / batch_index / batch_id |
分批信息 | 账户太多时 Google 会把数据拆成多个二维码,这就是你导出时看到一连串二维码的原因 |
💡 分批导出时,每个二维码的
batch_id相同、batch_index递增。src/index.test.js 中就有一个"拆成 2 个二维码导出 12 个账户"的真实测试用例,测试数据存放在 test-assets/test-qr-codes.json。
三、OtpParameters 字段详解:每个 2FA 账户的完整档案
OtpParameters 是协议的核心(google_auth.proto),一条记录对应一个 2FA 账户:
message OtpParameters {
bytes secret = 1; // 原始密钥(Protobuf bytes,实际是 Base64 字符串)
string name = 2; // 账户名,通常是绑定的邮箱
string issuer = 3; // 服务方,如 GitHub、TOTPgenerator
Algorithm algorithm = 4; // 哈希算法
DigitCount digits = 5; // 验证码位数
OtpType type = 6; // HOTP 或 TOTP
int64 counter = 7; // 计数器(仅 HOTP 有意义)
string unique_id = 8; // Google 内部账户唯一标识
}
逐个解读:
secret(最重要):TOTP 算法的"种子密钥",以bytes存储。反序列化后它是一段 Base64 文本,例如SGVsbA8h3q2+6A==。但大多数验证器 App 要求的是 Base32 格式密钥,所以 exporter 会在 src/index.js 中把它转成 Base32(遵循 RFC 3548,由 src/edbase32.js 实现),写入新增字段totpSecret,例如JBSWY3APEHPK3PXI——导入其他 App 时请认准这个字段,而不是secret。name+issuer:账户显示信息,如name是你的邮箱、issuer是网站名。counter:只有 HOTP 类型(基于计数的验证码)才有值,测试用例中的 HOTP 账户就带有"counter": "1"。unique_id:Google 给每个账户分配的 ID(分批导出时用于跨二维码合并),与密钥无关,可忽略。
四、三个枚举速查:Algorithm / DigitCount / OtpType
协议内嵌了三个枚举,决定了验证码的生成规则:
Algorithm(哈希算法)
| 枚举值 | 编号 | 说明 |
|---|---|---|
SHA1 |
1 | 最常见,绝大多数网站默认使用 |
SHA256 |
2 | 部分服务支持 |
SHA512 |
3 | 测试数据中 TOTPgenerator 的账户即使用此算法 |
MD5 |
4 | 极少见 |
ALGORITHM_UNSPECIFIED |
0 | 未指定(默认值) |
DigitCount(验证码位数)
| 枚举值 | 编号 | 说明 |
|---|---|---|
SIX |
1 | 标准 6 位 |
EIGHT |
2 | 8 位(注意编号不是 8!) |
SEVEN |
3 | 7 位(编号也不是 7) |
⚠️ 易踩坑:
EIGHT编号是 2、SEVEN是 3,编号与位数不对应。Protobuf 反序列化时源码(index.js 的enums: String选项)会直接输出枚举名,避免了手工映射出错。
OtpType(验证码类型)
TOTP:基于时间,约 30 秒自动刷新——日常最常见的类型。HOTP:基于计数器,每次点击"下一个码"才前进一次,必须配合counter使用。
五、完整解码流程与真实示例
整个工具的数据流可以概括为一条流水线:
- 扫码得到
otpauth-migration://offline?data=...URI - 提取
data参数 → URI 解码 → Base64 解码 → 得到 Protobuf 二进制(decode()) - 用
MigrationPayload反序列化,取出otp_parameters数组 - 每个账户的
secret经 Base32 转换后生成totpSecret - 输出 JSON(
npm run start)或为每个账户生成标准otpauth://二维码(npm run start:qrcode)
用 src/index.test.js 中的真实测试数据验证一下:
{
"algorithm": "SHA1",
"digits": "SIX",
"name": "Test account 1",
"secret": "SGVsbA8h3q2+6A==",
"totpSecret": "JBSWY3APEHPK3PXI",
"type": "TOTP"
}
可以看到,枚举字段(SHA1、SIX、TOTP)以可读字符串形式呈现,totpSecret 就是你可以直接填入 Aegis、Authy 等验证器的 Base32 密钥。
六、新手常见问题
Q1:运行后提示 "Expected payload version 1"? 说明 Google 更新了协议版本。请到项目 issue 区反馈你的版本号(报错信息中已包含提示)。
Q2:导出数据用在线网站解码安全吗?
⚠️ 不安全。URI 中包含你的邮箱和 2FA 密钥,等于交出了账户控制权。请务必使用本地运行(npm install 后执行 npm run start),或参考 Dockerfile 用 Docker 本地运行。
Q3:导出时出现了很多个二维码?
正常现象,对应 batch_size 分批机制。每个二维码单独扫码、依次输入即可,账户会自动按 otp_parameters 数组追加。
Q4:导入验证器时填 secret 还是 totpSecret?
填 totpSecret。secret 是 Base64 原文,totpSecret 才是通用的 Base32 密钥。
七、项目文件速查
| 文件 | 作用 |
|---|---|
| src/google_auth.proto | MigrationPayload 协议定义(本文主角) |
| src/index.js | 解码主逻辑:URI 解析、Protobuf 反序列化、JSON/二维码输出 |
| src/edbase32.js | Base64 → Base32(RFC 3548)编码实现 |
| src/index.test.js | 解码功能的单元测试与真实样例数据 |
| test-assets/test-qr-codes.json | 测试用二维码 URI 集合(含分批、SHA512 场景) |
| Dockerfile | 本地容器化运行方式 |
| package.json | 依赖声明:protobufjs、qrcode、prompt 等 |
google_auth.proto 虽然只有不到 50 行,却完整描述了 Google Authenticator 迁移协议的全部信息:MigrationPayload 负责分批与版本控制,OtpParameters 承载密钥本体。理解了这两个消息,你就能看懂任何 2FA 迁移二维码背后的数据结构,也才能安全、独立地完成密钥导出。🔑
