找回密码
 立即注册
首页 业界区 业界 c# ACME client

c# ACME client

谧怏弦 昨天 16:31
ACME 协议是一种开放标准,旨在实现数字证书颁发和续订流程的自动化,它彻底改变了证书管理。ACME 的开发旨在简化整个流程,已被许多证书颁发机构 (CA) 广泛采用,并已成为互联网标准 (RFC 8555).
为了充分理解ACME协议考虑如何让代理更方便使用ACME协议申请TLS/SSL证书,本人照着LettuceEncrypt 和 certes 从0实现了一遍 ACME协议client以及如何在asp.net core 中集成ACME申请管理。
本文接下来会详细说明相关内容。
ACME协议内容

这里简要描述一下协议内容,方便大家理解,详细还是得看协议原文。
一个简要ACME协议申请流程大致如下
  1. client  -- 0. 申请账号 -->                      ACME服务器
  2.     |    <-- 账号信息 --                            |
  3.    
  4.     |    -- 1. 创建证书申请订单 -->                  |
  5.         <-- 订单信息 --  
  6.     |   -- 2. 选择http/dns/tls中任意之一验证方式 -->  |
  7.         <-- 返回验证信息
  8.     |  -- 3. 部署验证信息
  9.         <---|
  10.     |  -- 4. 告知可以进行验证行为                     |
  11.              异步进行验证,成功则标明订单可以生成证书 --|                 
  12.                                        | -->
  13.     |  -- 4.1 client 可轮询api 确认验证结果
  14.     |  -- 5.验证通过提交CSR最终确定订单 -->            |
  15.     |  -- 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. 下。 然后 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
配置示例
  1. {
  2.   "pebble": {
  3.     "listenAddress": "0.0.0.0:14000",
  4.     "managementListenAddress": "0.0.0.0:15000",
  5.     "certificate": "D:\\Program Files\\tool\\pebble\\certs\\localhost\\cert.pem",
  6.     "privateKey": "D:\\Program Files\\tool\\pebble\\certs\\localhost\\key.pem",
  7.     "httpPort": 80,
  8.     "tlsPort": 443,
  9.     "ocspResponderURL": "",
  10.     "externalAccountBindingRequired": false,
  11.     "domainBlocklist": ["blocked-domain.example"],
  12.     "retryAfter": {
  13.         "authz": 3,
  14.         "order": 5
  15.     },
  16.     "profiles": {
  17.       "default": {
  18.         "description": "The profile you know and love",
  19.         "validityPeriod": 7776000
  20.       },
  21.       "shortlived": {
  22.         "description": "A short-lived cert profile, without actual enforcement",
  23.         "validityPeriod": 518400
  24.       }
  25.     }
  26.   }
  27. }
复制代码
启动命令
  1. .\pebble.exe -config .\pebble-config.json
复制代码
命令行

安装命令行
  1. dotnet tool install --global VKProxy.Cli
复制代码
  1. // 测试ACME服务访问协议
  2. vkproxy acme terms --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir
  3. // output:
  4. // data:text/plain,Do what thou wilt
复制代码
  1. // 生成pem格式账号密钥到 accountkey 文件,acme协议默认是通过密钥关联账号
  2. vkproxy acme account key --algorithm ES256 --output accountkey --format pem
  3. // accountkey 文件内容:
  4. // -----BEGIN EC PRIVATE KEY-----
  5. // MHcCAQEEIKAVlrieijZYRLawRZhNCTfQU++umiQD1TcFCv1POgQboAoGCCqGSM49
  6. // AwEHoUQDQgAEPhWnyoiS01MdguO4NA/4RmXO0GEFAg7a9F08KwjILDZPNNNy8XTj
  7. // WyUU6j4IZUbt/SM53QJXNEEYqdfDU53jag==
  8. // -----END EC PRIVATE KEY-----
复制代码
  1. // 新建account账号
  2. 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
  3. // output:
  4. // Location: https://127.0.0.1:14000/my-account/359a2c1419c73551
  5. // Account: {"status":"valid","contact":["mailto:test@t.org"],"orders":"https://127.0.0.1:14000/list-orderz/359a2c1419c73551"}
复制代码
  1. // 新建订单
  2. 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
  3. // output:
  4. // https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA
  5. // {"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"}
复制代码
  1. // 使用 http 方式验证
  2. 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
  3. // output:
  4. // {"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"}}
  5. // 这里就要求我们部署一个处理challengeUri 的api `GET http://kubernetes.docker.internal/.well-known/acme-challenge/aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0` 返回 challengeTxt `aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0.z1pFvCHE8G1C_w6FrgJqy-YK2cUpLAFgtFzMx4bKsjg`
  6. // 比如 部署一个 asp.net core 程序, 它包含如下内容
  7. // app.Map("/.well-known/acme-challenge", mapped =>
  8. // {
  9. //     mapped.Use(async (HttpContext c, Func<Task> next) =>
  10. //     {
  11. //         string value = "aHBa1xzb32c_VvS5Lsi8s6pIB7JeyqHxIQ4C490jDH0.z1pFvCHE8G1C_w6FrgJqy-YK2cUpLAFgtFzMx4bKsjg";
  12. //         c.Response.ContentLength = value?.Length ?? 0;
  13. //         c.Response.ContentType = "application/octet-stream";
  14. //         await c.Response.WriteAsync(value);
  15. //         await c.Response.CompleteAsync();
  16. //     });
  17. // });
复制代码
  1. // 部署好服务后,告知acme验证
  2. 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
  3. // output:
  4. // {"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}}
  5. // 这里可以看到 "status":"processing"
复制代码
  1. // 通过list查看
  2. vkproxy acme order list --key accountkey --dangerous-certificate true --timeout 00:10:00 --server https://127.0.0.1:14000/dir
  3. // output:
  4. // https://127.0.0.1:14000/my-order/KP92OBeu8Loim2er5K_ugWLtjGsdntMMzL28mDPhbmA
  5. // {"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"}
  6. // 这里可以看到 "status":"ready" 说明验证成功,证书可以下载了
复制代码
  1. // 下载证书,因为 pebble是本地测试服务,无合法根证书,所以要多添加 --additional-issuer issuer.txt ,issuer.txt内容来自 pebble 服务 https://127.0.0.1:15000/roots/0
  2. 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
  3. // output:
  4. // cert.pem
  5. // -----BEGIN CERTIFICATE-----
  6. // MIICYDCCAUigAwIBAgIIT4B4lP9vtcQwDQYJKoZIhvcNAQELBQAwKDEmMCQGA1UE
  7. // AxMdUGViYmxlIEludGVybWVkaWF0ZSBDQSA0NzA1OTUwHhcNMjUwNzI2MDczMzQ2
  8. // WhcNMjUwODAxMDczMzQ1WjAAMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExpcZ
  9. // fAZJgCeZ6iXBWmGUvwzq+RqmtUQG8jO2JEpIzTPmBHWQdLvWBiCrZQ5ssF64e44D
  10. // UbiVbMExvpX5GIUNDaOBgDB+MA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggr
  11. // BgEFBQcDATAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFOAW+aaPdbX8v+N58YWB
  12. // w5Umg3luMCgGA1UdEQEB/wQeMByCGmt1YmVybmV0ZXMuZG9ja2VyLmludGVybmFs
  13. // MA0GCSqGSIb3DQEBCwUAA4IBAQBWylL5NhRQzJ/m7n7GUhyKEM0jvybH5uNkRu9V
  14. // NR2hQdz/rPc8bw+9N3z3iNHkn65V9W6iC9xlwXXD7jAiYmtf3LLhYvkenbfJA72d
  15. // f8j5brIM+3IYAnLCMkkyIsFfSMfj9pwrPt/qMjkxFq2QmoFsgPQgx/xImU+OiKKP
  16. // t1lWaAMP/qiNWWbtRSyZ51C3RGNIVH0q+JoSRVgkbRXoxWueQted3YkBV8VDbbIW
  17. // o0Jk6Y6xBeNFx1Lz5yqa3xnotE9m7VFTxlkaHLRkGDoO0dgj+3FHK+0XLoNt8jgN
  18. // b9RgzCxAIBxkAlvx5VJOpApFTJhXR6hvDwyKmVvyXbZbx/7A
  19. // -----END CERTIFICATE-----
  20. // -----BEGIN PUBLIC KEY-----
  21. // MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAExpcZfAZJgCeZ6iXBWmGUvwzq+Rqm
  22. // tUQG8jO2JEpIzTPmBHWQdLvWBiCrZQ5ssF64e44DUbiVbMExvpX5GIUNDQ==
  23. // -----END PUBLIC KEY-----
  24. // -----BEGIN PRIVATE KEY-----
  25. // MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg6efLajrFYCnWy4i3
  26. // YW5Mc1L1h04oWat/786OQEh+1JihRANCAATGlxl8BkmAJ5nqJcFaYZS/DOr5Gqa1
  27. // RAbyM7YkSkjNM+YEdZB0u9YGIKtlDmywXrh7jgNRuJVswTG+lfkYhQ0N
  28. // -----END PRIVATE KEY-----
  29. 这就是证书所有内容了
复制代码
asp.net core 中使用

只需配置好 acme 相关设置即可启动, 如
  1. var builder = WebApplication.CreateBuilder(args);
  2. builder.Services.AddControllers();
  3. builder.Services.AddOpenApi();
  4. builder.Services.AddAcmeChallenge(o =>
  5. {
  6.     o.AllowedChallengeTypes = VKProxy.ACME.AspNetCore.ChallengeType.Http01;
  7.     o.RenewDaysInAdvance = TimeSpan.FromDays(2);
  8.     o.Server = new Uri("https://127.0.0.1:14000/dir");
  9.     o.DomainNames = new[] { "kubernetes.docker.internal" };
  10.     o.NewAccount(new string[] { "mailto:test@xxx.com" });
  11.     o.AdditionalIssuers = new[] {"""
  12.             -----BEGIN CERTIFICATE-----
  13.             MIIDGzCCAgOgAwIBAgIIU3M7k6+spYMwDQYJKoZIhvcNAQELBQAwIDEeMBwGA1UE
  14.             AxMVUGViYmxlIFJvb3QgQ0EgMDYyYzdjMCAXDTI1MDcyNjA3MDA1MVoYDzIwNTUw
  15.             NzI2MDcwMDUxWjAgMR4wHAYDVQQDExVQZWJibGUgUm9vdCBDQSAwNjJjN2MwggEi
  16.             MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZKIeNyaVFwuVOSc+3Q3bSznnf
  17.             QLDtUHnpwwzY6VaCW5x/M+zK4ykrIUJvC8qE55TL7YmBnJ5uT0DDsjLoZAWudRGS
  18.             UKvivcoEWectl2YfhUSCqw1LbTuK52UQTWNNwfe+1rmFPs2C3yyfEA78221SsQsj
  19.             FfbTZkhLgDpajtSLs9yZy+wEael8xvdMAO+REm9I8sCoK31DEs3ZNQBcrSDyT9mz
  20.             URhzDRahov7bg2MJmBxZH8ICfINd1yZA9kNghLtaRSRLF3JZWcjCr4H1MdjlJFDY
  21.             pQzfa7ZHCHW1fzwdRvi/zjASKvYAkr+arweQSYIqKrs9wN+ah09uEhztOz59AgMB
  22.             AAGjVzBVMA4GA1UdDwEB/wQEAwIChDATBgNVHSUEDDAKBggrBgEFBQcDATAPBgNV
  23.             HRMBAf8EBTADAQH/MB0GA1UdDgQWBBSH6Q9bP8CGt5JpTCMMNZj4j/DiqDANBgkq
  24.             hkiG9w0BAQsFAAOCAQEAryVZdW8KihxLrh4yRuLbIXpjyWacoblvUrWwIQ5vnwwt
  25.             RDoo0mHlYVOxo0ueiUQ4vi5kkGZk7VEsDXi6GV+KT/maupq6Hr+o6drKDO8iYA33
  26.             XuDCNOgfPOXusmiPJFCm07Ah+yV3BxLWMl3azbuiGIWyRZI+fzdnGD1Rh1vPXtI8
  27.             3JgSyqOrNLBQUVMfdhEAYNZrlFBuqUbxXEvA24IL2UgNpYTwAn2iYCcg2zpw5E/c
  28.             DtjJTHO5x+uyXsaRQDXkJ9OZbeil691JcJH7TNxAJVe5N46JFdIf7ELvyJek/K5/
  29.             xted2WWSLd/WQ2UPxxdfceRE1IDH0X88kk/OmmzujA==
  30.             -----END CERTIFICATE-----
  31.             """
  32. };
  33. }, c =>
  34. {
  35.     c.HttpClientConfig = new VKProxy.Config.HttpClientConfig()
  36.     {
  37.         DangerousAcceptAnyServerCertificate = true
  38.     };
  39. });
  40. var app = builder.Build();
  41. app.UseAuthorization();
  42. app.MapControllers();
  43. app.Run();
复制代码
打开debug log, 可以看到相关申请证书的log
  1. info: VKProxy.ACME.AspNetCore.AcmeState[0]
  2.       Using account https://127.0.0.1:14000/my-account/43cc0ec8ef818d32
  3. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  4.       Creating new order for a certificate
  5. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  6.       Validate Http01 for kubernetes.docker.internal
  7. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  8.       GetAuthorization kubernetes.docker.internal
  9. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  10.       GetAuthorization kubernetes.docker.internal
  11. dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0]
  12.       Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU
  13. dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0]
  14.       Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU
  15. dbug: VKProxy.ACME.AspNetCore.HttpChallengeResponseMiddleware[0]
  16.       Confirmed challenge request for vnEH5-HvtTiFvkygIBO6Njmbu6YY7-l9DXyrCwwmSMU
  17. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  18.       GetAuthorization kubernetes.docker.internal
  19. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  20.       Creating cert for kubernetes.docker.internal
  21. warn: VKProxy.ACME.AspNetCore.ServerCertificateSelector[0]
  22.       Failed to validate certificate for  (AD6C43DE80E1E3FB8975F0FC2EE2E545FC42DD10). This could cause an outage of your app.
  23. dbug: VKProxy.ACME.AspNetCore.AcmeState[0]
  24.       Checking certificates' renewals for kubernetes.docker.internal
复制代码
证书已经被加载到 asp.net core 中, 所以https 请求将会看到使用的 pebble的证书
Certificate CN
Issuer CN
Pebble Intermediate CA 470595
比如请求
  1. curl --location 'https://localhost:443/WeatherForecast' \
  2. --header 'Host: kubernetes.docker.internal'
复制代码
不过在 asp.net core 这样使用证书,个人并不推荐,这种方式存在一些问题

  • 实例需要访问ACME 服务,存在额外网络维护和安全的成本
  • ACME 服务通常存在一些限流,以避免攻击或滥用,当实例很多或反复启动容易产生问题
  • 这样使用就会导致同一域名存在很多证书,一旦某一实例无法更新证书,实例就会产生问题,人工处理可能比较麻烦
合理做法可以是有单独程序提供证书管理的功能,证书更新则可以在变更后由管理程序调用 代理程序api进行更新。
后面有空会尝试一下
VKProxy 是使用c#开发的基于 Kestrel 实现 L4/L7的代理(感兴趣的同学烦请点个github小赞赞呢)

来源:程序园用户自行投稿发布,如果侵权,请联系站长删除
免责声明:如果侵犯了您的权益,请联系站长,我们会及时删除侵权内容,谢谢合作!
您需要登录后才可以回帖 登录 | 立即注册