Authelia 深度指南用 authelia storage encryption 命令族管理数据库加密【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 使用 AES-GCM 对 SQLite、MySQL 与 PostgreSQL 数据库中存储的 TOTP 密钥、WebAuthn 凭据、OAuth2 会话等敏感数据做应用层加密加密密钥由storage.encryption_key配置项提供。当密钥泄露、需要验证密钥与数据库数据是否匹配、或需要轮换一次性验证码的 HMAC 密钥时官方 CLI 提供了authelia storage encryption命令族change-key/check/rotate三个子命令。读完本篇你将掌握这三个子命令的完整用法与参数、密钥在底层如何派生HKDF与加密GCM AAD以及密钥变更前后的标准安全操作流程。命令定位一个只做分组、没有直接动作的父命令authelia storage encryption本身是一个分组命令group command直接执行它只会打印帮助所有实际操作都在其子命令中完成。从源码 newStorageEncryptionCmd 可以看到该命令被声明为Args: cobra.NoArgs并挂接了三个子命令子命令作用参考文档authelia storage encryption change-key更换存储加密密钥全库重加密authelia_storage_encryption_change-key.mdauthelia storage encryption check校验当前密钥能否解密数据库数据authelia_storage_encryption_check.mdauthelia storage encryption rotate轮换存储加密相关的其他值HMAC 密钥authelia_storage_encryption_rotate.md它的父命令authelia storage用于管理 Authelia 的 SQL 数据库允许执行一系列手动操作起来非常困难的进阶任务参见 authelia storage 文档。encryption命令不接收位置参数唯一的示例就是authelia storage encryption --help选项只有-h, --help其余选项全部继承自父命令见下一节。继承选项如何指定数据库与密钥encryption命令族继承自authelia storage及其上层的持久化标志完整列表如下引自官方参考文档 authelia_storage_encryption.md-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这些标志在源码 newStorageCmd 中通过cmd.PersistentFlags()注册因此对storage下所有子命令生效-c, --config指定配置文件或目录默认加载configuration.yml。配置文件中已声明storage部分时此处的数据库标志用于临时覆盖例如在容器网络内操作另一台主机上的数据库。--encryption-key指定要使用的存储加密密钥避免把密钥写在命令行历史之外的配置里执行check时尤其有用——用它验证「某个密钥是否就是该数据库实际使用的密钥」而不必改动正在运行的配置。--sqlite.path/--mysql.*/--postgres.*三种后端数据库的连接覆盖参数默认值与源码中的注册默认值一致MySQLtcp://127.0.0.1:3306、PostgreSQLtcp://127.0.0.1:5432库名/用户名均为authelia。change-key更换加密密钥并全库重加密change-key用于更换 Authelia SQL 数据库的加密密钥用当前配置的密钥解密全部受保护数据再用新密钥重新加密并写回。用法与示例authelia storage encryption change-key [flags]官方文档给出的示例见 change-key 参考# 方式一密钥来自配置文件 authelia storage encryption change-key --config config.yml --new-encryption-key 0e95cb49-5804-4ad9-be82-bb04a9ddecd8 # 方式二旧密钥与连接参数全部走命令行 authelia storage encryption change-key --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 \ --new-encryption-key 0e95cb49-5804-4ad9-be82-bb04a9ddecd8 \ --postgres.address tcp://postgres:5432 --postgres.password autheliapw专属选项只有一个-h, --help help for change-key --new-encryption-key string the new key to encrypt the data with执行流程与约束源码视角CLI 入口在 StorageSchemaEncryptionChangeKeyRunE其中包含几条硬性约束数据库 schema 版本必须至少为 1否则直接报错schema version must be at least version 1 to change the encryption key新密钥至少 20 个字符且不能为空len(key) 20会失败省略--new-encryption-key时进入交互式模式命令行会提示Enter New Storage Encryption Key:从终端安全读取不显示输入。真正的重加密逻辑在 SchemaEncryptionChangeKey新密钥先经过HKDF-SHA256 派生info 为authelia:kdf:storage:encryption_key:v1见 DeriveCryptographicKey 与 const.go派生结果若与当前密钥相同则报「the old key and the new key are the same」调用SchemaEncryptionCheckKey先用旧密钥验证数据完整性旧密钥不对则中止避免把数据加密成不可恢复的状态随后在单个数据库事务内执行 SchemaEncryptionChangeKeyAdvanced按顺序对以下表逐行「解密→用新密钥重加密→写回」任何一步失败则整体回滚one_time_codeOTC 一次性代码totp_configurationsTOTP 密钥webauthn_credentialsWebAuthn 公钥与 attestationcached_data缓存数据各 OAuth2/OIDC 会话表oauth2_session等遍历所有已知的OAuth2SessionTypeencryption存储自身的管理值含 check 值与 HMAC 密钥成功后 CLI 输出Completed the encryption key change. Please adjust your configuration to use the new key.—— 也就是说数据库侧完成后还必须把新密钥写入运行配置storage.encryption_key或对应 secret再重启服务。check校验密钥与数据库数据是否匹配check用于验证当前配置的加密密钥对该数据库有效官方描述是“useful for validating all data that can be encrypted is intact”在密钥变更前后、数据库迁移或备份恢复之后执行它是最稳妥的习惯。用法与示例authelia storage encryption check [flags]authelia storage encryption check authelia storage encryption check --verbose authelia storage encryption check --verbose --config config.yml authelia storage encryption check --verbose \ --encryption-key b3453fde-ecc2-4a1f-9422-2707ddbed495 \ --postgres.address tcp://postgres:5432 --postgres.password autheliapw专属选项-h, --help help for check --verbose enables verbose checking of every row of encrypted data校验逻辑与输出默认非 verbose只解密encryption表中的哨兵值check value即可判断密钥对错代价小。核心在 checkEncryptionCheckValue它会按当前 schema 版本选择对应的密钥派生方式与 AAD旧库使用遗留的 SHA256 派生新库使用 HKDF 派生保证对未升级的旧库不会误报失败。--verboseSchemaEncryptionCheckKey 会对上面change-key提到的每一张加密表逐行执行解密统计每张表的Total Rows与Invalid Rows。CLI 输出由 runStorageSchemaEncryptionCheckKey 决定共四种结果Storage Encryption Key Validation: SUCCESSStorage Encryption Key Validation: FAILURE Cause: The schema version doesnt support encryption.Storage Encryption Key Validation: UNKNOWN Cause: 具体错误.verbose 模式下还会打印各表明细Tables: Table (one_time_code): ... Invalid Rows: 0 Total Rows: 12rotate轮换 HMAC 密钥破坏性操作rotate子命令族用于轮换存储中用于签名一次性验证码的 HMAC 密钥它不改变encryption_key本身而是重新生成 HMAC 密钥并清空其保护的表authelia storage encryption rotate hmac otc # 轮换 OTC HMAC 密钥清空 one_time_code 表 authelia storage encryption rotate hmac otp # 轮换 OTP HMAC 密钥清空 totp_history 表对应参考文档rotate hmac、rotate hmac otc、rotate hmac otp。从源码可以确认其破坏性与防护机制实现 SchemaEncryptionRotateHMACKey 在一个事务里完成两件事用crypto/rand生成新 HMAC 密钥OTC 用 SHA-512 块大小的 keyOTP 用 SHA-256 块大小的 key写入encryption表然后truncate对应表——otc对应one_time_code表otp对应totp_history表两个子命令各带一个-f, --force标志“force the rotation without confirmation”。不带-f时runStorageSchemaEncryptionRotateKey 会要求交互式确认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回车才继续否则取消。HMAC 密钥本身是加密后存放在encryption表中的名称形如hmac:name见 setCrypographyKey所以轮换 HMAC 密钥不影响storage.encryption_key的有效性。底层原理密钥派生、GCM 加密与 AAD理解这一命令族的前提是了解 Authelia 存储加密的三层结构1. 密钥派生用户密钥 ≠ 实际密钥配置中的storage.encryption_key不会直接用于加解密。新版实现通过 HKDF-SHA256 派生出 32 字节密钥internal/utils/crypto.goreader : hkdf.New(hash, raw, nil, []byte(info)) // info authelia:kdf:storage:encryption_key:v1早期版本使用DeriveLegacyCryptographicKey直接sha256.Sum256(raw)派生。这个差异决定了旧库升级路径schema 24 及以下的库按遗留方式校验升级迁移完成后自动切换到 HKDF 派生。2. AES-GCM 附加认证数据AAD所有密文都用 GCM 模式打开/关闭见 utils 加解密实现并且每个值的 AADAdditional Authenticated Data把密文绑定到它所在的表、列和行防止跨表/跨行搬移密文。三种 AAD 方案随 schema 版本演进选择逻辑见 aadForSchemaVersionschema 版本AAD 方案绑定粒度 25aadNone无 AAD25未发布aadColumn表 列authelia:storage:table:column 26aadRow表 列 行如 TOTP 按 username、WebAuthn 按 KIDRPID 细化版本常量定义在 internal/storage/const.goschemaVersionEncryptionKeyDerivation 25、schemaVersionEncryptionAADRowScoped 26。change-key在执行重加密前会先SchemaVersion查询并据此同时选定解密与加密所用的 AAD 方案。3. 受保护的表清单check --verbose与change-key遍历的加密列与源码一一对应表加密列AAD 行标识one_time_codecodesignaturetotp_configurationssecretusernamewebauthn_credentialspublic_key、attestationKID RPIDissuer 化 AADcached_datavaluenameoauth2_session等 OIDC 会话表session_datasignatureencryptionvaluenameHMAC 密钥、check 值等配置与密钥保管加密密钥的常规配置位置在configuration.yml的storage.encryption_key示例见 config.template.yml 与存储介绍文档storage: encryption_key: a_very_important_secret sqlite: path: /config/db.sqlite3官方推荐的保管方式是secrets 配置方法当配置键以key、secret、password、token、certificate_chain结尾时可以用带_FILE后缀的环境变量指向一个 Authelia 进程可读的文件例如AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE文件尾部的换行会被自动去除详见 Secrets 配置方法。注意该方法是配置分层模型中独占的一层——同一个 secret 不能同时用其他方法配置否则 Authelia 拒绝启动。对 CLI 场景--encryption-key标志提供了不依赖配置文件的路径但由于命令行参数会进入 shell 历史生产环境更建议用--config指向包含密钥的配置或交互式提示模式change-key省略--new-encryption-key时即进入该模式。实操建议密钥生命周期操作清单综合上述源码行为一次完整的密钥管理流程可以归纳为变更前authelia storage encryption check --verbose --config config.yml确认当前密钥下全部Invalid Rows: 0并备份数据库change-key虽在事务内执行备份仍是恢复的唯一兜底生成新密钥长度不低于 20 字符CLI 硬校验建议用密码学安全随机源生成执行换钥authelia storage encryption change-key --config config.yml --new-encryption-key new-key该命令内部会先跑一次完整校验旧密钥不对会直接中止不会留下半重加密状态更新运行配置把storage.encryption_key或AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE指向的文件改为新密钥并重启 Authelia变更后验证authelia storage encryption check --verbose全部Invalid Rows: 0且输出SUCCESS即完成如怀疑 OTC/OTP 签名密钥暴露用rotate hmac otc/rotate hmac otp轮换接受其清空对应表一次性验证码的代价非交互环境加-f。需要强调的是适用前提以上操作要求数据库 schema 版本至少为 1check对更低版本会报告The schema version doesnt support encryption且change-key成功后必须同步更新运行配置否则服务重启后将以新配置密钥去解密仍用旧密钥加密的数据登录相关功能将全部失败——这正是变更前先check --verbose、变更后再次check --verbose的价值所在。【免费下载链接】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），仅供参考