cfssl/cfssl

CFSSL

镜像概述和主要用途

CFSSL是CloudFlare的PKI/TLS瑞士军刀，既是命令行工具，也是用于签名、验证和捆绑TLS证书的HTTP API服务器。它需要Go 1.12+环境来构建。

注意：某些Linux发行版（特别是基于RHEL的发行版）移除了某些算法，因此官方仓库中的Golang可能无法正常工作。这些发行版的用户应手动安装Go以使用CFSSL。

核心功能和特性

CFSSL由以下组件构成：

• 一组用于构建自定义TLS PKI工具的包
• cfssl程序：使用CFSSL包的标准命令行工具
• multirootca程序：可以使用多个签名密钥的证书颁发机构服务器
• mkbundle程序：用于构建证书池捆绑包
• cfssljson程序：处理cfssl和multirootca程序的JSON输出，并将证书、密钥、CSR和捆绑包写入磁盘

使用场景和适用范围

CFSSL适用于以下场景：

• 企业内部PKI基础设施搭建
• TLS证书的创建、签名和管理
• 证书颁发机构(CA)服务器部署
• 自动化证书生命周期管理
• OCSP响应生成和OCSP服务器部署
• 证书捆绑和验证

详细使用方法和配置说明

Docker部署

Docker Run 示例

bash
# 拉取CFSSL镜像
docker pull cloudflare/cfssl

# 基本命令行使用
docker run --rm -v $(pwd):/work cloudflare/cfssl cfssl version

# 生成自签名根CA证书和私钥
docker run --rm -v $(pwd):/work cloudflare/cfssl cfssl genkey -initca csr.json | docker run --rm -i -v $(pwd):/work cloudflare/cfssl cfssljson -bare ca

# 启动CFSSL API服务器
docker run -d -p 8888:8888 -v $(pwd):/work --name cfssl-server cloudflare/cfssl cfssl serve -address 0.0.0.0 -ca ca.pem -ca-key ca-key.pem

Docker Compose 配置示例

yaml
version: '3'

services:
  cfssl:
    image: cloudflare/cfssl
    container_name: cfssl-server
    ports:
      - "8888:8888"
    volumes:
      - ./ca:/work
    command: cfssl serve -address 0.0.0.0 -ca /work/ca.pem -ca-key /work/ca-key.pem -loglevel 1
    restart: unless-stopped

命令行工具使用

cfssl命令行工具接受以下命令来指定要执行的操作：

• sign：签名证书
• bundle：构建证书捆绑包
• genkey：生成私钥和证书请求
• gencert：生成私钥和证书
• serve：启动API服务器
• version：打印当前版本
• selfsign：生成自签名证书
• print-defaults：打印默认配置

使用cfssl [command] -help了解有关命令的更多信息。version命令不带参数。

签名

bash
cfssl sign [-ca cert] [-ca-key key] [-hostname comma,separated,hostnames] csr [subject]

csr是客户端的证书请求。-ca和-ca-key标志分别是CA的证书和私钥。默认情况下，它们是ca.pem和ca_key.pem。-hostname是逗号分隔的主机名列表，覆盖证书SAN扩展中的DNS名称和IP地址。

例如，假设CA的私钥在/etc/ssl/private/cfssl_key.pem中，CA的证书在/etc/ssl/certs/cfssl.pem中，为cloudflare.com签名cloudflare.pem证书：

bash
cfssl sign -ca     /etc/ssl/certs/cfssl.pem       \
           -ca-key /etc/ssl/private/cfssl_key.pem \
           -hostname cloudflare.com               \
           ./cloudflare.pem

也可以使用-csr标志指定CSR。通过这种方式，标志值优先，并将覆盖参数。

主题是一个可选文件，包含应替换CSR中信息的主题信息。它应该是如下的JSON文件：

json
{
    "CN": "example.com",
    "names": [
        {
            "C":  "US",
            "L":  "San Francisco",
            "O":  "Internet Widgets, Inc.",
            "OU": "WWW",
            "ST": "California"
        }
    ]
}

注意：从Go 1.7开始，自签名证书将不包含AKI。

捆绑

bash
cfssl bundle [-ca-bundle bundle] [-int-bundle bundle] \
             [-metadata metadata_file] [-flavor bundle_flavor] \
             -cert certificate_file [-key key_file]

捆绑包用于根证书池和中间证书池。此外，平台元数据通过-metadata指定。捆绑包文件、元数据文件（和辅助文件）可在以下位置找到：

https://github.com/cloudflare/cfssl_trust

通过-cert和-key分别指定PEM编码的客户端证书和密钥。如果指定了密钥，将构建捆绑包并使用密钥进行验证。否则，将构建没有私钥的捆绑包。使用-代替文件路径，从stdin读取证书PEM。证书文件应包含（部分）证书捆绑包也是可以接受的。

通过-flavor指定捆绑风格。有三种风格：optimal生成最短链和最高级加密算法的捆绑包，ubiquitous生成在不同浏览器和OS平台上最广泛接受的捆绑包，force找到与输入证书文件内容相同的可接受捆绑包。

或者，可以直接从域中拉取客户端证书。也可以通过-ip连接到远程地址。

bash
cfssl bundle [-ca-bundle bundle] [-int-bundle bundle] \
             [-metadata metadata_file] [-flavor bundle_flavor] \
             -domain domain_name [-ip ip_address]

捆绑输出格式应如下例所示：

json
{
    "bundle": "CERT_BUNDLE_IN_PEM",
    "crt": "LEAF_CERT_IN_PEM",
    "crl_support": true,
    "expires": "2015-12-31T23:59:59Z",
    "hostnames": ["example.com"],
    "issuer": "ISSUER CERT SUBJECT",
    "key": "KEY_IN_PEM",
    "key_size": 2048,
    "key_type": "2048-bit RSA",
    "ocsp": ["http://ocsp.example-ca.com"],
    "ocsp_support": true,
    "root": "ROOT_CA_CERT_IN_PEM",
    "signature": "SHA1WithRSA",
    "subject": "LEAF CERT SUBJECT",
    "status": {
        "rebundled": false,
        "expiring_SKIs": [],
        "untrusted_root_stores": [],
        "messages": [],
        "code": 0
    }
}

生成证书签名请求和私钥

bash
cfssl genkey csr.json

要生成私钥和相应的证书请求，请将密钥请求指定为JSON文件。此文件应遵循以下格式：

json
{
    "hosts": [
        "example.com",
        "www.example.com",
        "https://www.example.com",
        "jdoe@example.com",
        "127.0.0.1"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C":  "US",
            "L":  "San Francisco",
            "O":  "Internet Widgets, Inc.",
            "OU": "WWW",
            "ST": "California"
        }
    ]
}

生成自签名根CA证书和私钥

bash
cfssl genkey -initca csr.json | cfssljson -bare ca

要生成自签名根CA证书，请将密钥请求指定为与'genkey'中相同格式的JSON文件。输出中将出现三个PEM编码的实体：私钥、csr和自签名证书。

生成远程颁发的证书和私钥

bash
cfssl gencert -remote=remote_server [-hostname=comma,separated,hostnames] csr.json

这将调用genkey，但让远程CFSSL服务器签名并颁发证书。您可以使用-hostname覆盖证书SAN。

生成本地颁发的证书和私钥

bash
cfssl gencert -ca cert -ca-key key [-hostname=comma,separated,hostnames] csr.json

这通过JSON请求从本地CA生成并颁发证书和私钥。您可以使用-hostname覆盖证书SAN。

使用新颁发的证书更新OCSP响应文件

bash
cfssl ocspsign -ca cert -responder key -responder-key key -cert cert \
 | cfssljson -bare -stdout >> responses

这将为cert生成OCSP响应，并将其添加到responses文件中。然后，您可以将responses传递给ocspserve以启动OCSP服务器。

启动API服务器

CFSSL附带基于HTTP的API服务器；端点记录在doc/api/intro.txt中。服务器通过serve命令启动：

bash
cfssl serve [-address address] [-ca cert] [-ca-bundle bundle] \
            [-ca-key key] [-int-bundle bundle] [-int-dir dir] [-port port] \
            [-metadata file] [-remote remote_host] [-config config] \
            [-responder cert] [-responder-key key] [-db-config db-config]

地址和端口默认为"127.0.0.1:8888"。-ca和-ca-key参数应该是用于签名的PEM编码证书和私钥；默认情况下，它们是ca.pem和ca_key.pem。-ca-bundle和-int-bundle应该分别是用于根证书池和中间证书池的证书捆绑包。它们分别默认为ca-bundle.crt和int-bundle.crt。如果指定了-remote选项，所有签名操作将转发到远程CFSSL。

-int-dir指定中间目录。-metadata是根证书存在性的文件。文件内容是json字典(k,v)，其中每个键k是根证书的SHA-1摘要，而值v是密钥存储文件名列表。-config指定配置文件的路径。-responder和-responder-key分别是OCSP响应器的证书和私钥。

日志量可以通过-loglevel选项控制。此选项在serve命令之后：

bash
cfssl serve -loglevel 2

级别如下：

• 0 - DEBUG
• 1 - INFO（这是默认级别）
• 2 - WARNING
• 3 - ERROR
• 4 - CRITICAL

multirootca

cfssl程序可以充当在线证书颁发机构，但它只使用单个密钥。如果需要多个签名密钥，可以使用multirootca程序。它只提供sign、authsign和info端点。文档包含配置和运行CA的说明。

mkbundle工具

mkbundle用于构建用于验证证书的根和中间捆绑包。可以使用以下命令安装：

bash
go get -u github.com/cloudflare/cfssl/cmd/mkbundle

它接受一组证书，检查CRL吊销（OCSP支持计划在下一版本中推出）和过期证书，并将它们捆绑到一个文件中。它接受证书目录和证书文件（可能包含多个证书）。例如，如果目录intermediates包含多个中间证书：

bash
mkbundle -f int-bundle.crt intermediates

将检查这些证书并将有效证书组合到单个int-bundle.crt文件中。

-f标志指定输出名称；-loglevel指定日志的详细程度（使用与上述相同的日志级别），-nw控制吊销检查工作线程的数量。

cfssljson工具

cfssl的大部分输出都是JSON格式。cfssljson工具可以获取此输出，并将其拆分为单独的key、certificate、CSR和bundle文件（视情况而定）。该工具接受一个标志-f，指定输入文件，以及一个参数，指定生成文件的基本名称。如果输入文件名是-（默认值），cfssljson从标准输入读取。它以以下方式将JSON文件中的键映射到文件名：

• 如果指定了__cert__或__certificate__，将生成__basename.pem__
• 如果指定了__key__或__private_key__，将生成__basename-key.pem__
• 如果指定了__csr__或__certificate_request__，将生成__basename.csr__
• 如果指定了__bundle__，将生成__basename-bundle.pem__
• 如果指定了__ocspResponse__，将生成__basename-response.der__

您可以传递-stdout而不是保存到文件，将编码内容输出到标准输出。

静态构建

默认情况下，Web资产根据其相对位置从磁盘访问。如果您希望分发单个静态链接的cfssl二进制文件，您需要在构建之前嵌入这些资源。这可以通过https://github.com/GeertJohan/go.rice%E5%B7%A5%E5%85%B7%E5%AE%8C%E6%88%90%E3%80%82

bash
pushd cli/serve && rice embed-go && popd

然后使用go build构建将使用嵌入的资源。

附加文档

附加文档可在"doc"目录中找到：

• api/intro.txt：记录API端点