letsencrypt/boulder
GitHub: letsencrypt/boulder
Boulder 是驱动 Let's Encrypt 的 ACME 证书颁发机构软件，实现了自动化的域名验证与 TLS 证书签发全流程。
Stars: 5667 | Forks: 636
# Boulder - 一个 ACME CA
[](https://github.com/letsencrypt/boulder/actions/workflows/boulder-ci.yml?query=branch%3Amain)
这是一个基于 ACME 的 CA 实现。[ACME 协议](https://github.com/ietf-wg-acme/acme/) 允许 CA 自动验证证书申请人是否实际控制某个标识符，并允许订阅者为其控制的标识符颁发和撤销证书。Boulder 是运行 [Let's Encrypt](https://letsencrypt.org) 的软件。
## 目录
* [概述](#overview)
* [设置 Boulder](#setting-up-boulder)
* [开发](#development)
* [配合 Certbot 使用](#working-with-certbot)
* [配合其他 ACME 客户端使用](#working-with-another-acme-client)
* [生产环境](#production)
* [贡献](#contributing)
* [许可证](#license)
## 概述
Boulder 分为以下几个主要组件：
1. Web Front Ends（每个 API 版本一个）
2. Registration Authority
3. Validation Authority
4. Certificate Authority
5. Storage Authority
6. Publisher
7. CRL Updater
这种组件模型让我们能够按安全上下文分离 CA 的功能。Web Front End、Validation Authority、CRL Storer 和 Publisher 需要访问互联网，这使它们面临更高的入侵风险。Registration Authority 可以在没有互联网连接的情况下运行，但仍需与 Web Front End 和 Validation Authority 通信。Certificate Authority 只需接收来自 Registration Authority 的指令。所有组件都与 SA 通信以进行存储，因此此处未显示大多数表示 SA RPC 的连线。
```
CA ---------> Publisher
^
|
Subscriber -> WFE --> RA --> SA --> MariaDB
| ^
Subscriber server <- VA <----+ |
|
Browser -----> S3 <----- CRL Storer/Updater
```
在内部，系统的逻辑基于五种类型的对象：accounts（账户）、authorizations（授权）、challenges（挑战）、orders（订单）和 certificates（证书），它们直接映射到 ACME 中同名的资源。来自 ACME 客户端的请求会导致新对象的创建和现有对象的更改。Storage Authority 维护当前对象集的持久副本。
Boulder 使用 gRPC 进行组件间通信。对于希望设为远程的组件，需要为该组件实例化一个“client”（客户端）和“server”（服务器）。客户端实现组件的 Go 接口，而服务器包含组件的实际逻辑。关于此通信模型的高级概述可以在 [gRPC 文档](https://www.grpc.io/docs/) 中找到。
关于各种 ACME 操作如何在 Boulder 中发生的完整细节在 [DESIGN.md](https://github.com/letsencrypt/boulder/blob/main/docs/DESIGN.md) 中进行了说明。
## 设置 Boulder
### 开发
Boulder 包含一个 Dockerfile 并使用 Docker Compose，以便轻松安装和设置其所有依赖项。这是维护者开发 Boulder 的方式，也是我们推荐的主要开发和实验运行方式。它不适合用作生产环境。
虽然我们致力于让 Boulder 易于设置，但 ACME 客户端开发者可能会发现 [Pebble](https://github.com/letsencrypt/pebble)（一个 Boulder 的微型版本）更适合持续集成和快速实验。
我们建议在获取 Boulder 副本之前设置 git 的 [fsckObjects 设置](https://groups.google.com/forum/#!topic/binary-transparency/f-BI4o8HZW0/discussion)，以便为更新提供更好的完整性保证。
克隆 boulder 仓库：
```
git clone https://github.com/letsencrypt/boulder/
cd boulder
```
此外，请确保已安装 Docker Engine 1.13.0+ 和 Docker Compose 1.10.0+。如果没有，可以按照 Docker 的 [安装说明](https://docs.docker.com/compose/install/) 进行操作。
我们建议 Docker 主机上至少有 **2GB 的 RAM** 可用。实际上，使用较少的 RAM 可能会导致 MariaDB 容器以不明显的方式失败。
运行我们的标准测试套件（lints、单元测试、集成测试）：
```
./t.sh
```
运行所有单元测试：
```
./t.sh -u
```
运行特定的单元测试（示例为 ./va 目录）：
```
./t.sh -u -p ./va
```
运行所有集成测试：
```
./t.sh -i
```
运行带覆盖率统计的单元测试和集成测试：
```
./t.sh -ui -c --coverage-dir=./test/coverage/mytestrun
```
运行特定的集成测试（示例运行 TestGenerateValidity 和 TestWFECORS）：
```
./t.sh -i -f TestGenerateValidity/TestWFECORS
```
执行上述任何操作，但使用“config-next”配置（代表可能的未来状态，例如包含新功能标志）：
```
./tn.sh -your -options -here
```
要在 Docker 容器中启动 Boulder，首先运行：
```
docker compose run bsetup
```
这会将必要的证书写入 `test/certs/[.softhsm-tokens,ipki,webpki]`；
您只需要运行一次即可创建证书。如果需要删除所有证书并重新开始，可以删除目录 `./test/certs/.softhsm-tokens`、`./test/certs/ipki` 和 `./test/certs/webpki`，然后重新运行 `docker compose run bsetup`。
然后运行：
```
docker compose up
```
docker-compose.yml 中的配置会将您的 boulder 检出目录挂载到 /boulder，因此您可以在主机上编辑代码，更改会立即反映在使用 `docker compose` 运行的 Docker 容器内。
如果您遇到 Docker 问题，可能需要尝试[删除所有容器和卷](https://www.digitalocean.com/community/tutorials/how-to-remove-docker-images-containers-and-volumes)。
默认情况下，Boulder 使用一个假的 DNS 解析器，将所有主机名解析为 127.0.0.1。这适用于在 Docker 容器内运行集成测试。如果您希望 Boulder 能够与运行在您主机上的客户端通信，您应该使用以下命令找到主机的 Docker IP：
```
ifconfig docker0 | grep "inet addr:" | cut -d: -f2 | awk '{ print $1}'
```
并编辑 docker-compose.yml 以更改 `FAKE_DNS` 环境变量使其匹配。这将导致 Boulder 的模拟 DNS 解析器（`sd-test-srv`）使用 `FAKE_DNS` 中的地址响应所有 A 查询。
如果您使用基于主机的防火墙（例如 `ufw` 或 `iptables`），请确保允许从 Docker 实例到您主机的所需验证端口的连接，以便您的 ACME 客户端使用。
或者，您可以使用 -e 通过环境变量覆盖 docker-compose.yml 的默认值（将 172.17.0.1 替换为上面命令中找到的主机 IPv4 地址）
```
docker compose run --use-aliases -e FAKE_DNS=172.17.0.1 --service-ports boulder ./start.py
```
不使用 `./test.sh` 包装器运行测试：
在本地运行单元测试，不使用 docker（仅适用于某些目录）：
```
go test ./issuance/...
```
运行所有单元测试：
```
docker compose run --use-aliases boulder go test -p 1 ./...
```
运行特定目录的单元测试：
```
docker compose run --use-aliases boulder go test
```
运行集成测试（省略 `--filter ` 以运行所有）：
```
docker compose run --use-aliases boulder python3 test/integration-test.py --chisel --gotest --filter
```
### 配合 Certbot 使用
从 https://github.com/certbot/certbot 检出 Certbot 客户端并按照其设置说明操作。设置好客户端后，您可能希望针对本地 Boulder 运行它。针对本地 Boulder 运行客户端需要许多命令行标志，并且无需 root 权限。在本地运行客户端的最简单方法是使用一个方便的 certbot 别名（`certbot_test`）并带有一个自定义的 `SERVER` 环境变量：
```
SERVER=http://localhost:4001/directory certbot_test certonly --standalone -d test.example.com
```
您的本地 Boulder 实例使用一个假的 DNS 解析器，该解析器对任何查询都返回 127.0.0.1，因此您可以为 -d 标志使用任何值。要返回 `127.0.0.1` 以外的答案，请将 Boulder 的 `FAKE_DNS` 环境变量更改为另一个 IP 地址。
### 配合其他 ACME 客户端使用
按照 Boulder 开发环境说明操作并启动容器后，您会发现 ACME 端点通过以下 URL 暴露给您的主机：
* ACME v2, HTTP: `http://localhost:4001/directory`
* ACME v2, HTTPS: `https://localhost:4431/directory`
要访问端点的 HTTPS 版本，您需要将 ACME 客户端软件配置为使用包含 `test/certs/ipki/minica.pem` CA 证书的 CA 信任库。有关更多信息，请参阅 [`test/certs/README.md`](https://github.com/letsencrypt/boulder/blob/main/test/certs/README.md)。
您的本地 Boulder 实例使用一个假的 DNS 解析器，该解析器对任何查询都返回 127.0.0.1，允许您为任何域颁发证书，就像它解析到您的 localhost 一样。要返回 `127.0.0.1` 以外的答案，请将 Boulder 的 `FAKE_DNS` 环境变量更改为另一个 IP 地址。
大多数情况下，您会希望将 `FAKE_DNS` 配置为指向运行 ACME 客户端的主机。
### 生产环境
Boulder 是为 Let's Encrypt 定制构建的，旨在仅支持 Web PKI 和 CA/Browser 论坛的基线要求。根据我们的经验，对于评估其用于生产环境的组织来说，Boulder 通常不是合适的选择。在大多数情况下，不需要使用 ACME 进行域授权的集中管理 PKI 是更好的选择。对于这种环境，我们建议评估 Boulder 以外的项目。
我们提供了一份简短的[部署和实施指南](https://github.com/letsencrypt/boulder/wiki/Deployment-&-Implementation-Guide)，描述了在生产环境中使用 Boulder 所涉及的一些必要工作和安全注意事项。基于 docker 的 Boulder 开发环境**不适合生产使用**。它使用公开可用的私钥材料，暴露调试端口，并且对组件故障很脆弱。
虽然我们支持其他组织在生产环境中部署 Boulder，但我们优先考虑有利于 Let's Encrypt 使命的支持和开发工作。这意味着我们可能无法提供及时的支持，或者接受严重偏离我们首要目标的拉取请求。如果您已经彻底评估了替代方案并且 Boulder 确实是最合适的，我们很乐意尽我们所能回答问题。
## 贡献
请查看 [CONTRIBUTING.md](https://github.com/letsencrypt/boulder/blob/main/docs/CONTRIBUTING.md)，了解我们关于提交补丁、代码审查流程、行为准则以及与代码库相关的各种其他提示的指南。
## 行为准则
任何以任何身份参与此社区的人员的行为准则可在[社区论坛](https://community.letsencrypt.org/guidelines)上查阅。
## 许可证
本项目根据 Mozilla Public License 2.0 授权，其全文可在 [LICENSE.txt](https://github.com/letsencrypt/boulder/blob/main/LICENSE.txt) 文件中找到。
标签：ACME 协议, Boulder, CA, Cloudformation, EVTX分析, EVTX分析, Go 语言, HTTPS, JSONLines, Let's Encrypt, MariaDB, meg, Python工具, RA, SSL/TLS, VA, Web 安全, 信息安全, 公钥基础设施, 加密技术, 域名验证, 微服务架构, 日志审计, 自动化证书管理, 证书吊销, 证书颁发机构, 请求拦截, 软件清单, 零信任