c# ACME client

SEO教程2025-07-2850
    正在检查是否收录...

c# ACME client

ACME 协议是一种开放标准，旨在实现数字证书颁发和续订流程的自动化，它彻底改变了证书管理。ACME 的开发旨在简化整个流程，已被许多证书颁发机构 (CA) 广泛采用，并已成为互联网标准 (RFC 8555).

为了充分理解ACME协议考虑如何让代理更方便使用ACME协议申请TLS/SSL证书，本人照着LettuceEncrypt 和 certes 从0实现了一遍 ACME协议client以及如何在asp.net core 中集成ACME申请管理。

本文接下来会详细说明相关内容。

ACME协议内容

这里简要描述一下协议内容，方便大家理解，详细还是得看协议原文。

一个简要ACME协议申请流程大致如下

client -- 0. 申请账号 --> ACME服务器 | <-- 账号信息 -- | | -- 1. 创建证书申请订单 --> | <-- 订单信息 -- | -- 2. 选择http/dns/tls中任意之一验证方式 --> | <-- 返回验证信息 | -- 3. 部署验证信息 <---| | -- 4. 告知可以进行验证行为 | 异步进行验证，成功则标明订单可以生成证书 --| | --> | -- 4.1 client 可轮询api 确认验证结果 | -- 5.验证通过提交CSR最终确定订单 --> | | -- 6. 下载证书 --> |

不同验证行为如下

  • http

    这是当今最常见的验证方式。 ACME服务器 如Let’s Encrypt 向您的 ACME 客户端提供一个令牌，然后您的 ACME 客户端将在您对 Web 服务器的 http://<你的域名>/.well-known/acme-challenge/（用提供的令牌替换 ）路径上放置指定文件。 该文件包含令牌以及帐户密钥的指纹。 一旦您的 ACME 客户端告诉 ACME服务器 如Let’s Encrypt 文件已准备就绪，ACME服务器 如Let’s Encrypt 会尝试获取它（可能从多个地点进行多次尝试）。 如果我们的验证机制在您的 Web 服务器上找到了放置于正确地点的正确文件，则该验证被视为成功，您可以继续申请颁发证书。 如果验证检查失败，您将不得不再次使用新证书重新申请。

    即 需要提供 GET http://{申请域名}/.well-known/acme-challenge/{验证Token} api ，并返回 {验证Token}.{AccountKey.Thumbprint()}

    ACME服务器会确认返回是否一致

    优点：

    • 它可以轻松地自动化进行而不需要关于域名配置的额外知识。
    • 它允许托管服务提供商为通过 CNAME 指向它们的域名颁发证书。
    • 它适用于现成的 Web 服务器。
    • 它也可以用于验证 IP 地址。

    缺点：

    • 如果您的 ISP 封锁了 80 端口，该验证将无法正常工作（这种情况很少见，但一些住宅 ISP 会这么做）。
    • ACME服务器 如Let’s Encrypt 不允许您使用此验证方式来颁发通配符证书。
    • 您如果有多个 Web 服务器，则必须确保该文件在所有这些服务器上都可用。

  • dns

    此验证方式要求您在该域名下的 TXT 记录中放置特定值来证明您控制域名的 DNS 系统。它允许您颁发通配符证书。 在 ACME服务器 如Let’s Encrypt 为您的 ACME 客户端提供令牌后，您的客户端将创建从该令牌和您的帐户密钥派生的 TXT 记录，并将该记录放在 _acme-challenge.<YOUR_DOMAIN> 下。 然后 ACME服务器 如Let’s Encrypt 将向 DNS 系统查询该记录。 如果找到匹配项，您就可以继续颁发证书！

    优点：

    • 您可以使用此验证方式来颁发包含通配符域名的证书。
    • 即使您有多个 Web 服务器，它也能正常工作。
    • 即使服务器不对公网开放，您也可以通过此方式验证其域名。

    缺点：

    • 在 Web 服务器上保留 API 凭据存在风险。
    • 您的 DNS 提供商可能不提供 API。
    • 您的 DNS API 可能无法提供有关更新时间的信息。
    • IP 地址不能通过此方式验证。
    • vkproxy lib 默认不提供dns自动验证实现，因为DNS 提供商太多了，api 不统一，且可能不提供 API

  • tls

    通过 443 端口上的 TLS 执行。 但是，它使用自定义的 ALPN 协议来确保只有知道此验证类型的服务器才会响应验证请求。 这还允许对此质询类型的验证请求使用与要验证的域名匹配的SNI字段，从而使其更安全。

    这一验证类型并不适合大多数人。 它最适合那些想要执行类似于 HTTP-01 的基于主机的验证，但希望它完全在 TLS 层进行以分离关注点的 TLS 反向代理的作者。

    优点：

    • 它在 80 端口不可用时仍可以正常工作。
    • 它可以完全仅在 TLS 层执行。
    • 它也可以用于验证 IP 地址。

    缺点：

    • 它不支持 Apache、Nginx 和 Certbot，且很可能短期内不会兼容这些软件。
    • 与 HTTP-01 一样，如果您有多台服务器，则它们需要使用相同的内容进行应答。
    • 此方法不能用于验证通配符域名。

pebble 本地测试的acme服务

由于过于贫穷，所以无法在真实的域名/acme服务商/dns服务商等等进行真实的示例

不过好在 letsencrypt.org 开源提供了可以在本地测试的acme服务 pebble

配置示例

{ "pebble": { "listenAddress": "0.0.0.0:14000", "managementListenAddress": "0.0.0.0:15000", "certificate": "D:\\Program Files\\tool\\pebble\\certs\\localhost\\cert.pem", "privateKey": "D:\\Program Files\\tool\\pebble\\certs\\localhost\\key.pem", "httpPort": 80, "tlsPort": 443, "ocspResponderURL": "", "externalAccountBindingRequired": false, "domainBlocklist": ["blocked-domain.example"], "retryAfter": { "authz": 3, "order": 5 }, "profiles": { "default": { "description": "The profile you know and love", "validityPeriod": 7776000 }, "shortlived": { "description": "A short-lived cert profile, without actual enforcement", "validityPeriod": 518400 } } } }

启动命令

.\pebble.exe -config .\pebble-config.json

命令行

安装命令行

dotnet tool install --global VKProxy.Cli 
// 测试ACME服务访问协议 vkproxy acme terms --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // data:text/plain,Do what thou wilt 
// 生成pem格式账号密钥到 accountkey 文件，acme协议默认是通过密钥关联账号 vkproxy acme account key --algorithm ES256 --output accountkey --format pem // accountkey 文件内容： // -----BEGIN EC PRIVATE KEY----- // MHcCAQEEIKAVlrieijZYRLawRZhNCTfQU++umiQD1TcFCv1POgQboAoGCCqGSM49 // AwEHoUQDQgAEPhWnyoiS01MdguO4NA/4RmXO0GEFAg7a9F08KwjILDZPNNNy8XTj // WyUU6j4IZUbt/SM53QJXNEEYqdfDU53jag== // -----END EC PRIVATE KEY----- 
// 新建account账号 vkproxy acme account new --contact mailto:test@t.org --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // Location: https://127.0.0.1:14000/my-account/359a2c1419c73551 // Account: {"status":"valid","contact":["mailto:test@t.org"],"orders":"https://127.0.0.1:14000/list-orderz/359a2c1419c73551"} 
// 新建订单 vkproxy acme order new --domains kubernetes.docker.internal --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA // {"status":"pending","expires":"2025-07-27T07:09:34+00:00","identifiers":[{"type":"dns","value":"kubernetes.docker.internal"}],"authorizations":["https://127.0.0.1:14000/authZ/BmLiNkioTcxg1KCmJrHYiapFyDZAUo87w0wP8WwQYP8"],"finalize":"https://127.0.0.1:14000/finalize-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA"} 
// 使用 http 方式验证 vkproxy acme order authz --domain kubernetes.docker.internal --order https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA --challenge-type http --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // {"location":"https://127.0.0.1:14000/chalZ/t0NRkPk5MiJuc5TQkaf6u9fAZzLV4K9Kwy0ApvrhULs","challengeUri":".well-known/acme-challenge/aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0","challengeTxt":"aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0.z1pFvCHE8G1C_w6FrgJqy-YK2cUpLAFgtFzMx4bKsjg","resource":{"type":"http-01","url":"https://127.0.0.1:14000/chalZ/t0NRkPk5MiJuc5TQkaf6u9fAZzLV4K9Kwy0ApvrhULs","status":"pending","token":"aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0"}} // 这里就要求我们部署一个处理challengeUri 的api `GET http://kubernetes.docker.internal/.well-known/acme-challenge/aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0` 返回 challengeTxt `aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0.z1pFvCHE8G1C_w6FrgJqy-YK2cUpLAFgtFzMx4bKsjg` // 比如 部署一个 asp.net core 程序， 它包含如下内容 // app.Map("/.well-known/acme-challenge", mapped => // { // mapped.Use(async (HttpContext c, Func<Task> next) => // { // string value = "aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0.z1pFvCHE8G1C_w6FrgJqy-YK2cUpLAFgtFzMx4bKsjg"; // c.Response.ContentLength = value?.Length ?? 0; // c.Response.ContentType = "application/octet-stream"; // await c.Response.WriteAsync(value); // await c.Response.CompleteAsync(); // }); // }); 
// 部署好服务后，告知acme验证 vkproxy acme order validate --domain kubernetes.docker.internal --order https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA --challenge-type http --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // {"location":"https://127.0.0.1:14000/chalZ/t0NRkPk5MiJuc5TQkaf6u9fAZzLV4K9Kwy0ApvrhULs","resource":{"result":{"type":"http-01","url":"https://127.0.0.1:14000/chalZ/t0NRkPk5MiJuc5TQkaf6u9fAZzLV4K9Kwy0ApvrhULs","status":"processing","token":"aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0"},"id":1,"status":"ranToCompletion","isCanceled":false,"isCompleted":true,"isCompletedSuccessfully":true,"creationOptions":"none","isFaulted":false}} // 这里可以看到 "status":"processing" 
// 通过list查看 vkproxy acme order list --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA // {"status":"ready","expires":"2025-07-27T07:09:34+00:00","identifiers":[{"type":"dns","value":"kubernetes.docker.internal"}],"authorizations":["https://127.0.0.1:14000/authZ/BmLiNkioTcxg1KCmJrHYiapFyDZAUo87w0wP8WwQYP8"],"finalize":"https://127.0.0.1:14000/finalize-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA"} // 这里可以看到 "status":"ready" 说明验证成功，证书可以下载了 
// 下载证书，因为 pebble是本地测试服务，无合法根证书，所以要多添加 --additional-issuer issuer.txt ，issuer.txt内容来自 pebble 服务 https://127.0.0.1:15000/roots/0 vkproxy acme order finalize --algorithm ES256 --format pem --output cert --additional-issuer issuer.txt --domain kubernetes.docker.internal --order https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA --challenge-type http --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir // output: // cert.pem // -----BEGIN CERTIFICATE----- // MIICYDCCAUigAwIBAgIIT4B4lP9vtcQwDQYJKoZIhvcNAQELBQAwKDEmMCQGA1UE // AxMdUGViYmxlIEludGVybWVkaWF0ZSBDQSA0NzA1OTUwHhcNMjUwNzI2MDczMzQ2 // WhcNMjUwODAxMDczMzQ1WjAAMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExpcZ // fAZJgCeZ6iXBWmGUvwzq+RqmtUQG8jO2JEpIzTPmBHWQdLvWBiCrZQ5ssF64e44D // UbiVbMExvpX5GIUNDaOBgDB+MA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggr // BgEFBQcDATAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFOAW+aaPdbX8v+N58YWB // w5Umg3luMCgGA1UdEQEB/wQeMByCGmt1YmVybmV0ZXMuZG9ja2VyLmludGVybmFs // MA0GCSqGSIb3DQEBCwUAA4IBAQBWylL5NhRQzJ/m7n7GUhyKEM0jvybH5uNkRu9V // NR2hQdz/rPc8bw+9N3z3iNHkn65V9W6iC9xlwXXD7jAiYmtf3LLhYvkenbfJA72d // f8j5brIM+3IYAnLCMkkyIsFfSMfj9pwrPt/qMjkxFq2QmoFsgPQgx/xImU+OiKKP // t1lWaAMP/qiNWWbtRSyZ51C3RGNIVH0q+JoSRVgkbRXoxWueQted3YkBV8VDbbIW // o0Jk6Y6xBeNFx1Lz5yqa3xnotE9m7VFTxlkaHLRkGDoO0dgj+3FHK+0XLoNt8jgN // b9RgzCxAIBxkAlvx5VJOpApFTJhXR6hvDwyKmVvyXbZbx/7A // -----END CERTIFICATE----- // -----BEGIN PUBLIC KEY----- // MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExpcZfAZJgCeZ6iXBWmGUvwzq+Rqm // tUQG8jO2JEpIzTPmBHWQdLvWBiCrZQ5ssF64e44DUbiVbMExvpX5GIUNDQ== // -----END PUBLIC KEY----- // -----BEGIN PRIVATE KEY----- // MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg6efLajrFYCnWy4i3 // YW5Mc1L1h04oWat/786OQEh+1JihRANCAATGlxl8BkmAJ5nqJcFaYZS/DOr5Gqa1 // RAbyM7YkSkjNM+YEdZB0u9YGIKtlDmywXrh7jgNRuJVswTG+lfkYhQ0N // -----END PRIVATE KEY----- 这就是证书所有内容了

asp.net core 中使用

只需配置好 acme 相关设置即可启动， 如

var builder = WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddOpenApi(); builder.Services.AddAcmeChallenge(o => { o.AllowedChallengeTypes = VKProxy.ACME.AspNetCore.ChallengeType.Http01; o.RenewDaysInAdvance = TimeSpan.FromDays(2); o.Server = new Uri("https://127.0.0.1:14000/dir"); o.DomainNames = new[] { "kubernetes.docker.internal" }; o.NewAccount(new string[] { "mailto:test@xxx.com" }); o.AdditionalIssuers = new[] {""" -----BEGIN CERTIFICATE----- MIIDGzCCAgOgAwIBAgIIU3M7k6+spYMwDQYJKoZIhvcNAQELBQAwIDEeMBwGA1UE AxMVUGViYmxlIFJvb3QgQ0EgMDYyYzdjMCAXDTI1MDcyNjA3MDA1MVoYDzIwNTUw NzI2MDcwMDUxWjAgMR4wHAYDVQQDExVQZWJibGUgUm9vdCBDQSAwNjJjN2MwggEi MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZKIeNyaVFwuVOSc+3Q3bSznnf QLDtUHnpwwzY6VaCW5x/M+zK4ykrIUJvC8qE55TL7YmBnJ5uT0DDsjLoZAWudRGS UKvivcoEWectl2YfhUSCqw1LbTuK52UQTWNNwfe+1rmFPs2C3yyfEA78221SsQsj FfbTZkhLgDpajtSLs9yZy+wEael8xvdMAO+REm9I8sCoK31DEs3ZNQBcrSDyT9mz URhzDRahov7bg2MJmBxZH8ICfINd1yZA9kNghLtaRSRLF3JZWcjCr4H1MdjlJFDY pQzfa7ZHCHW1fzwdRvi/zjASKvYAkr+arweQSYIqKrs9wN+ah09uEhztOz59AgMB AAGjVzBVMA4GA1UdDwEB/wQEAwIChDATBgNVHSUEDDAKBggrBgEFBQcDATAPBgNV HRMBAf8EBTADAQH/MB0GA1UdDgQWBBSH6Q9bP8CGt5JpTCMMNZj4j/DiqDANBgkq hkiG9w0BAQsFAAOCAQEAryVZdW8KihxLrh4yRuLbIXpjyWacoblvUrWwIQ5vnwwt RDoo0mHlYVOxo0ueiUQ4vi5kkGZk7VEsDXi6GV+KT/maupq6Hr+o6drKDO8iYA33 XuDCNOgfPOXusmiPJFCm07Ah+yV3BxLWMl3azbuiGIWyRZI+fzdnGD1Rh1vPXtI8 3JgSyqOrNLBQUVMfdhEAYNZrlFBuqUbxXEvA24IL2UgNpYTwAn2iYCcg2zpw5E/c DtjJTHO5x+uyXsaRQDXkJ9OZbeil691JcJH7TNxAJVe5N46JFdIf7ELvyJek/K5/ xted2WWSLd/WQ2UPxxdfceRE1IDH0X88kk/OmmzujA== -----END CERTIFICATE----- """ }; }, c => { c.HttpClientConfig = new VKProxy.Config.HttpClientConfig() { DangerousAcceptAnyServerCertificate = true }; }); var app = builder.Build(); app.UseAuthorization(); app.MapControllers(); app.Run();

打开debug log， 可以看到相关申请证书的log

info: VKProxy.ACME.AspNetCore.AcmeState[0] Using account https://127.0.0.1:14000/my-account/43cc0ec8ef818d32 dbug: VKProxy.ACME.AspNetCore.AcmeState[0] Creating new order for a certificate dbug: VKProxy.ACME.AspNetCore.AcmeState[0] Validate Http01 for kubernetes.docker.internal dbug: VKProxy.ACME.AspNetCore.AcmeState[0] GetAuthorization kubernetes.docker.internal dbug: VKProxy.ACME.AspNetCore.AcmeState[0] GetAuthorization kubernetes.docker.internal dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0] Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0] Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0] Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU dbug: VKProxy.ACME.AspNetCore.AcmeState[0] GetAuthorization kubernetes.docker.internal dbug: VKProxy.ACME.AspNetCore.AcmeState[0] Creating cert for kubernetes.docker.internal warn: VKProxy.ACME.AspNetCore.ServerCertificateSelector[0] Failed to validate certificate for (AD6C43DE80E1E3FB8975F0FC2EE2E545FC42DD10). This could cause an outage of your app. dbug: VKProxy.ACME.AspNetCore.AcmeState[0] Checking certificates' renewals for kubernetes.docker.internal

证书已经被加载到 asp.net core 中， 所以https 请求将会看到使用的 pebble的证书

Certificate CN
Issuer CN
Pebble Intermediate CA 470595

比如请求

curl --location 'https://localhost:443/WeatherForecast' \ --header 'Host: kubernetes.docker.internal'

不过在 asp.net core 这样使用证书，个人并不推荐，这种方式存在一些问题

  • 实例需要访问ACME 服务，存在额外网络维护和安全的成本
  • ACME 服务通常存在一些限流，以避免攻击或滥用，当实例很多或反复启动容易产生问题
  • 这样使用就会导致同一域名存在很多证书，一旦某一实例无法更新证书，实例就会产生问题，人工处理可能比较麻烦

合理做法可以是有单独程序提供证书管理的功能，证书更新则可以在变更后由管理程序调用 代理程序api进行更新。
后面有空会尝试一下

VKProxy 是使用c#开发的基于 Kestrel 实现 L4/L7的代理（感兴趣的同学烦请点个github小赞赞呢）

© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
微博 QQ 复制链接

评论

昵称
邮箱
主页