CertBot使用文档

​ ACME是"Automatic Certificate Management Environment”（自动证书管理环境）的缩写。ACME是一种用于自动化管理和获取SSL/TLS证书的协议。ACME协议由Internet工程任务组（IETF）定义，并由Let’s Encrypt等证颁发机构广泛采用。

​ ACME提供了一种标准化的方式，使能够自动请求、验证和获取证书，而无需人工干预。完成标准化获取证书流程需要ACME客户端与ACME服务器端进行通信。常见的ACME客户端有acme.sh、certbot等。

​ CertBot的github地址为：https://github.com/certbot/certbot

安装

  • Windows： 通过下载CertBot安装包进行安装
  • Linux: 可通过yum -y install certbot进行安装

控制台执行certbot --version打印出版本信息即安装成功。

$ certbot --version
certbot 2.7.4

注册

使用如下命令注册ACME客户端：

$ certbot register --server https://acme.certcloud.cn/acme/directory --eab-kid J9Lf****** --eab-hmac-key MD8C****** -m sample@qq.com
  • register: 表示这是一个注册账户的命令
  • –server:指定了ACME服务端的地址
  • –eab-kid、–eab-hmac-key：eab参数可从Certcloud控制台-自动化-ACME-设置处获取
  • -m:指定接受通知的邮箱

命令行中打印如下结果即表示注册成功：

$ certbot register --server https://acme.cmc.test/acme/directory --eab-kid ***  --eab-hmac-key *** -m sample@qq.com  
Saving debug log to ***\$(pwd)\letsencrypt.log
Account registered.

手动签发证书

签发证书的命令使用示例如下：

certbot certonly --manual  --domain test.online --server https://acme.certcloud.cn/acme/directory --preferred-challenges dns-01 --key-type rsa
  • certonly: 表示只签发证书，不会自动配置您的服务器软件来使用这些证书
  • –manual： 表示手动验证您拥有指定域名的控制权
  • –domain：指定要签发证书的域名
  • –server: 指定ACME服务端地址
  • –preferred-challenges ： 用于指定验证方式：dns-01表示采用dns验证，http-01表示采用http文件验证
  • –key-type：指定密钥类型

不推荐采用上述方式进行签发证书，这意味着您每次在证书快要过期时都要执行该命令进行手动验证签发证书。

​ 我们可以使用dns插件的方式实现自动验证并签发证书, 不同的DNS解析服务提供商有不同的配置。请选择您的域名所在解析服务器相对应的插件命令执行。

自动签发证书

Amazon Route53

您的域名在AWS Route53解析，可以使用如下命令：

certbot certonly --dns-route53 -d example.com -d *.example.com -d a.com -server https://acme.certcloud.cn/acme/directory --preferred-challenges dns-01 --key-type rsa

需要配置环境变量如下：

export  AWS_ACCESS_KEY_ID="<key id>"
export  AWS_SECRET_ACCESS_KEY="<secret>"

下面用国内AWS获取id和secret进行说明，国外AWS也是类似操作。过程如下：

  1. 点击跳转国内AWS IAM控制台,或搜索服务IAM进入
  2. 在左侧导航栏，选择访问管理 > 用户
  3. 创建用户并点击用户名进入或直接点击用户名进入
  4. 选择安全凭证 > 访问密钥
  5. 创建访问密钥

创建过程参考下列图例：

AWS密钥入口

AWS密钥

​ 此时密钥还不能正常使用，还需要给密钥所在用户授权。在左侧导航栏选择访问管理 > 策略，点击创建策略,如下图所示：

AWS创建策略

策略编辑器选择JSON，策略内容为：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "route53:GetHostedZone",
                "route53:ListHostedZones",
                "route53:ListHostedZonesByName",
                "route53:GetHostedZoneCount",
                "route53:ChangeResourceRecordSets",
                "route53:ListResourceRecordSets"
            ],
            "Resource": "*"
        }
    ]
}

如下图所示：

AWS策略

接着下一步输出策略名称和策略描述，最后点击创建策略。

创建策略成功后我们继续给用户添加权限，在左侧导航栏选择访问管理 > 用户，选择刚刚创建密钥的用户进入详情界面，点击添加权限,再选择直接附加策略，勾选我们刚刚创建的策略即可。

AWS添加策略

用户详情界面的策略列表显示我们刚刚新增的策略即配置成功。

对于非中国区域的AWS获取的密钥已经能够正常使用，使用中国区的AWS密钥签发证书会出现下面的错误

[Thu Dec 14 19:50:06     2023] Response error:<?xml version="1.0"?>
<ErrorResponse xmlns="https://route53.amazonaws.com/doc/2013-04-01/"><Error><Type>Sender</Type><Code>InvalidClientTokenId</Code><Message>The security token included in the request is invalid.</Message></Error><RequestId>eeee-dddd-cccc-bbbb-aaaa</ErrorResponse>

要使用中国区AWS的密钥，需要修改脚本中的AWS_HOST和Region参数：

Windows对应的默认安装路径为C:\Users\用户名\.acme.sh\dnsapi\dns_aws.sh，

Linux对应的默认安装路径为/root/.acme.sh/dnsapi/dns_aws.sh，

修改dns_aws.sh文件中12行的AWS_HOST为api.route53.cn(原始值为api.route53.cn)，修改dns_aws.sh文件中302行的Region为cn-northwest-1(原始值为us-east-1)，修改完成保存后即能正确签发证书。详情请见2722 Issues

阿里云

官方无对国内阿里云DNS解析的支持，可采用第三方插件的形式使用，来源于https://github.com/tengattack/certbot-dns-aliyun,请谨慎使用。

首先使用pip命令安装插件

sudo pip install certbot-dns-aliyun

创建和授权对应配置文件

chmod 600 /path/to/credentials.ini

文件中需要配置access_key和access_key_secret,文件内容格式如下：

dns_aliyun_access_key = 12345678
dns_aliyun_access_key_secret = 1234567890abcdef1234567890abcdef

最后自动验证dns的签发证书命令为：

certbot certonly \
    --authenticator=dns-aliyun \
    --dns-aliyun-credentials='/path/to/credentials.ini' \
    -d *.example.com,example.com --server https://acme.certcloud.cn/acme/directory --preferred-challenges dns-01 --key-type rsa

获取阿里云的key和secret过程为：

  1. 登录RAM控制台。

  2. 在左侧导航栏，选择身份管理 > 用户，创建用户会自动生成一对key和secret。

  3. 在用户页面，单击目标RAM用户名称。

  4. 在用户AccessKey区域，单击创建AccessKey。

  5. 根据界面提示完成安全验证。

  6. 在创建AccessKey对话框，查看AccessKey ID和AccessKey Secret。您可以单击下载CSV文件，下载AccessKey信息。或单击复制，复制AccessKey信息。

  7. 单击确定。

创建过程如下图所示：

阿里云密钥入口

阿里云密钥 在用户下创建密钥后还需要给用户进行AliyunDNSFullAccess授权,如下图所示：

阿里云密钥授权

上述过程使用了系统策略AliyunDNSFullAccess，你可以自定义策略，控制授权的粒度。

DNSPOD

官方无对DNSPOD解析的支持，可采用第三方插件的形式使用，来源于https://github.com/tengattack/certbot-dns-dnspod,请谨慎使用。

首先使用pip命令安装插件

sudo pip install git+https://github.com/tengattack/certbot-dns-dnspod.git

创建和授权对应配置文件

chmod 600 /path/to/credentials.ini

文件中需要配置id和token,文件内容格式如下：

dns_dnspod_api_id = 12345
dns_dnspod_api_token = 1234567890abcdef1234567890abcdef

最后自动验证dns的签发证书命令为：

certbot certonly -a dns-dnspod \
    --dns-dnspod-credentials /path/to/credentials.ini \
    -d example.com \
    -d "*.example.com" --server https://acme.certcloud.cn/acme/directory --preferred-challenges dns-01 --key-type rsa

腾讯云已经收购dnspod，如果你已登录腾讯云平台，跳转到dnspod是免登录的。腾讯云平台购买的域名能在dnspod官网 中查询到，因此你也可以使用dnspod的密钥进行授权自动验证域名所有权。获取dnspod密钥过程如下：

登录dnspod官网后点击头像的API密钥,你可以查看在到腾讯云创建的密钥，详细流程参考上一模块，我们接着创建DNSPod Token

dns1

选择 DNSPod Token，就到了 dnspod 的 token 生成页面,点击创建密钥，获取到 ID 和 token并设置到对应的环境变量DP_Id和DP_Key

dns2

其他

certbot官方支持的dns插件有

官方插件文档请参考：certbot-dns-plugins

自动部署和更新证书

请参考certbot官方用户指南

January 1, 0001