使用 lego 的 INWX DNS Provider 签发通配符证书：配置、2FA 与源码级原理

网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载本文以 lego 项目中 INWX DNS Provider 官方文档 为核心结合 inwx.go、inwx_test.go 等源码完整讲解如何通过 INWX Dom Robot API 完成 DNS-01 挑战并签发含通配符证书。读完本文你将掌握 INWX Provider 的全部环境变量、2FA 处理机制、沙箱模式以及底层挑战流程实现。INWX 是德国域名注册商其 Dom Robot 提供 XML-RPC 风格的 API 接口。lego 自 v2.0.0 起内置inwxDNS Provider代码标识inwx可在签发证书时自动创建/清理用于 DNS-01 挑战的 TXT 记录从而支持*.example.com这类通配符证书的自动化签发与续期。快速开始签发含通配符的证书使用 INWX Provider 的核心命令如下示例摘自 zz_gen_inwx.mdINWX_USERNAMExxxxxxxxxx \ INWX_PASSWORDyyyyyyyyyy \ lego run --dns inwx -d *.example.com -d example.com # 启用 2FA 时需要额外提供共享密钥 INWX_USERNAMExxxxxxxxxx \ INWX_PASSWORDyyyyyyyyyy \ INWX_SHARED_SECRETzzzzzzzzzz \ lego run --dns inwx -d *.example.com -d example.com其中--dns inwx指定使用 INWX Provider-d *.example.com -d example.com同时申请通配符域名与根域名两者需同时出现因为通配符证书不覆盖根域名。命令会执行 DNS-01 挑战先在 INWX 中写入_acme-challengeTXT 记录等待 DNS 传播后向 CA 验证签发成功后自动清理记录。除 CLI 外也可使用 YAML 配置文件方式通用 DNS Provider 用法详见 docs/content/obtain/dns01.mdchallenges: inwx: dns: provider: inwx envFile: .env.inwx # 可选从 dotenv 文件加载环境变量 certificates: example: domains: - example.com - *.example.com凭据与环境变量INWX Provider 的全部配置均通过环境变量传递分为两类必需凭据与可选附加配置。必需凭据Credentials环境变量名说明INWX_USERNAMEINWX 账户用户名INWX_PASSWORD账户密码这两个变量是 Provider 初始化的硬性要求。从源码 inwx.go 可见NewDNSProvider()通过env.Get(EnvUsername, EnvPassword)读取任一缺失都会直接返回错误values, err : env.Get(EnvUsername, EnvPassword) if err ! nil { return nil, fmt.Errorf(inwx: %w, err) }对应的错误信息形如some credentials information are missing: INWX_USERNAME,INWX_PASSWORD这组错误场景在 inwx_test.go 的TestNewDNSProvider中有完整的单测覆盖分别验证成功、双缺失、仅缺用户名、仅缺密码四种情况。附加配置Additional Configuration环境变量名说明默认值INWX_SHARED_SECRET与 2FA 相关的共享密钥TOTP 种子无INWX_SANDBOX是否启用沙箱模式布尔值falseINWX_TTLDNS 挑战所用 TXT 记录的 TTL秒300INWX_PROPAGATION_TIMEOUT等待 DNS 传播的最大时长秒360INWX_POLLING_INTERVALDNS 传播检查的时间间隔秒2这些默认值定义在NewDefaultConfig()中inwx.goreturn Config{ TTL: env.GetOrDefaultInt(EnvTTL, 300), // INWX has rather unstable propagation delays, thus using a larger default value PropagationTimeout: env.GetOrDefaultSecond(EnvPropagationTimeout, 6*time.Minute), PollingInterval: env.GetOrDefaultSecond(EnvPollingInterval, dns01.DefaultPollingInterval), Sandbox: env.GetOrDefaultBool(EnvSandbox, false), }注意源码注释明确说明INWX 的 DNS 传播延迟相当不稳定因此PROPAGATION_TIMEOUT默认值取6 * time.Minute360 秒而非 lego 通用的较短默认值。POLLING_INTERVAL则复用dns01.DefaultPollingInterval2 秒。这两个值最终由Timeout()方法返回给 lego 的等待逻辑inwx.gofunc (d *DNSProvider) Timeout() (timeout, interval time.Duration) { return d.config.PropagationTimeout, d.config.PollingInterval }凭据的_FILE后缀与文件引用文档明确说明所有上述环境变量名均可追加_FILE后缀改为从文件读取值而非直接内联明文。例如INWX_USERNAME_FILE/path/to/username \ INWX_PASSWORD_FILE/path/to/password \ lego run --dns inwx -d example.com其中/path/to/username文件内只需包含一行用户名文件内容即值不得有多余内容。该机制由 lego 的 platform/env/env.go 中GetOrFile()实现先尝试读取INWX_USERNAME若为空则回退到INWX_USERNAME_FILE指定的路径读取文件内容。这在容器化、密钥托管等不适合明文暴露凭据的场景下尤其有用。2FA双因素认证处理机制INWX 账户可开启基于 TOTPGoogle Authenticator 风格的双因素认证。开启后除了用户名密码登录还必须提供一次性 TAN 码解锁账户。lego 通过INWX_SHARED_SECRET自动完成这一过程用户无需手动干预。其实现位于 inwx.go 的twoFactorAuth()与computeSleep()func (d *DNSProvider) twoFactorAuth(info *goinwx.LoginResponse) error { if info.TFA ! GOOGLE-AUTH { return nil } if d.config.SharedSecret { return errors.New(two-factor authentication but no shared secret is given) } // INWX forbids re-authentication with a previously used TAN. // To avoid using the same TAN twice, we wait until the next TOTP period. sleep : d.computeSleep(time.Now()) if sleep ! 0 { log.Info(inwx: waiting for the next TOTP token, slog.Duration(sleep, sleep)) time.Sleep(sleep) } now : time.Now() tan, err : totp.GenerateCode(d.config.SharedSecret, now) ... d.previousUnlock now.Truncate(30 * time.Second) return d.client.Account.Unlock(tan) }关键细节登录响应中TFA GOOGLE-AUTH时才会触发 2FA 流程若账户未开启 2FA 则直接跳过。若已开启 2FA 但未提供INWX_SHARED_SECRET会直接报错two-factor authentication but no shared secret is given。INWX 禁止复用同一个 TANTOTP 每 30 秒轮换一次。若上一次解锁发生在本 TOTP 周期内computeSleep()会计算距下一周期previousUnlock 30s的剩余时间并time.Sleep确保使用全新的 TAN。previousUnlock字段被截断到 30 秒粒度记录。该等待逻辑有专门单测 inwx_test.go例如上一次解锁在06:29:30Z当前时刻06:29:40Z时计算出的等待时长为 20 秒。因此在启用 2FA 的账户上务必同时配置INWX_SHARED_SECRET即你在 Google Authenticator 等应用中绑定的 Base32 密钥。沙箱模式SandboxINWX_SANDBOXtrue可切换到 INWX 的沙箱环境用于测试不产生真实 DNS 变更。源码中 inwx.go 的处理为if config.Sandbox { log.Info(inwx: sandbox mode is enabled.) } client : goinwx.NewClient(config.Username, config.Password, goinwx.ClientOptions{Sandbox: config.Sandbox})即以Sandbox选项构造底层 goinwx 客户端。值得注意的坑沙箱模式下 TXT 记录的最小 TTL 是 3600 秒而生产默认 TTL 为 300。因此进行沙箱联调时需显式调大 TTL这一点在 inwx_test.go 的TestLivePresentAndCleanup中体现envTest.Apply(map[string]string{ EnvSandbox: true, EnvTTL: 3600, // In sandbox mode, the minimum allowed TTL is 3600 })该测试同时验证了Present在记录已存在返回 Object exists时不会报错幂等CleanUp能正确删除匹配的记录——对应源码中 Present 对Object exists错误的特殊处理。DNS-01 挑战的底层流程结合源码INWX Provider 实现challenge.Provider接口的三个关键方法完整流程如下Present创建 TXT 记录见 inwx.go通过dns01.GetChallengeInfo计算挑战记录名_acme-challenge.domain与挑战值用dns01.DefaultClient().FindZoneByFqdn自动探测权威 zone将通配符域名规约为可管理的最小父域调用client.Account.Login()登录defer中调用Logout()确保会话释放需要 2FA 时执行twoFactorAuth构造goinwx.NameserverRecordRequest{Domain, Name, Type: TXT, Content: info.Value, TTL: d.config.TTL}调用Nameservers.CreateRecord创建记录若返回 Object exists 视为成功幂等。等待传播lego 按Timeout()返回的(360s, 2s)轮询 DNS直至 TXT 记录在全球权威服务器可见。CleanUp清理 TXT 记录见 inwx.go同样先探测 zone、登录、处理 2FA用Nameservers.Info按Domain Name Type: TXT查询现有记录遍历response.Records找出Content与挑战值一致的recordID调用Nameservers.DeleteRecord(recordID)删除若找不到匹配记录则报错inwx: TXT record not found。底层 HTTP/XML-RPC 通信由 INWX 官方 Go 客户端库github.com/nrdcg/goinwx完成见 inwx.go 的 importProvider 仅负责挑战编排与记录管理。库模式使用编程方式不通过 CLI 时也可以在 Go 代码中直接使用该 Provider与 lego 的 lego/client.go 组合import github.com/go-acme/lego/v4/providers/dns/inwx config : inwx.NewDefaultConfig() config.Username your-username config.Password your-password config.SharedSecret your-totp-secret config.Sandbox false config.TTL 300 provider, err : inwx.NewDNSProviderConfig(config) if err ! nil { log.Fatal(err) } // 将 provider 传入 lego.Client 的 Challenge 配置即可其中NewDNSProviderConfig会校验Username/Password非空否则返回inwx: credentials missing并据Sandbox构造底层客户端inwx.go。若走无参的NewDNSProvider()则必须提前设置好上述环境变量。小结签发命令lego run --dns inwx -d *.example.com -d example.com凭据通过INWX_USERNAME/INWX_PASSWORD注入2FA 账户需加INWX_SHARED_SECRET全部变量均支持_FILE后缀从文件读取适合容器与密钥管理场景生产默认 TTL 300 秒、传播超时 360 秒、轮询间隔 2 秒沙箱模式需将 TTL 调到至少 3600Provider 自动完成登录/登出、TOTP 解锁避免 TAN 复用、TXT 记录创建与清理全程无需人工干预。若需进一步了解 DNS Provider 的通用配置与凭据注入方式如 dotenv 文件、--env-file标志可阅读 docs/content/dns/_index.md 与 docs/content/obtain/dns01.md。赞分享网络安全密码学【免费下载链接】legoLets Encrypt/ACME client and library written in Go项目地址https://gitcode.com/gh_mirrors/le/lego点击查看免费下载相关推荐lego 使用 Beget.com DNS Provider 签发通配符证书配置详解与源码原理lego 使用 Beget.com DNS Provider 签发通配符证书配置详解与源码原理 本指南聚焦 legoLets Encrypt/ACME c网络安全密码学Bytebase Agent 问题追踪规范以 Linear 为唯一事实源用 linctl 驱动 Issue 全生命周期管理Bytebase Agent 问题追踪规范以 Linear 为唯一事实源用 linctl 驱动 Issue 全生命周期管理 本文基于 Bytebase 仓库网络安全密码学lego 使用 Gigahost.no DNS Provider 签发通配符证书完整配置指南与源码原理lego 使用 Gigahost.no DNS Provider 签发通配符证书完整配置指南与源码原理 本文是 legoLets Encrypt/ACME网络安全密码学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考