mode51software/vaultplugin-hsmpki
GitHub: mode51software/vaultplugin-hsmpki
一款扩展Vault内置PKI插件的工具，通过PKCS#11接口实现HSM硬件安全模块签名，为证书颁发提供硬件级私钥保护。
Stars: 21 | Forks: 6
# Vault HSM PKI 插件
Vault HSM PKI 插件在内置 PKI 插件的基础上进行了修改，通过 [PKCS#11](http://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/os/pkcs11-base-v2.40-os.html) 实现了使用 Hardware Security Module（硬件安全模块）进行证书签名的支持。
## 软件设计
### 复用内置 PKI
[内置 PKI](https://github.com/hashicorp/vault/tree/v1.6.3/builtin/logical/pki) 在使用方面有一个[指定的 API](https://www.vaultproject.io/api-docs/secret/pki)，新插件可以遵循该 API，但其代码并非以可复用模块的形式提供。
由于此 HSM 插件旨在保留大部分现有功能而不做修改（例如 roles），因此内置 PKI 代码被包含在 [pkg/pki](./pkg/pki) 目录中，并添加了 pki_api.go 文件以使选定的函数可从外部访问。其余包含的 PKI 代码被原样包含在 pkg/pki 目录中。
因此，HSM PKI 插件可以选择性地覆盖某些 PKI 路径，同时使用一些未更改的路径。
## 用法
### 依赖项
[Go](https://golang.org/doc/install)
[Vault](https://www.vaultproject.io/downloads)
### 设置 HSM
[pkcs11helper 模块](https://github.com/mode51software/pkcs11helper)提供了针对 SoftHSM、Thales 的 SafeNet 和 Entrust 的 nShield 的[详细设置说明](https://github.com/mode51software/pkcs11helper/blob/master/SETUP.md)。
### 配置
请准备 [conf/ 目录下的 HSM 配置文件](https://github.com/mode51software/vaultplugin-hsmpki/blob/master/conf/config-safenet.hcl)。
PKCS#11 客户端库的路径以及 Slot ID 和 PIN 在此配置文件中指定。
省略 key_label 参数以随机生成一个新的 key label。
如果您已安装并配置了 SafeNet DPoD，请先为 shell 设置环境：
```
cd /opt/safenet/dpod/current
. ./setenv
cd
```
### 构建
请注意，可能需要以下环境变量：
export GOSUMDB=off
以下命令将构建插件二进制文件并将 Vault 服务器作为内存中的开发实例启动：
```
make
```
请访问 [INSTALL.md](INSTALL.md) 获取持久化插件安装说明和注册详细信息。
### 登录
现在打开一个新的终端窗口并登录到 Vault。这是一个开发实例的示例：
`export VAULT_ADDR='http://127.0.0.1:8200'`
`vault login root`
### 设置
#### 无 CA 生成的设置
如果 Intermediate CA 已在 Vault 外部由 Root CA 创建并签名，则适用以下说明。
##### 启用 HSM PKI 插件：
`vault secrets enable -path=hsmpki_inter -options="config=conf/config-softhsm.hcl" vaultplugin-hsmpki`
#### 带 CA 生成的设置
如果需要由 Vault 创建并签名 Root 和 Intermediate CA，则适用以下说明。
##### 启用 HSM PKI 插件路径：
* 不同的配置文件可以传递给插件的每个实例。
* 这些文件可能包含替代的 HSM slot 和 PIN 设置。
* 如果未指定 key label，系统将自动生成一个并存储在 Vault 中。
* 自动生成的 key label 会在 Generate Root 和 Generate Intermediate 命令的响应中提供。
Root CA 路径：
`vault secrets enable -path=hsmpki_root -options="config=conf/config-safenet.hcl" vaultplugin-hsmpki`
Intermediate CA 路径：
`vault secrets enable -path=hsmpki_inter -options="config=conf/config-safenet.hcl" vaultplugin-hsmpki`
### 运行创建 CA 证书并签发
在这一系列步骤中，Vault：
* 使用 hsmpki_root 路径生成 Root CA 证书
* 使用 hsmpki_inter 路径生成 Intermediate CA 和 CSR
* 使用 hsmpki_root 路径签名 Intermediate CA 的 CSR 并生成证书
* 使用 hsmpki_inter 路径设置已签名的 Intermediate CA
* 创建一个角色
* 使用 hsmpki_path 签发一个新的私钥和由 Intermediate CA 签名的新证书
#### 生成 Root CA
请注意，key_label 会与 serial_number 一起返回。还要注意，该证书与签发证书相同。
如果 conf 文件中未指定 key_label，则会自动为 HSM 生成一个 key label。
自动生成的 key_label 格式例如：ROOTCA20210314232939
`vault write hsmpki_root/root/generate/internal common_name=safenet.ec.ca.mode51.software key_type=ec key_bits=521 permitted_dns_domains=localhost organization="mode51 Software Ltd" ou="Software" country="GB" locality="Cambridge" province="Cambridgeshire" street_address="1 A Street" postal_code="CB1"`
将已签名的 Intermediate CA 保存到文件，例如 data/root.cert.pem
此 CA 证书可以导入到浏览器中进行测试。
#### 生成 Intermediate CA 和 CSR
自动生成的 key_label 格式例如：INCA20210314233609
`vault write hsmpki_inter/intermediate/generate/internal common_name=safenet.ec.interca.mode51.software key_type=ec key_bits=384 permitted_dns_domains=localhost organization="mode51 Software Ltd" ou="Software" country="GB" locality="Cambridge" province="Cambridgeshire" street_address="1 A Street" postal_code="CB1"`
将 CSR 保存到文件，例如 data/intermediate.csr.pem
使用 openssl 检查 CSR：
`openssl req -in ./data/intermediate.csr.pem -text`
#### 签名 Intermediate CA
`vault write hsmpki_root/root/sign-intermediate csr=@data/intermediate.csr.pem common_name=safenet.ec.interca.mode51.software key_type=ec key_bits=384 permitted_dns_domains=localhost organization="mode51 Software Ltd" ou="Software" country="GB" locality="Cambridge" province="Cambridgeshire" street_address="1 A Street" postal_code="CB1"`
将已签名的 Intermediate CA 保存到文件，例如 data/intermediate.cert.pem
此 CA 证书可以导入到浏览器中进行测试。
#### 设置已签名的 Intermediate CA
如果 key label 是作为 Generate Intermediate 命令的一部分自动生成的，则不需要在此处或 conf 文件中指定它：
`vault write hsmpki_inter/intermediate/set-signed certificate=@data/intermediate.cert.pem hash_algo="SHA-512"`
#### 创建角色
为允许的域创建一个角色，该角色配置证书签名模板，在本例中为 localhost：
`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type="ec" key_bits="384"`
#### 签发新的已签名证书
请求 Vault 创建新的密钥对，生成 CSR 并使用 HSM 对其进行签名，同时返回私钥、CA 和已签名的证书：
`vault write hsmpki_inter/issue/localhost common_name=localhost`
### 运行使用外部生成并签名的 CA 进行签名
#### 设置已签名的 Intermediate CA
设置已签名的 Intermediate 证书，并使用支持配置 HSM 密钥别名和首选 SHA 算法的 HSM PKI 扩展。
Key label 也可以在传递给 secrets enable 命令的 conf 文件中进行配置：
`vault write hsmpki_inter/intermediate/set-signed certificate=@data/safenet-inter-0016.ca.cert.pem key_label="ECTestCAInterKey0016" hash_algo="SHA-512"`
#### 创建角色
为允许的域创建一个角色，该角色配置证书签名模板，在本例中为 localhost：
`vault write hsmpki_inter/roles/localhost allowed_domains=localhost allow_subdomains=true ttl=24h max_ttl=72h key_type="ec" key_bits="384"`
#### 签名 CSR
现在 Vault 已准备好进行签名，使用 HSM 签名一个独立的 CSR 文件，并返回 CA 和已签名的证书：
`vault write hsmpki_inter/sign/localhost csr=@data/localhost512.csr.pem`
#### 签发新证书
请求 Vault 创建新的密钥对，生成 CSR 并使用 HSM 对其进行签名，同时返回私钥、CA 和已签名的证书：
`vault write hsmpki_inter/issue/localhost common_name=localhost`
#### 吊销证书
`vault write hsmpki_inter/revoke serial_number=""`
#### 查看证书吊销时间
`vault read hsmpki_inter/cert/`
#### 查看 CRL
`curl --header "X-Vault-Token: root" http://127.0.0.1:8200/v1/hsmpki_inter/crl/pem > data/crl.txt`
`openssl crl -in ./data/crl.txt -text`
### 验证证书
安装 nginx 并为测试站点设置 TLS 证书和私钥，
下文分别称为 localhost.crt 和 localhost.key。
这些是 Vault 的 issue 命令生成的私钥和证书。
分别将 Root CA 和 Intermediate CA 导入 Web 浏览器。
访问 https://localhost:444/ 并确认 TLS 证书被接受。
```
server {
listen 444 ssl http2 default_server;
server_name localhost;
ssl_certificate /etc/nginx/certs/localhost.crt;
ssl_certificate_key /etc/nginx/certs/localhost.key;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!MD5;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
}
```
### 测试
查看 [TESTING](TESTING.md) README
### 故障排除
#### Vault
* api_addr 必须在 [Vault 的服务器配置文件](https://www.vaultproject.io/docs/configuration#api_addr)中配置，否则插件将无法正常工作。
#### SafeNet DPoD [故障排除](https://thalesdocs.com/dpod/services/hsmod_services/hsmod_troubleshooting/index.html)
##### 环境
setenv 脚本设置以下环境变量。请使用您的 dpod 文件根目录的路径：
```
declare -x ChrystokiConfigurationPath="/opt/safenet/dpod/current"
```
这可以在 systemd 配置文件的 service 部分中设置：
```
Environment="ChrystokiConfigurationPath=/opt/safenet/dpod/current"
```
##### HSM 错误代码 0x80001604
* 这可能表明 SafeNet DPoD 分区已满
## 许可证
Vault 的 HSM PKI 由 [BT UK](https://www.globalservices.bt.com/en/aboutus/our-services/security) 赞助，由 [mode51 Software](https://mode51.software) 开发，并根据 Mozilla Public License v2 贡献给 [HashiCorp 社区](https://www.vaultproject.io/docs/plugin-portal)。
作者 [Chris Newman](https://mode51.software)
标签：EVTX分析, Go语言, HashiCorp Vault, HSM, nShield, PKCS#11, ProjectDiscovery, SafeNet, SamuraiWTF, Secrets Management, SoftHSM, TypeScript, Vault插件, 安全插件, 密码学, 手动系统调用, 数字证书, 数据保护, 日志审计, 硬件安全模块, 程序破解, 证书签名