Authelia CLI 实战：authelia crypto pair ed25519 generate 命令详解与 Ed25519 密钥对生成原理

Authelia CLI 实战：authelia crypto pair ed25519 generate 命令详解与 Ed25519 密钥对生成原理

【免费下载链接】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 crypto pair ed25519 generate子命令的用途、全部选项与默认值，并结合internal/commands与internal/utils中的源码实现，说明该命令从随机数生成、Ed25519 密钥对派生到 PEM 文件落盘（0600 权限）的完整调用链，帮助你既能正确使用该命令，也能理解输出文件格式与--legacy标志为何对 Ed25519 不生效等细节。

命令定位：authelia crypto 命令树中的位置

authelia crypto pair ed25519 generate属于 Authelia CLI 的crypto命令族。从 命令注册代码 看，newCryptoCmd下挂有rand、certificate、hash、pair四个子命令，其中newCryptoPairCmd又按算法分别注册了 RSA、ECDSA、Ed25519 和 ML-DSA 四个分支，每个分支下再挂一个generate子命令：

authelia crypto └── pair ├── rsa └── generate ├── ecdsa └── generate ├── ed25519 └── generate ← 本文主题 └── mldsa └── generate

对应参考文档见 authelia crypto pair ed25519 与本文对应的 generate 子命令页。该子命令的用途很直接：生成一对密码学 Ed25519 密钥，并将私钥与公钥分别导出为 PEM 文件。

Ed25519 在 Authelia 生态中是实际有用的密钥材料：例如 OIDC Provider 的json_web_keys配置校验逻辑 validateOIDCIssuerPrivateKeyPair 就显式接受ed25519.PrivateKey作为 JWKS 私钥类型之一。因此该命令产出的密钥对可以直接用于 OIDC 签名密钥等场景。

Synopsis 与基本用法

按官方参考文档，命令摘要（Synopsis）为：

Generate a cryptographic Ed25519 key pair.

用法：

authelia crypto pair ed25519 generate [flags]

文档给出的最小示例：

authelia crypto pair ed25519 generate --help

实际生成一对密钥并输出到指定目录：

authelia crypto pair ed25519 generate -d /var/authelia/keys

成功后 stdout 会打印（由 runCryptoPairGenerate 组装）：

Generating key pair Algorithm: Ed25519 Output Paths: Directory: /var/authelia/keys Private Key: private.pem Public Key: public.pem

选项详解（Options）

以下是官方参考文档列出的全部选项，并结合 cmdFlagsCryptoPrivateKey 与 cmdFlagsCryptoPairGenerate 中的源码定义补充说明：

几个要点：

• 文件路径拼接规则：--file.private-key/--file.public-key的值是相对文件名，最终路径由 cryptoGetWritePathsFromCmd 执行filepath.Join(dir, path)得到。对 pair 场景，源码中固定选取私钥/公钥两个文件标志位（flagPrivate, flagPublic = cmdFlagNameFilePrivateKey, cmdFlagNameFilePublicKey）。
• --legacy对 Ed25519 实际不生效：这是源码里一个值得注意的细节。cryptoKeyProperties 中ed25519.PrivateKey分支返回legacy = false，而 runCryptoPairGenerate 中执行legacy = legacy && legacyKey。由于 Ed25519 只有 PKCS#8 私钥与 PKIX 公钥两种标准编码，不存在 PKCS#1 / SECG1 对应的传统格式，所以即使传入--legacy，也不会生成额外文件。
• Ed25519 无算法专属参数：对比源码 cmdFlagsCryptoPrivateKeyEd25519 是一个空函数——RSA 分支有-b/--bits（默认 2048）、ECDSA 有-b/--curve（默认 P256）、ML-DSA 有-b/--parameters（默认 ML-DSA-65），而 Ed25519 密钥长度是算法固定的，无需（也无法）配置。

从父命令继承的选项

参考文档列出的继承选项（定义于根命令）：

对 generate 这类纯密钥生成操作而言，配置文件加载并非必需流程，这两个标志是命令树统一挂载的通用能力。

源码级执行流程：从随机数到 PEM 文件

该子命令的RunE是共享入口 CryptoGenerateRunE，整个执行链如下：

1. 生成私钥。cryptoGenPrivateKeyFromCmd 根据父命令的 Use（ed25519）分派，调用标准库：

   case cmdUseEd25519: if _, privateKey, err = ed25519.GenerateKey(ctx.providers.Random); err != nil { return nil, fmt.Errorf("generating Ed25519 private key resulted in an error: %w", err) }

   熵源来自ctx.providers.Random，即 Authelia 命令上下文注入的随机数提供者，而非直接调用crypto/rand全局接口——从源码结构看这是一种便于测试注入的依赖设计。

2. 分派到 pair 生成逻辑。CryptoGenerateRunE检查祖父命令是否为certificate；本命令为pair场景，因此进入 CryptoPairGenerateRunE，读取--legacy、--file.extension.legacy两个标志后计算输出路径。

3. 派生公钥并写文件。runCryptoPairGenerate 依次：

   • 通过 cryptoKeyAlgorithm 得到算法名Ed25519用于打印；
   • 私钥经 utils.WriteKeyToPEM 写入private.pem；
   • 公钥通过 PublicKeyFromPrivateKey 对ed25519.PrivateKey调用k.Public()派生，再写入public.pem。

4. PEM 编码格式。PEMBlockFromX509Key 决定了落盘的具体编码：

   • 私钥：BlockTypePKCS8PrivateKey，即 PEM 头-----BEGIN PRIVATE KEY-----（PKCS#8 / DER）；
   • 公钥：BlockTypePKIXPublicKey，即-----BEGIN PUBLIC KEY-----（SubjectPublicKeyInfo / DER）。

   所有密钥文件均通过 WritePEMBlocksToPath 以os.OpenFile(..., 0600)打开创建——文件权限固定为 0600，保证私钥不被同机其他用户读取。

测试用例印证行为

internal/commands/crypto_test.go 中的ShouldSucceedPairEd25519子测试直接覆盖了本命令：构造newCryptoGenerateCmd(cmdCtx, cmdUsePair, cmdUseEd25519)，挂载到pair → ed25519的命令层级上，设置--directory为临时目录后执行CryptoGenerateRunE，断言无错误且输出包含Ed25519。同文件 L827 附近还将其纳入ShouldCreatePairEd25519的表驱动用例中。这印证了文档中"生成 Ed25519 密钥对"的语义与实现一致。

实战：生成可复用的 Ed25519 密钥对

完整可复制的示例（在临时目录生成，随后用 openssl 验证格式）：

authelia crypto pair ed25519 generate -d ./keys # 查看生成的文件 ls ./keys # private.pem public.pem # 用 openssl 校验格式（PKCS#8 私钥 / SPKI 公钥） openssl pkey -in ./keys/private.pem -noout -text | head -n 3 openssl pkey -pubin -in ./keys/public.pem -noout -text | head -n 3

也可以自定义文件名：

authelia crypto pair ed25519 generate \ -d ./keys \ --file.private-key oidc_signing.pem \ --file.public-key oidc_signing.pub

注意事项与限制：

• 命令本身不读取也不要求加载配置文件；-d不指定时文件落在当前工作目录；
• 目标文件已存在时会被截断重写（O_TRUNC），不会追加；
• 生成的 PEM 是标准 PKCS#8 / SPKI 编码，可被 OpenSSL 3.x 及多数 Go/Java 生态直接解析；
• 若你的目标是用这对密钥为 OIDC Provider 签名，可将private.pem内容对应到配置中 OIDCjson_web_keys的 Ed25519 私钥项（该类型受 identity_providers.go 校验逻辑支持）。

相关命令（SEE ALSO）

参考文档"SEE ALSO"部分指出的直接关联命令：

• authelia crypto pair ed25519 — 执行 Ed25519 密钥对密码学操作（本文命令的父级，其下仅含 generate 子命令）；
• 同族平级命令：authelia crypto pair rsa generate、authelia crypto pair ecdsa generate、authelia crypto pair mldsa generate（后者为后量子 ML-DSA 参数化算法）；
• 证书方向对应命令：authelia crypto certificate ed25519 generate，支持自签名、CA 签发与链 bundle 输出，与本命令共享私钥生成逻辑。

总结：authelia crypto pair ed25519 generate是一个轻量、确定性的密钥材料生成工具——固定的 Ed25519 算法、可配置的输出目录与文件名、0600 权限的 PKCS#8/SPKI 双文件输出，适合快速为 OIDC 签名等场景准备密钥对；而源码层面的legacy标志短路行为与随机数提供者注入设计，则帮助你在阅读其他算法分支（RSA/ECDSA/ML-DSA）文档时理解整套 crypto 命令族的统一架构。

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia