网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载lego 是使用 Go 语言编写的 Lets Encrypt / ACME 客户端和库。本文围绕其配置文件机制展开.lego.yml或.lego.yaml允许你以声明式 YAML 的方式统一管理服务器、账户、验证方式challenges与多张证书取代逐条命令行参数的手动签发流程。读完本文你将掌握配置文件的完整结构、全部配置项与默认值、最小可运行示例以及配置驱动下证书与账户的归档archive生命周期行为。配置文件解决什么问题当需要管理多张证书例如多域名、多环境、多 ACME 服务器时单纯依靠命令行参数会让命令越来越长、越来越难维护。lego 的配置文件正是为简化多证书管理而设计的它把服务器、账户、验证方式和证书的声明集中在一个 YAML 文件中每次签发只需运行lego runlego 会读取配置文件并完成所有证书的获取、更新与存储。从源码结构看配置系统位于 cmd/internal/configuration由结构定义configuration.go、默认值configuration_defaults.go、加载器configuration_loader.go与校验器configuration_validation.go四部分协作完成。使用配置文件的命令配置文件被以下命令使用lego即lego run按配置签发/续期证书lego certificates revokelego certificates listlego accounts listlego archives listlego archives restore这些命令在启动时会自动加载配置文件其中run命令要求必须基于配置文件工作在 validation.go 中--config标志被明确禁止与run以外的命令行模式混用避免两种配置来源冲突。文件位置与格式配置文件是位于当前工作目录的 YAML 文件文件名二选一.lego.yml.lego.yamllego 在启动时会自动查找并加载。查找逻辑在 configuration_loader.go 的FindDefaultConfigurationFile中实现它依次探测.lego.yml与.lego.yaml按此顺序找到第一个存在且非目录的文件即返回其绝对路径若两者都不存在则返回FileNotFoundError。也可以使用--config标志显式指定配置文件路径lego run --config /path/to/my-config.yml在 setup.go 中可见完整的加载流程loadConfiguration先确定文件路径再ReadConfiguration解析 YAML、ApplyDefaults填充默认值、Validate校验合法性最后设置日志与 User-Agent。加载器在解析时启用了decoder.KnownFields(true)见 configuration_loader.go意味着配置文件中出现未定义的字段会直接报错有助于尽早发现拼写错误。配置文件的整体结构配置文件的顶层由四个命名映射named map加上若干全局项组成每个条目都有一个你自选的名称key和一段配置valueserversACME 服务器定义accountsACME 账户定义challenges验证方式HTTP-01 / TLS-ALPN-01 / DNS-01 / DNS-PERSIST-01定义certificates证书定义它们之间的引用关系是单向的证书通过名称引用账户与验证方式账户通过名称引用服务器。这种按名引用的设计让同一份配置可以复用账户和挑战配置显著减少重复。certificates: my-cert: challenge: my-http # 引用 challenges 段中的 my-http account: my-account # 引用 accounts 段中的 my-account accounts: my-account: server: my-server # 引用 servers 段中的 my-server全局配置项顶层包括字段说明默认值storage数据存储目录路径.lego/当前目录下networkStack网络栈可选ipv6only或ipv4only两者都用userAgent连接 ACME 服务器时使用的 User-Agentlego 相关默认信息log日志级别与格式见下文日志与钩子info/coloredhookspre / deploy / post 钩子命令无配置文件的完整字段参考含全部注释与默认值见 docs/content/references/ref-file/_index.md同时可以用官方 JSON Schema 校验docs/static/lego.jsonschema.json。智能默认值Smart Defaults为了让最小配置足够简洁lego 在ApplyDefaultsconfiguration_defaults.go中注入了一组默认值设置说明存储目录Storage默认为当前目录下的.lego账户服务器Account server未指定时默认使用 Lets Encrypt 生产环境目录https://acme-v02.api.letsencrypt.org/directory证书密钥类型Certificate key type未指定时继承其账户的密钥类型证书账户Certificate account若配置中只定义了一个账户则自动使用该账户证书验证方式Certificate challenge若配置中只定义了一个挑战则自动使用该挑战预定义挑战Predefined challengeshttp-01、tls-alpn-01、dns-persist-01可直接作为挑战名称使用无需额外定义源码层面的默认值细节均来自 configuration_defaults.go账户默认KeyType为EC256见applyAccountsDefaults服务器默认OverallRequestLimit为certificate.DefaultOverallRequestLimit对应文档值 18未配置任何账户时系统会注入一个名为noemailexample.com的默认账户DefaultAccountID服务器指向 Lets Encrypt 生产环境引用http-01/tls-alpn-01/dns-persist-01这些特殊名称时setDefaultHTTP01/setDefaultTLSALPN01/setDefaultDNSPersist01会自动在challenges段中补建对应的默认挑战配置HTTP 监听:80TLS 监听:443证书未指定KeyType时getDefaultCertificateKeyType优先继承账户密钥类型否则回退到EC256。得益于这些默认值获取一张证书的最小配置可以非常精简。最小配置示例四类验证方式以下示例均假设使用 Lets Encrypt默认服务器。只需在项目目录放置.lego.yml并运行lego run即可。HTTP-01# .lego.yml certificates: my-cert: challenge: http-01 domains: - example.comhttp-01是预定义名称lego 会自动使用默认 HTTP 挑战提供方监听:80。TLS-ALPN-01# .lego.yml certificates: my-cert: challenge: tls-alpn-01 domains: - example.comtls-alpn-01同样是预定义名称默认监听:443。DNS-01通配符证书DNS-01 需要真实配置 DNS 提供商因此必须先在challenges段中定义# .lego.yml challenges: my-dns: dns: provider: cloudflare certificates: my-cert: domains: - example.com - *.example.com注意此例中证书条目省略了challenge字段因为配置里只定义了一个挑战my-dns根据智能默认值规则会自动使用它。这是多证书最小配置的典型写法。DNS-01 是签发通配符证书的必备方式。DNS-PERSIST-01DNS-PERSIST-01 是一种可复用的持久化 DNS 挑战先在权威 DNS 写入 TXT 记录并保留供多家 CA 复用其配置与使用方式见独立文档 docs/content/obtain/dnspersist01.md。服务器servers配置servers段用于定义自定义 ACME 服务器例如 Pebble 测试服务器、企业内网 ACME 服务。账户通过server字段按名称引用它。servers: myServer: # ACME 服务器 URL。 # # 必填。 url: https://example.com/dir # ACME 整体请求数限制。 # # 默认: 18 overallRequestLimit: 7 # 跳过对 ACME 服务器的 TLS 校验仅建议测试环境使用。 # # 默认: false tlsSkipVerify: true # HTTP 超时时间秒。 # # 默认: 30 httpTimeout: 60 # 获取证书时的超时时间秒仅在取证书时生效。 # # 默认: 30 certTimeout: 60校验阶段configuration_validation.go 的validateServers会统计每个服务器被账户引用的次数对未被任何账户引用的服务器打印警告帮助发现冗余配置。账户accounts配置定义账户是可选的默认情况下 lego 会自动在 Lets Encrypt ACME 服务器上创建一个账户。只有当你需要换用其他 ACME 服务器、或需要自定义账户属性如密钥类型、EAB时才需要显式定义。# 当账户定义从配置文件中移除时其对应文件会被归档。 # 归档文件在 30 天后被删除。 accounts: myAccount: # ACME 服务器。可以是 # 1. URL # 2. 短代码见 shortcode 说明 # 3. servers 配置段中定义的服务器 ID # # 默认: https://acme-v02.api.letsencrypt.org/directory server: https://example.com/dir # 账户邮箱。 # # 可选。 email: fooexample.com # 生成账户私钥所用的密钥类型。 # # 默认: EC256 keyType: RSA2048 # 是否接受服务条款ToS。 # # 默认: false acceptsTermsOfService: true # 外部账户绑定External Account BindingEAB配置。 # 部分 CA如 ZeroSSL要求提供 EAB 凭证。 # # 可选。 eab: # EAB KID。 # # 必填。 kid: foo # EAB HMAC 密钥。 # # 必填。 hmacKey: foo校验规则configuration_validation.go 的validateAccount要求若配置了eab则kid与hmacKey必须同时提供否则报错keyType必须是受支持的类型。lego 支持的密钥类型定义在 certcrypto/keytypes.goEC256、EC384、RSA2048、RSA3072、RSA4096、RSA8192。证书certificates配置certificates段是配置文件的核心每个条目对应一张或多域名组合的证书。证书通过account与challenge按名引用账户与验证方式。# 当证书定义从配置文件中移除时其对应证书文件会被归档。 # 归档文件在 30 天后被删除。 certificates: # 证书的 ID/名称。 myCert: # 验证方式类型。可以是 # 1. http-01特殊名称使用默认 HTTP 挑战提供方 # 2. tls-alpn-01特殊名称使用默认 TLS-ALPN-01 挑战提供方 # 3. challenges 配置段中定义的挑战 ID # # 必填除非配置中只有一个挑战可自动推断。 challenge: one # 账户 ID/名称。 # 若配置文件中未定义账户则使用默认账户 # 若只定义了一个账户则账户 ID 可省略。 # # 必填。 account: foo # 生成证书所用的密钥类型。 # 未设置时使用账户密钥类型若账户也未定义密钥类型则使用 EC256。 keyType: RSA2048 # 要为其申请证书的域名列表。 # # 与 csr 互斥。 domains: - example.com - *.example.com # 证书签名请求CSR文件路径。 # # 与 domains 互斥。 csr: /tmp/foo.csr # 首选证书链。 # # 可选。 preferredChain: ISRG Root X1 # ACME 服务器 profile。 # # 可选。 profile: tls # 是否在证书中使用 Common NameCN。 # CN 已弃用不建议使用。 # # 可选。 # 默认: false enableCommonName: true # 证书的 notBefore 字段。 # # 可选。 notBefore: # 证书的 notAfter 字段。 # # 可选。 notAfter: # 不把签发者证书附加到新证书上以生成证书包bundle。 # # 默认: false noBundle: true # 在 CSR 与生成的证书中包含 OCSP must-staple TLS 扩展。 # 仅在 CSR 由 lego 生成时有效。 # # 默认: false mustStaple: true # 即使证书请求成功也强制放弃deactivateauthorizations。 # # 默认: false alwaysDeactivateAuthorizations: true # 证书续期相关选项。 # # 可选。 renew: # 若私钥已存在则复用。 # # 可选。 # 默认: false reuseKey: true # 证书剩余多少天时触发续期。 # 默认根据证书生命周期动态计算 # 剩余 1/3 生命周期或短生命周期证书的 1/2 生命周期。 days: 1 # 续期前不添加随机睡眠。 # 若以自动化方式续期不建议使用此选项。 # # 默认: false disableRandomSleep: true # ARI自动续期集成配置。 # # 可选。 ari: # 禁用 ARI 机制。 # # 默认: false disable: true # 对 renewalInfo 端点返回的续期时间愿意等待的最大时长。 # # 默认: 0s waitToRenewDuration: 1m # 额外生成 .pfxPKCS#12文件将 .key、.crt 与签发者 .crt 拼接加密。 # # 可选。 pfx: # 加密 .pfx 文件所用的密码。 # # 必填。 password: xxx # .pfx 文件的加密编码格式。 # 支持DES、RC2、SHA256、PBMAC1 # # 可选。 # 默认: RC2 format: PBMAC1从源码看证书条目最终会在 process_obtain.go 中被转换为实际的 ACME 请求newObtainRequest把keyType、mustStaple、notBefore/notAfter、bundle由noBundle取反、preferredChain、enableCommonName、profile、alwaysDeactivateAuthorizations等字段映射到certificate.ObtainRequestnewSaveOptions则在配置了pfx时额外生成 PKCS#12 文件格式与密码取自pfx.format/pfx.password。若配置了csr则走obtainForCSR分支读取 CSR 文件并调用ObtainForCSR此时会强制关闭 PEM 输出因为没有私钥。校验规则validateCertificates/validateCertificate要点每个证书必须提供domains或csr之一且二者互斥account与challenge必须引用配置中真实存在的名称existInMap检查keyType必须受支持pfx.format必须受支持IsPKCS12Supported实现见 certcrypto/pkcs12.go。验证方式challenges配置challenges段定义可复用的验证方式。一个挑战条目可以包含http、tls、dns、dnsPersist四种子配置中的一种或多种校验要求至少定义一种。challenges: # HTTP-01 挑战配置。 one: http: # 监听地址。 # # 默认: :80 address: :80 # HTTP 服务器启动到挑战校验之间的延迟。 # # 默认: 0s delay: 6s # 当 HTTP-01 在反向代理之后时基于该 HTTP 头进行校验。 # # 可选。 proxyHeader: Host # 将 HTTP-01 的 .well-known/acme-challenge 文件直接写入该 webroot 目录。 # 会禁用内置服务器并要求该目录被公开服务且可访问 .well-known/acme-challenge。 # # 可选。 webroot: /tmp/webroot # 用于 HTTP-01 的 memcached 主机列表挑战写入所有指定主机。 # # 可选。 memcachedHosts: - memcached:11211 # 用于 HTTP-01 的 S3 桶名挑战写入 S3 桶。 s3Bucket: s3-bucket # TLS-ALPN-01 挑战配置。 two: tls: # 监听地址。 # # 默认: :443 address: :443 # TLS 监听器启动到挑战校验之间的延迟。 # # 默认: 0s delay: 6s # DNS-01 挑战配置。 three: dns: # DNS 提供商。 # # 必填。 provider: cloudflare # 存放凭证的 dotenv 文件路径。 # # 可选。 envFile: /tmp/secrets/.env # 传播检查相关配置。 # # 可选。 propagation: # 设为 true 时不等待 TXT 记录在全部权威名称服务器上传播。 # # 默认: false disableAuthoritativeNameservers: true # 设为 true 时不等待 TXT 记录在全部递归名称服务器resolver上传播。 # # 默认: false disableRecursiveNameservers: true # 禁用全部 TXT 记录传播检查改用固定等待时长。 # 强烈不建议使用此选项。 # # 默认: 0 wait: 5s # DNS 超时秒仅用于权威名称服务器查询。 # # 默认: 10 dnsTimeout: 30 # 用于递归CNAME 解析与 apex 域确定时使用的 resolver。 # DNS-01 挑战校验时直接查询权威 DNS 服务器。 # # 语法: host:port。 # # 可选。 # 默认使用系统 resolver无法确定时使用 Cloudflare 的 DNS resolver。 resolvers: - 1.1.1.1:53 # DNS-PERSIST-01 挑战配置。 four: dnsPersist: # 当 CA 提供多个 issuer-domain-name 时覆盖要使用的 issuer-domain-name。 # 必须由挑战提供方支持。 # # 可选。 issuerDomainName: example.com # 为 DNS-PERSIST-01 记录设置可选的 persistUntilRFC3339 时间戳。 # # 可选。 persistUntil: 2020-01-01T00:00:00Z # 传播检查配置含义与 dns.propagation 相同。 propagation: disableAuthoritativeNameservers: true disableRecursiveNameservers: true wait: 5s校验规则validateChallenges/validateChallenge要求每个挑战至少定义一种类型DNS 挑战必须指定providerpropagation.wait与disableAuthoritativeNameservers/disableRecursiveNameservers互斥见validatePropagationExclusiveOptions——因为固定等待与传播检查是两种互斥的策略。DNS 提供商的可选清单非常庞大Cloudflare、AliDNS、Route53、DNSPod、HuaweiCloud、TencentCloud 等数百家可通过lego dnshelp命令或 docs/content/dns 目录下的文档查询使用provider: 名称即可切换。日志与钩子log 与 hooks日志# 日志配置。 # # 可选。 log: # 日志级别。 # # 默认: info level: debug # 日志格式。 # 支持text、json、colored # # 默认: colored format: jsonformat字段由validateLog校验只接受text、json、colored或留空使用默认值三种取值。钩子钩子允许在证书签发流程的关键节点执行外部命令例如签发前停止服务、签发后部署证书# 钩子配置。 # # 可选。 hooks: # 签发前钩子。 pre: # 要执行的命令。 # # 必填。 command: ./my-pre-hook.sh # 命令超时。 # # 可选。 # 默认: 2 分钟。 timeout: 3s # 部署钩子。 deploy: command: ./my-deploy-hook.sh timeout: 3s # 签发后钩子。 post: command: ./my-post-hook.sh timeout: 3s从源码看钩子默认超时由 configuration_defaults.go 的applyDefaultHook注入2 * time.Minute签发流程中钩子的调用顺序为pre→ 获取证书 →deploy→post见 process_obtain.go 中的PreForDomains、Deploy、Post。钩子的详细文档见 docs/content/advanced/hooks.md。归档行为Archive Behavior配置文件不仅驱动签发还驱动生命周期管理当你从配置文件中删除某个条目时lego 会把对应的文件移入归档而不是直接删除从而为误删提供恢复手段删除证书条目该证书的文件被归档删除账户条目该账户的文件被归档删除服务器条目该服务器及其关联账户的文件被归档。归档文件在30 天后被自动清理。归档相关命令# 列出所有已备份的账户与证书 lego archives list # 交互式恢复某个备份命令会询问要恢复的备份文件 lego archives restore更完整的归档操作说明见 docs/content/advanced/archives.md。归档机制实现于 cmd/internal/storage/archiver.go 及配套的archiver_accounts.go、archiver_certificates.go存储层会记录证书/账户的来源为OriginConfiguration配置驱动从而在配置变更时正确触发归档。校验与排错建议由于加载器启用了严格解析配置阶段最容易遇到的问题与对应排查方式如下未定义字段报错YAML 中出现结构体中不存在的字段会解码失败。请对照 docs/content/references/ref-file/_index.md 检查字段拼写。引用悬空证书引用的account/challenge名称不存在会报错existInMap。请检查名称是否一致。必填缺失DNS 挑战缺少provider、证书既无domains也无csr、EAB 缺少kid/hmacKey等都会在校验阶段失败。互斥冲突domains与csr互斥propagation.wait与disableAuthoritativeNameservers/disableRecursiveNameservers互斥。未使用的服务器校验器会对未被任何账户引用的服务器打印警告可据此清理冗余配置。Schema 校验可使用docs/static/lego.jsonschema.json对配置文件做离线校验。总结lego 的配置文件.lego.yml通过servers/accounts/challenges/certificates四层命名映射把 ACME 服务器、账户、验证方式与证书解耦并按名关联配合存储目录、服务器、密钥类型、账户、挑战等一系列智能默认值只需寥寥几行 YAML 即可完成 HTTP-01 / TLS-ALPN-01 / DNS-01 / DNS-PERSIST-01 任一方式的多证书签发。配置驱动的归档行为则为证书与账户的删除提供了自动备份与恢复能力让大规模证书管理变得可声明、可审计、可回滚。赞分享网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载相关推荐如何用 Auth0 为 PostgREST 签发 JWT 完成外部认证如何用 Auth0 为 PostgREST 签发 JWT 完成外部认证 如果你的 PostgREST 目前依靠数据库里的 SQL 函数自行签发令牌而你的应用登网络安全密码学Karakeep 命令行工具CLI完全指南安装、认证配置与书签批量管理实战Karakeep 命令行工具CLI完全指南安装、认证配置与书签批量管理实战 Karakeep自托管书签收藏应用提供了一套轻量级官方 CLI用于在终端后端前端移动开发AI 应用知识管理全文检索MCP 服务CANN Runtime 默认Device与默认Stream机制完全指南配置、生命周期与传参规则CANN Runtime 默认Device与默认Stream机制完全指南配置、生命周期与传参规则 导读 在 CANN Runtime 的日常开发中没有调用CANNAscend人工智能性能剖析系统编程上一篇Velog v1完全解析开发者专属博客平台的核心功能与架构揭秘下一篇toyDB中的编译时错误检查更早发现问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考