Authelia storage encryption rotate 命令详解数据库 HMAC 密钥轮换的 CLI 参考与源码实现【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaauthelia storage encryption rotate是 Authelia CLI 中用于轮换 SQL 存储加密值的命令族。本文基于官方 CLI 参考文档完整梳理该命令的定位、参数与用法并结合internal/commands与internal/storage下的源码讲清hmac otp/hmac otc两个子命令在数据库事务内实际执行了哪些操作随机生成新 HMAC 密钥、写入加密表、清空对应数据表帮助你安全、可验证地完成密钥轮换运维操作。命令定位它在 CLI 命令树中的位置rotate是storage命令下encryption管理子命令组的一员。从命令注册代码 internal/commands/storage.go 可以看到完整的命令树结构authelia storage # 管理 SQL 存储PersistentPreRun 中加载并验证存储配置 └── encryption # 管理存储加密 ├── check # 用当前配置密钥校验数据库数据完整性 ├── change-key # 更换存储主加密密钥 └── rotate # 轮换存储加密值本文主题 └── hmac # 轮换 HMAC 密钥 ├── otp # 轮换 TOTP 历史记录的 HMAC 密钥 └── otc # 轮换一次性代码OTC的 HMAC 密钥需要特别注意rotate本身只是一个父命令不带任何业务逻辑它只有-h, --help一个选项注册代码 internal/commands/storage.go#L180-L196 中未设置RunE。真正执行轮换的是叶子子命令hmac otp与hmac otc它们各自携带一个--force选项子命令短描述长描述来自 internal/commands/const.goauthelia storage encryption rotate hmac otpRotate the OTP HMAC key轮换用于记录 TOTP 历史的 HMAC 密钥同时清空totp_history表authelia storage encryption rotate hmac otcRotate the OTC HMAC key轮换用于一次性代码one-time codes的 HMAC 密钥同时清空one_time_code表两个叶子子命令的命令行选项为-f, --force force the rotation without confirmation -h, --help help for otp / otc官方给出的示例命令同样定义于 internal/commands/const.goauthelia storage encryption rotate hmac otp --config config.yml authelia storage encryption rotate hmac otp --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw authelia storage encryption rotate hmac otc --config config.yml authelia storage encryption rotate hmac otc --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 --postgres.address tcp://postgres:5432 --postgres.password autheliapw以及父命令本身的帮助用法authelia storage encryption rotate --help命令行参数Options 与 Options inherited from parent commands本命令自有选项Options-h, --help help for rotate从父命令继承的选项Options inherited from parent commands这些选项由根命令与storage命令以PersistentFlags形式注册所有storage子命令均可使用。完整清单及默认值如下注册位置见 internal/commands/root.go#L46-L47 与 internal/commands/storage.go#L33-L46-c, --config strings configuration files or directories to load, for more information run authelia -h authelia config (default [configuration.yml]) --config.experimental.filters strings list of filters to apply to all configuration files, for more information run authelia -h authelia filters --encryption-key string the storage encryption key to use --mysql.address string the MySQL server address (default tcp://127.0.0.1:3306) --mysql.database string the MySQL database name (default authelia) --mysql.password string the MySQL password --mysql.username string the MySQL username (default authelia) --postgres.address string the PostgreSQL server address (default tcp://127.0.0.1:5432) --postgres.database string the PostgreSQL database name (default authelia) --postgres.password string the PostgreSQL password --postgres.schema string the PostgreSQL schema name (default public) --postgres.username string the PostgreSQL username (default authelia) --sqlite.path string the SQLite database path各参数的用途说明参数默认值作用-c, --configconfiguration.yml指定配置文件或配置目录命令行值会覆盖配置文件中的同名项--config.experimental.filters无对全部配置文件应用过滤器详见帮助主题authelia -h authelia filters--encryption-key无覆盖配置中的存储主加密密钥。轮换操作本身不生成这个主密钥但它必须正确才能解密数据库encryption表中存放的旧 HMAC 密钥条目并写入新条目--mysql.address/--mysql.database/--mysql.username/--mysql.passwordtcp://127.0.0.1:3306/authelia/authelia/ 无命令行方式指向 MySQL 实例--postgres.address/--postgres.database/--postgres.schema/--postgres.username/--postgres.passwordtcp://127.0.0.1:5432/authelia/public/authelia/ 无命令行方式指向 PostgreSQL 实例--sqlite.path无命令行方式指向 SQLite 数据库文件路径实践建议生产环境通常直接从配置文件-c指向的 YAML读取数据库连接与storage.encryption_key命令行标志主要用于排障、容器内一次性维护或密钥托管在环境变量中的场景。storage命令的PersistentPreRunE会依次执行配置加载、存储配置校验与存储 Provider 初始化internal/commands/storage.go#L22-L27因此密钥配置错误会在真正执行轮换之前就被拦截。源码级执行流程一条 rotate 命令背后发生了什么hmac otp与hmac otc共用同一个入口函数 StorageSchemaEncryptionRotateRunE其处理链如下前置校验先调用ctx.CheckSchema()确认数据库 schema 可用随后runStorageSchemaEncryptionRotateKey通过store.SchemaVersion(ctx)读取 schema 版本若version 0直接报错schema version must be at least version 1 to rotate keysinternal/commands/storage_run.go#L401-L409。即必须先完成初始化/迁移的数据库才能轮换密钥。命令名到数据表的映射入口函数按cmd.Use决定目标表internal/commands/storage_run.go#L389-L396子命令表名internal/storage/const.goHMAC 密钥名密钥长度otcone_time_codeotc存储名hmac_key_otcsha512.BlockSize64 字节otptotp_historyotp存储名hmac_key_otpsha256.BlockSize32 字节交互式确认若未指定--forceCLI 会在终端提示internal/commands/storage_run.go#L411-L421This will rotate the HMAC key and truncate the table table, this is not reversible, type ROTATE and press return to continue:只有原样输入ROTATE才会继续否则命令以cancelling key rotation due to user not accepting data destruction结束。这是为了防止误操作清空数据表而设计的破坏性操作确认。数据库事务内完成轮换核心实现在 SQLProvider.SchemaEncryptionRotateHMACKey步骤为开启事务p.db.Beginx()调用setCrypographyKey(...)用crypto/rand生成指定长度的随机密钥以主加密密钥加密后 upsert 到encryption表名称形如hmac_key_otc/hmac_key_otp格式定义见 internal/storage/const.go#L82-L118replacetrue意味着直接覆盖旧条目对目标表执行TRUNCATEp.truncate(ctx, tx, table)任一步失败即回滚事务全部成功后提交并输出Completed the otc key rotation successfully and cleanly truncated the one_time_code table. Completed the otp key rotation successfully and cleanly truncated the totp_history table.该接口在 internal/storage/provider.go 的Provider接口中以注释明确说明其语义“rotates a HMAC key in the storage provider given a specific name”。收尾入口函数在defer中调用ctx.providers.StorageProvider.Close()关闭连接internal/commands/storage_run.go#L374-L378。为什么必须同时清空数据表从源码结构看两类被保护的数据都以 HMAC 签名做完整性保护OTC 使用hmac-sha512、OTP 历史使用hmac-sha256计算签名签名函数见 internal/storage/sql_provider_encryption.go#L643-L661。一旦 HMAC 密钥被替换旧行中的签名将永远无法通过新密钥校验这些记录实质上已经失效。因此 Authelia 选择在轮换时原子性地截断对应表避免出现“密钥已换但残留不可验证脏数据”的中间状态整个“换密钥 清表”过程包裹在同一个事务中任何一步失败都会回滚保证数据库不会处于半轮换状态。影响面与运维建议otpTOTP 历史轮换totp_history用于记录 TOTP 验证历史供审计/回看用途。轮换后历史记录被清空但不影响任何账号的二次验证能力。otc一次性代码轮换one_time_code存放一次性代码清空后所有已签发但尚未使用的一次性代码立即作废例如设备授权、密码重置等流程中处于进行中的代码。建议安排在低峰维护窗口执行并提醒用户进行中的相关流程需要重新发起。不影响主加密密钥rotate hmac只轮换 HMAC 密钥与storage encryption change-key更换存储主加密密钥会重加密one_time_code、totp_configurations、webauthn_credentials、cached_data、OIDC 会话等全部受保护列实现见 internal/storage/sql_provider_encryption.go#L70-L114是相互独立的两件事。轮换后可用 check 命令交叉验证authelia storage encryption check可加--verbose逐行检查每张表的加密数据通过SchemaEncryptionCheckKey解密校验各表数据输出Storage Encryption Key Validation: SUCCESS / FAILURE适合在轮换前后各跑一次作为基线对比实现见 internal/commands/storage_run.go#L432-L493。相关文档SEE ALSOauthelia storage encryption — Manage storage encryptionauthelia storage encryption rotate hmac — Rotate HMAC keys关键源码索引文件说明internal/commands/storage.gostorage encryption rotate命令树注册、持久化数据库标志定义internal/commands/const.go各子命令的 Short / Long / Example 文案internal/commands/storage_run.go轮换入口、schema 版本检查、ROTATE交互确认internal/storage/sql_provider_encryption.go事务内生成随机 HMAC 密钥、写入加密表并截断数据表internal/storage/provider.goSchemaEncryptionRotateHMACKey接口定义docs/content/reference/cli/authelia/authelia_storage_encryption_rotate.md本文对应的官方 CLI 参考文档原文【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考