Certbot中文文档
展开或关闭
简介
Certbot简介 Certbot 证书
获取Cerbot
Certbot 系统要求
用户指南
Certbot命令和获取各版本证书 Certbot 管理证书 Certbot 更改证书的域 Certbot 我的证书在哪里？ Certbot 验证前和验证后挂钩 Certbot 更改ACME服务器 Certbot命令行选项 Certbot 开发人员指南
API 文档
certbot.compat.filesystem module certbot.compat.misc module certbot.compat.os module certbot.display.ops module certbot.display.ops module certbot.display.util module certbot.plugins.common module certbot.plugins.dns_common module certbot.plugins.dns_common_lexicon module certbot.plugins.dns_test_common module certbot.plugins.dns_test_common_lexicon module certbot.plugins.enhancements module certbot.plugins.storage module certbot.plugins.util module certbot.tests.acme_util module certbot.tests.util module

Certbot 开发人员指南

Certbot中文文档 /

入门

设置用于开发时，Certbot具有相同的系统要求。尽管以下部分将帮助您安装Certbot及其依赖项，但Certbot需要在类似UNIX的操作系统上运行，因此，如果您使用Windows，则需要设置运行Linux等操作系统的（虚拟）计算机并在类似UNIX的操作系统上继续执行这些说明。

运行客户端的本地副本

从本地树以开发人员模式运行客户端与以用户身份运行Certbot有点不同。要进行设置，请通过运行以下命令克隆我们的git存储库：

git clone https://github.com/certbot/certbot

如果您使用的是macOS，建议您跳过本节的其余部分，而应在Docker中运行Certbot。您可以在此处找到有关操作方法的说明。如果您在Linux上运行，则可以运行以下命令来安装依赖项并设置可以在其中运行Certbot的虚拟环境。

安装运行Certbot所需的OS系统依赖项。

# For APT-based distributions (e.g. Debian, Ubuntu ...)
sudo apt update
sudo apt install python3-dev python3-venv gcc libaugeas0 libssl-dev
                 libffi-dev ca-certificates openssl
# For RPM-based distributions (e.g. Fedora, CentOS ...)
# NB1: old distributions will use yum instead of dnf
# NB2: RHEL-based distributions use python3X-devel instead of python3-devel (e.g. python36-devel)
sudo dnf install python3-devel gcc augeas-libs openssl-devel libffi-devel
                 redhat-rpm-config ca-certificates openssl

设置将托管您的Certbot本地实例的Python虚拟环境。

cd certbot
python tools/venv3.py

注意
当Certbot的依赖项更改或引入新插件时，您可能需要重复此操作。

现在，您可以通过执行venv3/bin/certbot或激活虚拟环境来从git运行Certbot的副本 。您可以通过运行以下命令来完成后者：

source venv3/bin/activate

运行此命令后，certbot和开发工具，如ipdb， ipython，pytest，和tox是在运行命令shell中可用。这些工具安装在虚拟环境中，并且与全局Python安装分开。这可以通过设置环境变量来工作，以便找到正确的可执行文件，并且Python可以提取Certbot所需的各种软件包的版本。

找到需要解决的问题

您可以在github问题跟踪器中找到未解决的问题。

分支正常工作后，您可以打开拉取请求。您的拉取请求中的所有更改都必须具有全面的单元测试范围，通过我们的测试并符合编码风格。

测试

您可以通过多种方式测试代码：

  • 运行自动化的单元测试，
  • 运行自动化集成测试
  • 运行临时 手动集成测试

运行自动化的单元测试

当您使用文件时foo.py，还应该在与子目录foo_test.py 相同的目录中foo.py或在tests子目录中有一个文件（如果没有，则创建一个）。在处理代码和测试时，请运行python foo_test.py 以运行相关的测试。

为了进行调试，建议将 import ipdb; ipdb.set_trace()语句放在源代码中。

完成代码更改并通过测试之后foo_test.py ，请运行Certbot的所有单元测试，并使用tox -e py3-cover来检查覆盖范围。然后，您应该使用tox -e lint（所有文件）或pylint --rcfile=.pylintrc path/to/file.py（一次单个文件）检查代码样式。

上述所有方法均成功完成后，您可以使用tox --skip-missing-interpreters来运行完整的测试套件 。我们建议您首先运行上面的命令，因为运行所有这样的测试非常慢，并且大量的输出会使得在发生特定故障时很难发现它们。

警告
如果您的用户具有sudo权限，则完整的测试套件可能会尝试修改系统的Ap​​ache配置，因此不应在生产的Apache服务器上运行它。

运行自动化集成测试

通常，打开一个请求请求并让Github和Travis为您运行集成测试就足够了。但是，您可能要在提交请求之前在本地运行它们。您需要安装并运行Docker和docker-compose。

Tox环境integration将设置Pebble让我们加密ACME CA服务器）进行集成测试，然后启动Certbot集成测试。

允许用户访问您本地的Docker守护程序，运行：

tox -e integration

测试将使用pytest运行。在集成测试执行结束时，将显示一个测试报告和一个代码覆盖率报告。

运行手动集成测试

您还可以针对Pebble ACME服务器的本地实例手动执行Certbot 。这对于验证对代码所做的修改是否使Certbot表现出预期的效果很有用。

为此，您需要：

  • 已安装Docker，并且有权访问Docker客户端的用户，
  • Certbot 的可用本地副本。

使用设置的虚拟环境包含两个命令，一旦激活虚拟环境，便可以使用它们：python tools/venv3.py

run_acme_server
  • 启动Pebble的本地实例并在前台运行以打印其日志。
  • 按CTRL + C停止此实例。
  • 该实例配置为验证针对本地执行的certbot的质询。

certbot_test [ARGS…]

  • 使用提供的参数和可用于测试目的的其他参数执行certbot，例如：详细输出，万一Certbot崩溃时的完整回溯等。
  • 执行已预先配置为与以开头的Pebble CA进行交互run_acme_server。
  • 可以将任何参数传递给Certbot（例如）。certbot_test certonly -d test.example.com

这是验证Certbot在具有Python 3的计算机上使用HTTP-01挑战成功颁发证书的典型工作流程：

python tools/venv3.py
source venv3/bin/activate
run_acme_server &
certbot_test certonly --standalone -d test.example.com
# To stop Pebble, launch `fg` to get back the background job, then press CTRL+C

在CI中运行测试

Certbot使用Azure Pipelines和Travis来运行连续集成测试。如果您使用我们的Azure和Travis设置，则名称以开头的分支test-将在该分支上运行所有Azure和Travis测试。如果分支名称以开头azure-test-，它将运行我们所有的Azure测试，而不运行我们的Travis测试。如果分支以开头travis-test-，则只会运行我们的Travis测试。

代码组件和布局

Certbot存储库的以下组件已分发给用户：

acme

包含所有协议特定的代码

certbot

主要客户代码

certbot-apache和certbot-nginx

客户端代码以配置特定的Web服务器

certbot-dns- *

客户端代码以配置DNS提供程序

certbot-auto and letsencrypt-auto

在UNIX系统上安装Certbot及其依赖项的Shell脚本

windows installer

在Windows上安装Certbot，并使用Windows-installer /中的文件构建

插件架构

Certbot具有插件架构，以促进对不同的Web服务器，其他TLS服务器和操作系统的支持。可用于插件实现的接口在interfaces.py和plugins / common.py中定义 。

主要的两个插件接口是IAuthenticator，用于实现向证书颁发机构证明域控制的各种方法，以及IInstaller，用于配置服务器以在证书颁发后使用证书。某些插件（例如内置的Apache和Nginx插件）实现了这两个接口并执行了这两项任务。其他一些，例如内置的Standalone验证器，仅实现一个接口。

还有一些IDisplay插件，可以更改向用户显示提示的方式。

认证者

身份验证器是通过解决ACME服务器提供的挑战来证明对域名的控制的插件。ACME当前定义了几种类型的挑战：HTTP，TLS-ALPN和DNS，由中的类表示acme.challenges。身份验证器插件应实现对至少一种挑战类型的支持。

身份验证器通过实施get_chall_pref(domain)以优先顺序返回挑战类型的排序列表来指示其支持 的挑战。

身份验证器还必须实现perform(achalls)，它例如通过在HTTP服务器上配置文件或在DNS中设置TXT记录来“执行”挑战列表。一旦所有挑战成功或失败，Certbot都会调用该插件的cleanup(achalls)方法来删除仅在身份验证期间需要的任何文件或DNS记录。

安装程序

存在安装程序插件可在服务器中实际设置证书，可能会调整安全性配置以使其更正确和安全（解决一些混合内容问题，打开HSTS，重定向到HTTPS等）。安装程序插件通过supported_enhancements()呼叫告知主要客户他们完成后者的能力。当前，我们在树中有两个Installers ApacheConfigurator。和 NginxConfigurator。外部项目在支持IIS，Icecast和Plesk方面取得了一些进展。

安装程序和身份验证器通常是相同的类/对象（例如，这两个任务都可以由像nginx这样的网络服务器执行），尽管并非总是如此（独立插件是侦听端口80的身份验证器，但无法安装）证书；后缀插件将是安装程序，而不是身份验证器）。

安装程序和身份验证器是分开的，因为应该可以将StandaloneAuthenticator它（自己设置自己的Python服务器来执行挑战）与本身无法解决挑战的程序一起使用（例如MTA安装程序）。

安装程式开发

有一些现有的课程在开发新课程时可能是有益的IInstaller。旨在重新配置UNIX服务器的安装程序可以使用Augeas进行配置解析，并且可以从AugeasConfigurator类继承来处理许多接口。无法使用Augeas的安装程序可能仍会发现Reverter该类在处理配置检查点和回滚方面很有帮助。

编写自己的插件

注意
Certbot团队目前不接受任何新的DNS插件，因为我们想重新思考应对挑战的方法，并首先解决＃6464，＃6503和＃6504之类的问题。

Certbot客户端支持通过使用组的setuptools入口点动态发现插件certbot.plugins。这样，您可以例如创建IAuthenticator或的 自定义实现， IInstaller而不必将其与核心上游源代码合并。examples/plugins/目录中提供了一个示例 。

在开发过程中，您可以将插件安装到Certbot开发virtualenv中，如下所示：

. venv/bin/activate
pip install -e examples/plugins/
certbot_test plugins

您的插件应显示在最后一条命令的输出中。如果不是，则未正确安装。

插件完成并发布后，您可以让用户在系统范围内安装。请注意，这仅适用于通过OS软件包或通过pip安装了Certbot的用户。运行用户当前无法使用第三方插件。从技术上讲，可以将第三方插件安装到所使用的virtualenv中，但是在升级时，它们会消失 。pip install``certbot-auto``certbot-auto``certbot-auto

编码风格

请：

  1. 与其余代码保持一致。

  2. 阅读PEP 8-Python样式指南。

  3. 请遵循Google Python样式指南，但我们使用Sphinx样式的文档除外：

    def foo(arg):
    """Short description.

 :param int arg: Some number.

 :returns: Argument
 :rtype: int

 """
    return arg

  4. 记住要使用pylint。

使用certbot.compat.os代替os

Python的标准库os模块缺少对文件权限（例如DACL）的Windows安全功能的全面支持。但是，由Certbot处理的多个文件（例如私钥）在Linux和Windows上都需要严格限制访问。

为了解决这个问题，该certbot.compat.os模块包装了标准 os模块，并禁止使用缺少对这些Windows安全功能的支持的方法。

作为开发人员，在使用Certbot或其插件时，必须certbot.compat.os 在所需的每个位置使用os（例如from certbot.compat import os而不是 import os）。否则，提交您的PR时测试将失败。

Mypy类型注释

Certbot使用mypy静态类型检查器。Python 3本机支持正式的类型注释，然后可以使用mypy对其进行一致性测试。Python 2没有，但是可以在comments中添加类型注释。Mypy即使没有类型注释也可以进行一些类型检查。即使没有完全注释的代码库，我们也可以在Certbot中找到错误。

Certbot同时支持Python 2和3，因此我们使用的是Python 2样式的注释。

Zulip撰写了使用mypy 的出色指南。这很有用，但是您不必阅读全部内容即可开始为Certbot做出贡献。

要在Certbot上运行mypy，请在已安装Python 3的计算机上使用tox -e mypy。

请注意typing，由于包装方面的问题，我们不仅从import导入，acme.magic_typing而且在Certbot中从中导入， 并且必须为pylint添加一些注释，如下所示：

from acme.magic_typing import Dict

还要注意，我们所依赖的OpenSSL具有加密类型定义，但没有SSL类型。我们都使用。这些导入应如下所示：

from OpenSSL import crypto
from OpenSSL import SSL # type: ignore # https://github.com/python/typeshed/issues/2052

提交拉取请求

Steps:

  1. 编写您的代码！执行此操作时，应为添加或修改的任何功能添加mypy类型注释。您可以通过在安装了Python 3的计算机上运行tox -e mypy来检查是否已正确完成此操作。
  2. 确保您的环境设置正确并且位于虚拟环境中。您可以按照“ 入门”部分中的说明进行操作 。
  3. 运行tox -e lint以检查pylint错误。修复所有错误。
  4. 运行以运行包括覆盖率在内的整个测试套件。该参数忽略运行测试所需的缺少的Python版本。修复所有错误。tox --skip-missing-interpreters``--skip-missing-interpreters
  5. 提交PR。PR打开后，请勿强行推入包含拉取请求的分支以压榨或修改提交。我们在PR上使用压缩合并，并且重写提交使更改很难在两次评论之间进行跟踪。
  6. 您的测试通过了Travis吗？如果没有，请更正所有错误。

寻求帮助

如果您在处理Certbot问题时有任何疑问，请随时寻求帮助！您可以在EFF的Mattermost实例的Certbot通道中针对其开源项目执行此操作，如下所述。

您可以参与EFF的多个软件项目，例如EFF开源贡献者聊天平台上的 Certbot 。注册EFF开源贡献者聊天平台，即表示您同意与该平台的运营商和数据控制者电子前沿基金会共享您的个人信息。EFF和EFFOSCCP的其他用户都可以使用该频道，他们可以在EFFOSCCP之外的这些频道中使用或公开信息。根据隐私政策，EFF将使用您的信息来促进EFF的使命，包括主持和主持该平台上的讨论。

EFFOSCCP的使用受EFF行为准则的约束。当调查涉嫌违反《行为准则》的行为时，EFF可能会审查讨论渠道或直接消息。

更新certbot-auto和letencrypt-auto

注意
目前，我们仅接受对certbot-auto的更改，该更改可修复在https://certbot.eff.org/instructions 上推荐的certbot-auto是推荐的安装方法的平台上的回归。

更新脚本

开发人员应该不能修改certbot-auto和letsencrypt-auto文件在存储库的根目录。而是分别修改 和目录letsencrypt-auto.template中的letsencrypt-auto-source和 特定于平台的Shell脚本letsencrypt-auto-source/pieces/bootstrappers。

构建letencrypt-auto-source / letsencrypt-auto

一旦更改了上述任何文件，就 letsencrypt-auto-source/letsencrypt-auto应更新脚本。代替手动更新此脚本，请运行构建脚本，该脚本位于 letsencrypt-auto-source/build.py：

python letsencrypt-auto-source/build.py

运行build.py将更新letsencrypt-auto-source/letsencrypt-auto 脚本。请注意，运行此脚本后，存储库根目录中的certbot-auto和letsencrypt-auto脚本将保持不变。您的更改将在下一版Certbot中传播到这些文件。

打开PR

打开PR时，请确保已提交以下文件：

  1. letsencrypt-auto-source/letsencrypt-auto.template 和 letsencrypt-auto-source/pieces/bootstrappers/*
  2. letsencrypt-auto-source/letsencrypt-auto（由生成build.py）

仔细检查没有对存储库根目录中的certbot-auto或letsencrypt-auto脚本进行任何更改，这些脚本将在下一个版本中由核心开发人员更新。

更新文档

Certbot存储库中的许多软件包在docs/目录中都有文档 。该目录位于软件包的顶级目录下。例如，Certbot的文档在下 certbot/docs。

要生成软件包的文档，请确保已按照说明进行操作，以设置Certbot 的本地副本，包括激活虚拟环境。之后，cd您要构建到docs目录并运行以下命令：

make clean html

这将_build/html在当前 docs/目录中生成HTML文档。

使用Docker运行客户端

您可以使用Docker Compose快速设置运行和测试Certbot的环境。要安装Docker Compose，请按照https://docs.docker.com/compose/install/ 上的说明进行操作 。

注意
Linux用户可以按照入门部分pip install docker-compose中所述，在安装Docker Engine并激活您的Shell之后，简单地运行以获取Docker Compose 。

现在，您可以在主机上进行开发，但是可以运行Certbot并在Docker中测试您的更改。使用时，请docker-compose确保您位于Certbot存储库的克隆中。例如，您可以运行以下命令来检查错误：

docker-compose run --rm --service-ports development bash -c 'tox -e lint'

您还可以在Docker容器中运行外壳的终端保持打开状态，并在另一个窗口中修改Certbot代码。主机上的Certbot存储库安装在容器内，因此您所做的任何更改都会立即生效。为此，请运行：

docker-compose run --rm --service-ports development bash

现在运行上述检查棉绒错误的操作非常简单：

tox -e lint

有关操作系统依赖性的说明

操作系统级别的依赖项可以这样安装：

./certbot-auto --debug --os-packages-only

一般来说…

  • sudo 是运行特权进程的建议方法
  • 需要Python2.7或3.5+
  • Python绑定需要Augeas
  • virtualenv 用于管理其他Python库依赖项

FreeBSD

FreeBSD默认使用tcsh。为了激活virtualenv，您将需要兼容的shell，例如。pkg install bash && bash

本文章首发在 网安wangan.com 网站上。

上一篇 下一篇
安全侠
Reserved 1.2k 声望
暂无个人描述~
讨论数量: 0
只看当前版本


暂无话题~
© 2021 WANGAN.COM 帮助网安从业者成长；关注产业发展,做网络安全忠诚卫士！