Authelia storage encryption rotate hmac otc 命令详解OTC HMAC 密钥轮换与 one_time_code 表清理【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本文围绕 Authelia 官方 CLI 参考文档authelia storage encryption rotate hmac otc展开完整介绍该命令的用法、全部参数并结合仓库源码剖析其底层实现链路HMAC 密钥如何在事务中被替换、one_time_code表为何必须被截断truncate、密钥尺寸为何与 SHA-512 绑定以及-f/--force确认保护机制的工作原理帮助读者在生产环境中安全、正确地执行一次性代码签名密钥的轮换。命令概述authelia storage encryption rotate hmac otc用于轮换一次性代码One-Time CodeOTC所使用的 HMAC 密钥。根据官方参考文档的说明Rotate the OTC HMAC key. This subcommand allows rotation of the HMAC key used for one-time codes. In addition it truncates the one_time_code table.即该子命令在轮换 OTC HMAC 密钥的同时会截断one_time_code数据表使所有基于旧密钥生成签名的存量一次性代码全部作废。命令的基本形式为authelia storage encryption rotate hmac otc [flags]典型使用示例官方文档给出了两种等价的使用方式来自 命令文档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第一种从配置文件加载存储连接与加密密钥信息第二种通过命令行标志直接内联提供加密密钥与 PostgreSQL 连接参数适合无配置文件或临时运维场景。命令参数参考本命令专有选项选项说明-f, --force跳过交互确认强制执行轮换-h, --help显示otc子命令帮助从父命令继承的选项选项默认值说明-c, --config strings[configuration.yml]要加载的配置文件或目录详情可运行authelia -h authelia config--config.experimental.filters strings-应用于所有配置文件的过滤器列表详情可运行authelia -h authelia filters--encryption-key string-使用的存储加密密钥--mysql.address stringtcp://127.0.0.1:3306MySQL 服务器地址--mysql.database stringautheliaMySQL 数据库名--mysql.password string-MySQL 密码--mysql.username stringautheliaMySQL 用户名--postgres.address stringtcp://127.0.0.1:5432PostgreSQL 服务器地址--postgres.database stringautheliaPostgreSQL 数据库名--postgres.password string-PostgreSQL 密码--postgres.schema stringpublicPostgreSQL schema 名--postgres.username stringautheliaPostgreSQL 用户名--sqlite.path string-SQLite 数据库文件路径这些存储相关标志在源码中的映射关系可以在 internal/commands/storage_run.go 的ConfigStorageCommandLineConfigRunE中得到印证--encryption-key映射到配置项storage.encryption_key--sqlite.path映射到storage.local.path各 MySQL/PostgreSQL 标志一一对应到storage.mysql.*与storage.postgres.*配置路径即命令行标志与配置文件字段是同一套配置模型的不同来源。关联命令authelia storage encryption rotate hmac —— 父命令管理 HMAC 密钥轮换下含otc与otp两个子命令。它保护的是什么OTC 与 HMAC 签名的关系要理解这条命令的必要性先要看清 OTC 在 Authelia 中的角色。一次性代码模型定义于 internal/model/one_time_code.go// OneTimeCode represents special one-time codes stored in the database. type OneTimeCode struct { ID int db:id PublicID uuid.UUID db:public_id Signature string db:signature IssuedAt time.Time db:issued IssuedIP IP db:issued_ip ExpiresAt time.Time db:expires Username string db:username Intent string db:intent ConsumedAt sql.NullTime db:consumed ConsumedIP NullIP db:consumed_ip RevokedAt sql.NullTime db:revoked RevokedIP NullIP db:revoked_ip Code []byte db:code }关键事实均来自源码当前唯一用途是会话提权session elevationNewOneTimeCode生成代码时固定写入Intent: OTCIntentUserSessionElevation值为use说明当前 OTC 机制服务于用户会话提权流程见 internal/handlers/handler_session_elevation.go代码本体加密存储code列并非明文而是使用存储加密密钥--encryption-key对应的那把密钥加密后入库并在加密时以signature作为 AAD附加认证数据见 internal/storage/sql_provider.go 中的utils.Encrypt(code.Code, p.aad.Get(tableOneTimeCode, columnCode, code.Signature), ...)signature列由 HMAC 密钥派生常量定义见 internal/storage/const.gotableOneTimeCode one_time_code、hmacNameOneTimeCode otc、keyTypeCryptographyHMAC hmac。从源码结构看OTC 的 HMAC 密钥以SHA-512 块大小128 字节生成与读取internal/storage/sql_provider_encryption.go 中p.getHMACKey(ctx, hmacNameOneTimeCode, sha512.BlockSize)而 OTP 历史表对应的密钥则使用 SHA-256 块大小二者在SchemaEncryptionRotateHMACKey的 switch 分支中明确区分。由此可以推断one_time_code表中的signature依赖这把 HMAC 密钥计算。一旦密钥被替换旧签名将无法再被新密钥校验通过所有未消费/未过期的存量 OTC 都将永久失效——这正是命令必须同步截断该表的根本原因而不是可选的附带行为。源码级执行链路剖析第一步命令定义命令树在 internal/commands/storage.go 中装配storage→encryption→rotate→hmac→otc其中otc子命令绑定RunE: ctx.StorageSchemaEncryptionRotateRunE并注册-f/--force布尔标志Args: cobra.NoArgs即不接受位置参数。命令的短描述与示例文本定义在 internal/commands/const.go。第二步前置校验与表名映射StorageSchemaEncryptionRotateRunEinternal/commands/storage_run.go执行顺序为在命令退出时确保关闭存储连接defer Closectx.CheckSchema()检查存储 schema 就绪状态读取--force标志根据cmd.Use将子命令名映射为受保护表名otc→one_time_codeotp→totp_history。第三步版本校验、交互确认、执行轮换核心逻辑在runStorageSchemaEncryptionRotateKeyinternal/commands/storage_run.gofunc runStorageSchemaEncryptionRotateKey(ctx context.Context, w io.Writer, store storage.Provider, table, name string, force bool) (err error) { var version int if version, err store.SchemaVersion(ctx); err ! nil { return err } if version 0 { return errors.New(schema version must be at least version 1 to rotate keys) } if !force { var confirmed bool if confirmed, err termReadConfirmation(fmt.Sprintf(This will rotate the HMAC key and truncate the %s table, this is not reversible, type ROTATE and press return to continue: , table), ROTATE); err ! nil { return err } if !confirmed { return errors.New(cancelling key rotation due to user not accepting data destruction) } } if err store.SchemaEncryptionRotateHMACKey(ctx, name); err ! nil { return err } _, _ fmt.Fprintf(w, Completed the %s key rotation successfully and cleanly truncated the %s table.\n, name, table) return nil }三个要点值得注意Schema 版本门槛schema 版本必须 ≥ 1已初始化未初始化的库无法执行轮换不可逆性确认未加--force时终端会提示This will rotate the HMAC key and truncate the one_time_code table, this is not reversible, type ROTATE and press return to continue:必须键入ROTATE才继续拒绝则返回错误cancelling key rotation due to user not accepting data destruction成功输出Completed the otc key rotation successfully and cleanly truncated the one_time_code table.可直接用于脚本中的结果判断。第四步事务化替换密钥并截断表存储层实现在 internal/storage/sql_provider_encryption.go 的SchemaEncryptionRotateHMACKey// SchemaEncryptionRotateHMACKey rotates the HMAC key with the given name, truncating the table it protects. func (p *SQLProvider) SchemaEncryptionRotateHMACKey(ctx context.Context, name string) (err error) { // ... switch name { case hmacNameOneTimeCode: size, table, desc sha512.BlockSize, tableOneTimeCode, one time-codes case hmacNameOneTimePassword: size, table, desc sha256.BlockSize, tableTOTPHistory, totp history default: return fmt.Errorf(unknown key name %s, name) } var tx SQLXTx if tx, err p.db.Beginx(); err ! nil { /* 回滚并报错 */ } if _, err p.setCrypographyKey(ctx, tx, keyTypeCryptographyHMAC, name, size, true); err ! nil { /* 回滚并报错 */ } if err p.truncate(ctx, tx, table); err ! nil { /* 回滚并报错 */ } if err tx.Commit(); err ! nil { /* 报错 */ } return nil }实现细节该操作是原子事务Beginx开启事务后依次“写入新 HMAC 密钥setCrypographyKeyreplacetrue覆盖旧密钥→TRUNCATE目标表 →Commit任一步失败都会回滚不会出现“密钥已换但表未清空”或“表已清空但密钥未换”的中间状态OTC 密钥尺寸固定为sha512.BlockSize128 字节与 OTC 签名所使用的 HMAC-SHA512 相匹配该接口是存储提供者的通用契约声明于 internal/storage/provider.go因此对 SQLite、MySQL、PostgreSQL 三种后端行为一致对应的测试用例TestSQLProviderSchemaEncryptionRotateHMACKey位于 internal/storage/sql_provider_mock_test.go覆盖了不同密钥名称otc/otp下的轮换路径。实操建议与边界条件轮换时机OTC 生命周期短ExpiresAt由签发时的时长决定截断one_time_code表只会作废“尚未消费”的活跃提权代码。建议只在怀疑 HMAC 密钥泄露、或按密钥轮换策略定期执行时运行该命令执行前后确认没有正在进行中的会话提权流程。--force的适用场景确认提示需要 TTY 交互输入ROTATE因此自动化脚本CI、Ansible、systemd timer 等中必须加-f才能跳过交互在交互式 shell 中则建议保留确认环节防止误操作。与otp子命令的区别hmac父命令下另有otp子命令internal/commands/storage.go它轮换的是 TOTP 历史记录表totp_history的 HMAC 密钥SHA-256 块大小。两者共用StorageSchemaEncryptionRotateRunE执行体仅通过cmd.Use区分目标表请勿混用。与change-key的区别storage encryption change-key是替换存储加密密钥保护code等加密列的那把密钥它需要重加密全量数据且保留数据而本命令替换的是HMAC 签名密钥数据必须整体作废。轮换后验证可配合authelia storage encryption check同属storage encryption子命令见 internal/commands/storage.go与storage schema info检查存储密钥状态确认轮换后存储整体仍为有效状态。前提条件--encryption-key与配置文件中的storage.encryption_key模板见 config.template.yml必须指向当前存储正在使用的密钥且目标数据库 schema 版本 ≥ 1连接参数默认值如 PostgreSQLtcp://127.0.0.1:5432、MySQLtcp://127.0.0.1:3306适用于本地部署生产环境请显式传入--postgres.*等标志。总结authelia storage encryption rotate hmac otc是 Authelia 密钥生命周期管理中的专用安全运维命令它以事务方式替换一次性代码的 HMAC-SHA512 签名密钥并原子性地清空one_time_code表从而让旧密钥签发的所有未消费提权代码一次性失效。理解其“密钥轮换必须伴随数据作废”的设计源于 signature 对密钥的依赖与 code 列 AAD 绑定 signature 的加密方式见 internal/storage/sql_provider.go再配合-f/--force的确认机制就能在安全事件响应与常规密钥治理场景中正确、可控地执行该操作。参考资料仓库内路径命令参考文档命令树装配CLI 执行体与确认逻辑存储层密钥轮换实现存储常量定义OneTimeCode 模型存储提供者接口声明轮换行为测试【免费下载链接】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），仅供参考 Authelia storage encryption rotate hmac otc 命令详解：OTC HMAC 密钥轮换与 one_time_code 表清理
Authelia storage encryption rotate hmac otc 命令详解OTC HMAC 密钥轮换与 one_time_code 表清理【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本文围绕 Authelia 官方 CLI 参考文档authelia storage encryption rotate hmac otc展开完整介绍该命令的用法、全部参数并结合仓库源码剖析其底层实现链路HMAC 密钥如何在事务中被替换、one_time_code表为何必须被截断truncate、密钥尺寸为何与 SHA-512 绑定以及-f/--force确认保护机制的工作原理帮助读者在生产环境中安全、正确地执行一次性代码签名密钥的轮换。命令概述authelia storage encryption rotate hmac otc用于轮换一次性代码One-Time CodeOTC所使用的 HMAC 密钥。根据官方参考文档的说明Rotate the OTC HMAC key. This subcommand allows rotation of the HMAC key used for one-time codes. In addition it truncates the one_time_code table.即该子命令在轮换 OTC HMAC 密钥的同时会截断one_time_code数据表使所有基于旧密钥生成签名的存量一次性代码全部作废。命令的基本形式为authelia storage encryption rotate hmac otc [flags]典型使用示例官方文档给出了两种等价的使用方式来自 命令文档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第一种从配置文件加载存储连接与加密密钥信息第二种通过命令行标志直接内联提供加密密钥与 PostgreSQL 连接参数适合无配置文件或临时运维场景。命令参数参考本命令专有选项选项说明-f, --force跳过交互确认强制执行轮换-h, --help显示otc子命令帮助从父命令继承的选项选项默认值说明-c, --config strings[configuration.yml]要加载的配置文件或目录详情可运行authelia -h authelia config--config.experimental.filters strings-应用于所有配置文件的过滤器列表详情可运行authelia -h authelia filters--encryption-key string-使用的存储加密密钥--mysql.address stringtcp://127.0.0.1:3306MySQL 服务器地址--mysql.database stringautheliaMySQL 数据库名--mysql.password string-MySQL 密码--mysql.username stringautheliaMySQL 用户名--postgres.address stringtcp://127.0.0.1:5432PostgreSQL 服务器地址--postgres.database stringautheliaPostgreSQL 数据库名--postgres.password string-PostgreSQL 密码--postgres.schema stringpublicPostgreSQL schema 名--postgres.username stringautheliaPostgreSQL 用户名--sqlite.path string-SQLite 数据库文件路径这些存储相关标志在源码中的映射关系可以在 internal/commands/storage_run.go 的ConfigStorageCommandLineConfigRunE中得到印证--encryption-key映射到配置项storage.encryption_key--sqlite.path映射到storage.local.path各 MySQL/PostgreSQL 标志一一对应到storage.mysql.*与storage.postgres.*配置路径即命令行标志与配置文件字段是同一套配置模型的不同来源。关联命令authelia storage encryption rotate hmac —— 父命令管理 HMAC 密钥轮换下含otc与otp两个子命令。它保护的是什么OTC 与 HMAC 签名的关系要理解这条命令的必要性先要看清 OTC 在 Authelia 中的角色。一次性代码模型定义于 internal/model/one_time_code.go// OneTimeCode represents special one-time codes stored in the database. type OneTimeCode struct { ID int db:id PublicID uuid.UUID db:public_id Signature string db:signature IssuedAt time.Time db:issued IssuedIP IP db:issued_ip ExpiresAt time.Time db:expires Username string db:username Intent string db:intent ConsumedAt sql.NullTime db:consumed ConsumedIP NullIP db:consumed_ip RevokedAt sql.NullTime db:revoked RevokedIP NullIP db:revoked_ip Code []byte db:code }关键事实均来自源码当前唯一用途是会话提权session elevationNewOneTimeCode生成代码时固定写入Intent: OTCIntentUserSessionElevation值为use说明当前 OTC 机制服务于用户会话提权流程见 internal/handlers/handler_session_elevation.go代码本体加密存储code列并非明文而是使用存储加密密钥--encryption-key对应的那把密钥加密后入库并在加密时以signature作为 AAD附加认证数据见 internal/storage/sql_provider.go 中的utils.Encrypt(code.Code, p.aad.Get(tableOneTimeCode, columnCode, code.Signature), ...)signature列由 HMAC 密钥派生常量定义见 internal/storage/const.gotableOneTimeCode one_time_code、hmacNameOneTimeCode otc、keyTypeCryptographyHMAC hmac。从源码结构看OTC 的 HMAC 密钥以SHA-512 块大小128 字节生成与读取internal/storage/sql_provider_encryption.go 中p.getHMACKey(ctx, hmacNameOneTimeCode, sha512.BlockSize)而 OTP 历史表对应的密钥则使用 SHA-256 块大小二者在SchemaEncryptionRotateHMACKey的 switch 分支中明确区分。由此可以推断one_time_code表中的signature依赖这把 HMAC 密钥计算。一旦密钥被替换旧签名将无法再被新密钥校验通过所有未消费/未过期的存量 OTC 都将永久失效——这正是命令必须同步截断该表的根本原因而不是可选的附带行为。源码级执行链路剖析第一步命令定义命令树在 internal/commands/storage.go 中装配storage→encryption→rotate→hmac→otc其中otc子命令绑定RunE: ctx.StorageSchemaEncryptionRotateRunE并注册-f/--force布尔标志Args: cobra.NoArgs即不接受位置参数。命令的短描述与示例文本定义在 internal/commands/const.go。第二步前置校验与表名映射StorageSchemaEncryptionRotateRunEinternal/commands/storage_run.go执行顺序为在命令退出时确保关闭存储连接defer Closectx.CheckSchema()检查存储 schema 就绪状态读取--force标志根据cmd.Use将子命令名映射为受保护表名otc→one_time_codeotp→totp_history。第三步版本校验、交互确认、执行轮换核心逻辑在runStorageSchemaEncryptionRotateKeyinternal/commands/storage_run.gofunc runStorageSchemaEncryptionRotateKey(ctx context.Context, w io.Writer, store storage.Provider, table, name string, force bool) (err error) { var version int if version, err store.SchemaVersion(ctx); err ! nil { return err } if version 0 { return errors.New(schema version must be at least version 1 to rotate keys) } if !force { var confirmed bool if confirmed, err termReadConfirmation(fmt.Sprintf(This will rotate the HMAC key and truncate the %s table, this is not reversible, type ROTATE and press return to continue: , table), ROTATE); err ! nil { return err } if !confirmed { return errors.New(cancelling key rotation due to user not accepting data destruction) } } if err store.SchemaEncryptionRotateHMACKey(ctx, name); err ! nil { return err } _, _ fmt.Fprintf(w, Completed the %s key rotation successfully and cleanly truncated the %s table.\n, name, table) return nil }三个要点值得注意Schema 版本门槛schema 版本必须 ≥ 1已初始化未初始化的库无法执行轮换不可逆性确认未加--force时终端会提示This will rotate the HMAC key and truncate the one_time_code table, this is not reversible, type ROTATE and press return to continue:必须键入ROTATE才继续拒绝则返回错误cancelling key rotation due to user not accepting data destruction成功输出Completed the otc key rotation successfully and cleanly truncated the one_time_code table.可直接用于脚本中的结果判断。第四步事务化替换密钥并截断表存储层实现在 internal/storage/sql_provider_encryption.go 的SchemaEncryptionRotateHMACKey// SchemaEncryptionRotateHMACKey rotates the HMAC key with the given name, truncating the table it protects. func (p *SQLProvider) SchemaEncryptionRotateHMACKey(ctx context.Context, name string) (err error) { // ... switch name { case hmacNameOneTimeCode: size, table, desc sha512.BlockSize, tableOneTimeCode, one time-codes case hmacNameOneTimePassword: size, table, desc sha256.BlockSize, tableTOTPHistory, totp history default: return fmt.Errorf(unknown key name %s, name) } var tx SQLXTx if tx, err p.db.Beginx(); err ! nil { /* 回滚并报错 */ } if _, err p.setCrypographyKey(ctx, tx, keyTypeCryptographyHMAC, name, size, true); err ! nil { /* 回滚并报错 */ } if err p.truncate(ctx, tx, table); err ! nil { /* 回滚并报错 */ } if err tx.Commit(); err ! nil { /* 报错 */ } return nil }实现细节该操作是原子事务Beginx开启事务后依次“写入新 HMAC 密钥setCrypographyKeyreplacetrue覆盖旧密钥→TRUNCATE目标表 →Commit任一步失败都会回滚不会出现“密钥已换但表未清空”或“表已清空但密钥未换”的中间状态OTC 密钥尺寸固定为sha512.BlockSize128 字节与 OTC 签名所使用的 HMAC-SHA512 相匹配该接口是存储提供者的通用契约声明于 internal/storage/provider.go因此对 SQLite、MySQL、PostgreSQL 三种后端行为一致对应的测试用例TestSQLProviderSchemaEncryptionRotateHMACKey位于 internal/storage/sql_provider_mock_test.go覆盖了不同密钥名称otc/otp下的轮换路径。实操建议与边界条件轮换时机OTC 生命周期短ExpiresAt由签发时的时长决定截断one_time_code表只会作废“尚未消费”的活跃提权代码。建议只在怀疑 HMAC 密钥泄露、或按密钥轮换策略定期执行时运行该命令执行前后确认没有正在进行中的会话提权流程。--force的适用场景确认提示需要 TTY 交互输入ROTATE因此自动化脚本CI、Ansible、systemd timer 等中必须加-f才能跳过交互在交互式 shell 中则建议保留确认环节防止误操作。与otp子命令的区别hmac父命令下另有otp子命令internal/commands/storage.go它轮换的是 TOTP 历史记录表totp_history的 HMAC 密钥SHA-256 块大小。两者共用StorageSchemaEncryptionRotateRunE执行体仅通过cmd.Use区分目标表请勿混用。与change-key的区别storage encryption change-key是替换存储加密密钥保护code等加密列的那把密钥它需要重加密全量数据且保留数据而本命令替换的是HMAC 签名密钥数据必须整体作废。轮换后验证可配合authelia storage encryption check同属storage encryption子命令见 internal/commands/storage.go与storage schema info检查存储密钥状态确认轮换后存储整体仍为有效状态。前提条件--encryption-key与配置文件中的storage.encryption_key模板见 config.template.yml必须指向当前存储正在使用的密钥且目标数据库 schema 版本 ≥ 1连接参数默认值如 PostgreSQLtcp://127.0.0.1:5432、MySQLtcp://127.0.0.1:3306适用于本地部署生产环境请显式传入--postgres.*等标志。总结authelia storage encryption rotate hmac otc是 Authelia 密钥生命周期管理中的专用安全运维命令它以事务方式替换一次性代码的 HMAC-SHA512 签名密钥并原子性地清空one_time_code表从而让旧密钥签发的所有未消费提权代码一次性失效。理解其“密钥轮换必须伴随数据作废”的设计源于 signature 对密钥的依赖与 code 列 AAD 绑定 signature 的加密方式见 internal/storage/sql_provider.go再配合-f/--force的确认机制就能在安全事件响应与常规密钥治理场景中正确、可控地执行该操作。参考资料仓库内路径命令参考文档命令树装配CLI 执行体与确认逻辑存储层密钥轮换实现存储常量定义OneTimeCode 模型存储提供者接口声明轮换行为测试【免费下载链接】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），仅供参考