深入google_auth.proto:google-authenticator-exporter背后的MigrationPayload协议与OtpParameters字段详解

原创2026-11-16 19:00:071,406 阅读

深入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-exporter 运行终端效果:解码 MigrationPayload 数据并输出 TOTP 密钥

一、为什么需要破解这个迁移协议?

当你在 Google Authenticator 中执行「设置 → 转移账户 → 导出账户」时,App 会显示一个二维码。用任意扫码工具读取它,会得到类似这样的 URI:

otpauth-migration://offline?data=CiIKCkhlbGwP...

注意 data 参数并不是明文,它经历了三重包装:

  1. URI 编码(如 %3D 实际是 =)
  2. Base64 编码
  3. 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 使用。

五、完整解码流程与真实示例

整个工具的数据流可以概括为一条流水线:

  1. 扫码得到 otpauth-migration://offline?data=... URI
  2. 提取 data 参数 → URI 解码 → Base64 解码 → 得到 Protobuf 二进制(decode())
  3. 用 MigrationPayload 反序列化,取出 otp_parameters 数组
  4. 每个账户的 secret 经 Base32 转换后生成 totpSecret
  5. 输出 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 迁移二维码背后的数据结构,也才能安全、独立地完成密钥导出。🔑

登录后查看全文
google-authenticator-exporter