free_tls_certificates 0.1.6

安装

free_tls_certificates 可以通过pip安装，但首先需要安装其依赖项的一些二进制依赖项。以Ubuntu（以Python 3为例）

sudo apt-get install build-essential libssl-dev libffi-dev python3-dev python3-pip
sudo pip3 install free_tls_certificates

pip将安装的依赖项包括

• Let’s Encrypt的低级ACME客户端库及其所有依赖项。

• idna by kjd。

• cryptography及其依赖项（在Ubuntu上：sudo apt-get install build-essential libssl-dev libffi-dev python3-dev）。

命令行使用

命令行工具 free_tls_certificate（在安装free_tls_certificates后可用，它有一个s）可以用于从Let’s Encrypt自动提供TLS证书或生成自签名证书。

要从Let’s Encrypt获取TLS证书，您需要已经运行在端口80（而不是443——域验证仅在端口80上工作）的Web服务器，并且能够从运行free_tls_certificates的机器访问其静态根。

运行

free_tls_certificate domain-name-1.com [domain-name-2.com ...] /path/to/private.key /path/to/certificate.crt /path/to/website /path/to/acme/storage

第一次运行

• 将生成一个新的2048位RSA私钥，并保存到/path/to/private.key中，除非该路径下已存在文件，在这种情况下将使用该私钥。

• 您将被提示接受Let’s Encrypt的服务条款。将在/path/to/acme/storage为您创建并维护一个新的ACME账户。

• 将请求ACME HTTP01挑战，将在/path/to/website/.well-known/acme-challenge/...安装一个域所有权验证文件，并等待证书准备就绪。

• 当证书准备就绪时，证书以及证书链将被写入到/path/to/certificate.crt中（证书首先写入，正如nginx所期望的那样）。

后续运行将是无头运行，只需做正确的事情

• 如果指定的证书文件存在且有效，至少为给定的域有效期为30天，则工具将退出而不做任何操作（退出代码为3）。

• 如果证书文件不存在，不为所有给定的域有效，是自签名的，或者30天内即将到期，将颁发新证书，并将证书文件覆盖为新证书（以及链）。（您负责重新启动您的Web服务器，以便它可以看到新证书。）

由于工具仅在需要时颁发新证书，您可以将工具运行在夜间cron作业中，以保持证书的有效性。

您还可以使用此工具生成自签名证书。在启动新机器时很有用：您的Web服务器在放置证书文件之前可能不会启动，但您无法获得证书，直到Web服务器运行。

要获取自签名证书，只需添加--self-signed

free_tls_certificate --self-signed domain-name-1.com [domain-name-2.com ...] /path/to/private.key /path/to/certificate.crt

Web服务器支持

您需要一个正在运行的Web服务器，该服务器正在服务一个静态文件目录，该目录可以由free_tls_certificate写入。它必须通过HTTP（端口80）提供文件，因为ACME域验证不通过HTTPS进行。

您可能想使用如下nginx配置（或您Web栈的等效配置）

server {
    listen 80 default;
    location / {
        # Redirect to HTTPS.
        return 301 https://$host$request_uri;
    }
    location /.well-known/acme-challenge/ {
        # Serve the Let's Encrypt challenge path (must be
        # over HTTP, not HTTPS).
        root /home/ubuntu/public_html;
    }
}

server {
    listen 443 ssl http2;
    server_name domin-name-1.com;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ... your other directives here...
}

在这种情况下，您的/path/to/website将是/home/ubuntu/public_html。

作为Python模块使用

文件driver.py包含了一个完整的、可工作的示例，说明了如何使用此客户端库。这是free_tls_certificate命令行工具背后的代码。

请参阅driver.py以获取完整文档。需要处理许多边缘情况。

基本上是这样的。您将适应此代码以用于您的服务器配置工具

import requests.exceptions
import acme.messages

from free_tls_certificates import client

domains = ["mailinabox.email", "www.mailinabox.email"]
agree_to_tos = None  # fill this in on second run per output of exception

try:
    client.issue_certificate(
        domains,
        "path/to/some/storage",
        certificate_file="certificate.crt",
        agree_to_tos_url=agree_to_tos)

except client.NeedToAgreeToTOS as e:
    print("You need to agree to the TOS. Set this on next run:")
    print("agree_to_tos = " + repr(e.url))

except client.NeedToTakeAction as e:
    for action in e.actions:
        if isinstance(action, client.NeedToInstallFile):
            print("Install a file!")
            print("Location: " + action.url)
            print("Contents: " + action.contents)

except client.WaitABit as e:
    import datetime
    print ("Try again in %s." % (e.until_when - datetime.datetime.now()))

但请参阅完整的驱动程序文件以处理所有错误条件！

使用说明

您可以一次性请求多个域的证书，可能最多100个（这是Let’s Encrypt当前的最大值）。您指定的第一个域将放入证书的“通用名称”字段，所有域都将放入证书的“主题备用名称”（SAN）扩展中。（所有现代浏览器都接受SAN域。）

请注意，Let’s Encrypt尚未（在撰写本文时）支持为国际化域名颁发证书。

您可以使用任何Python字符串类型（str、bytes、unicode）来传递域名。如果域名是国际化的，请使用Python 2的unicode和Python 3的str实例来传递域名名的Unicode形式。如果字符串已经是IDNA编码的（即punycode），则可以使用任何字符串类型。

测试

要测试库，请设置一个本地运行的Boulder服务器，它是ACME服务器的参考实现。

• 安装docker。

• 从https://github.com/letsencrypt/boulder下载Boulder源代码。

• 切换到您放置Boulder的目录。

• 运行FAKE_DNS=$(hostname -I) test/run-docker.sh（根据您的docker设置，可能需要sudo）。

Boulder默认使用其测试配置运行，该配置无论请求哪个域名的证书，都会通过查询docker主机上的5002端口执行“HTTP01”域名验证，这对于创建响应这些请求的测试服务器非常有用。（但是，您仍然需要使用合理的公共域名进行测试，因此something.invalid将不会被您的Boulder服务器接受。）

如果您还没有创建测试虚拟环境，请创建一个

virtualenv -ppython3 env
source env/bin/activate
pip install -r requirements.txt

添加

127.0.0.1 x1.le.wtf
127.0.0.1 fail.le.wtf

到您的/etc/hosts文件。这是为了在我们库的客户端验证域名验证检查之前提交挑战响应到ACME服务器。我们使用x1.le.wtf和fail.le.wtf作为测试域名（因为Boulder即使在测试中也不会为无效域名颁发证书），它们必须解析到localhost。

启动我们的单元测试

python test.py

这检查本地Boulder服务器是否会为x1.le.wtf颁发证书，并检查库的其他方面。