Step Certificates 示例指南:从 ca.Client SDK 到 Federation、证书轮换与 Docker 部署
Step Certificates 示例指南:从 ca.Client SDK 到 Federation、证书轮换与 Docker 部署
本文以 certificates 仓库 examples 目录下的官方示例为主线,系统讲解如何用 Go SDK(ca 包)集成私有证书颁发机构:从最基础的客户端初始化、签名(Sign)与续期(Renew),到 BootstrapServer/BootstrapClient 的一键式 TLS/mTLS 服务搭建,再到证书自动轮换机制、NGINX + Docker 组合部署、多 CA 联邦(Federation)以及通过 Custom Claims 自定义证书有效期。读完本文,你将掌握 Step CA 客户端 API 的全部核心用法,并能直接复制示例在本地跑通整套流程。
示例总览与运行前提
examples/README.md 是 certificates 仓库的官方示例手册,对应源码全部位于 examples 目录:
| 示例目录 | 演示内容 |
|---|---|
| basic-client | ca.Client 类型作为 SDK 的全部基础方法 |
| bootstrap-tls-server | 服务端可选验证客户端证书的 TLS 服务 |
| bootstrap-mtls-server | 强制要求 mTLS 的严格模式服务端 |
| bootstrap-client | 自动申请证书并周期性发起 TLS 请求的客户端 |
| basic-federation | 两个独立 CA 之间的根证书联邦 |
| docker | NGINX + Step CA + 定时续期容器编排 |
所有示例都使用同一个预生成的 PKI 配置 examples/pki/config/ca.json,其中包含 4 个 jwk 类型 provisioner:mariano@smallstep.com(默认 24h 有效期)、mike@smallstep.com(2 分钟短证书)、decade(10 年)、90days(90 天),配置中的 provisioner 密钥密码为 password。实际生产环境请勿使用示例 PKI,应通过 step ca init 自行初始化。
一、Basic Client:ca.Client SDK 全方法演示
examples/basic-client/client.go 展示了 ca.Client 类型作为 SDK 的所有核心方法,这些方法本质上是 CA HTTP API(/health、/root、/sign、/renew 等端点)的便捷封装。对应实现位于 ca/client.go。
1.1 客户端初始化:NewClient 与 Bootstrap
示例首先通过 CA 地址和根证书指纹创建客户端:
client, err := ca.NewClient("https://localhost:9000", ca.WithRootSHA256("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d"))
- 第一个参数是 CA 的服务地址;
- 根证书 SHA-256 指纹可用
step certificate fingerprint root_ca.crt获取。
从 ca/client.go 的源码看,WithRootSHA256 和 WithRootFile 会创建一个底层 Transport:前者使用非安全客户端通过指纹去 CA 拉取根证书(o.rootSHA256),后者直接加载本地根证书文件(o.rootFilename)。两者都是 ClientOption,且互斥——若先前已配置过创建 Transport 的选项,会直接返回错误。
CA 地址通常会出现在 provisioner token 中,--root root_ca.crt 选项也会把根指纹写进 token。因此当 token 内含根指纹时,更简单的初始化方式是:
client, err := ca.Bootstrap(token)
Bootstrap 的实现见 ca/bootstrap.go:它解析 JWT(jose.ParseSigned),读取 tokenClaims 中的 sha 字段和 aud 声明,校验 sha 存在且 aud 以 http 开头后,等价于执行 NewClient(claims.Audience[0], WithRootSHA256(claims.SHA))。
其他初始化方式(同样在示例源码注释中给出):
// 使用根证书文件而非指纹:
client, err := ca.NewClient("https://localhost:9000", ca.WithRootFile("../pki/secrets/root_ca.crt"))
1.2 Health:健康检查
health, err := client.Health()
// Health is a struct created from the JSON response {"status": "ok"}
底层实现(ca/client.go)向 /health 端点发起 GET,将 JSON 反序列化为 api.HealthResponse;若服务器在线则返回 {"status":"ok"}。
1.3 Root:获取并校验根证书
root, err := client.Root("84a033e84196f73bd593fad7a63e509e57fd982f02084359c4e8c5c864efc27d")
Root 方法(ca/client.go)使用非安全 HTTP 客户端(newInsecureClient())从 /root/{sha256Sum} 下载根证书,然后用本地计算出的 SHA-256 与传入指纹比对,不一致即返回 root certificate fingerprint does not match 错误。之所以允许使用非安全客户端,是因为响应已通过指纹比对得到校验,这保证了客户端在初始化阶段无需先信任任何根即可安全获取根证书。
1.4 Sign:签发证书(最重要方法)
Sign 负责对一个 CSR(证书签名请求)进行授权并签名。授权依赖由已授权 provisioner 签发的 provisioning token。你可以手工构造 CSR 填入 *api.SignRequest,但 SDK 提供了 ca.CreateSignRequest,它内部生成安全随机密钥并自动结合 token 中的信息构造 CSR:
// 从 token 创建 SignRequest,返回请求、私钥和可能的错误
req, pk, err := ca.CreateSignRequest(token)
if err != nil { ... }
// 执行 Sign 请求,返回已签发的证书
sign, err := client.Sign(req)
if err != nil { ... }
从源码看,Sign(ca/client.go)向 /sign 端点 POST JSON 请求体,成功后除解析 api.SignResponse 外,还会从 resp.TLS 的验证链中提取根证书写入 sign.TLS 字段,方便调用方直接拿到信任链。
1.5 Renew:证书续期(mTLS)
续期依赖 mTLS 连接:请求方必须携带现有证书,因此需要传入一个带有当前证书的 Transport。
// 获取可取消的 context,用于停止续期 goroutine 与定时器
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 用 Sign 响应和私钥创建 Transport
tr, err := client.Transport(ctx, sign, pk)
if err != nil { ... }
// 续期证书,返回类型与 Sign 相同
renew, err := client.Renew(tr)
if err != nil { ... }
Renew 的实现(ca/client.go)使用传入的 tr 构造 http.Client,向 /renew 端点发起 POST。这里 Transport 中必须配置好客户端证书,因为 CA 通过 mTLS 验证调用者身份后才允许续期。另外还提供 RenewWithToken 系列方法,用于证书已过期场景下携带授权 token 续期。
1.6 Provisioners:provisioner 查询与密钥获取
以下方法用于检查 provisioner 信息:一个返回 provisioner 列表,一个返回指定 provisioner 的加密密钥。
// 无选项时返回前 20 个 provisioner
provisioners, err := client.Provisioners()
// 可设置上限,最多 100
provisioners, err := client.Provisioners(ca.WithProvisionerLimit(100))
// 配合分页游标
provisioners, err := client.Provisioners(ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"))
// 两者组合
provisioners, err := client.Provisioners(
ca.WithProvisionerCursor("1f18c1ecffe54770e9107ce7b39b39735"),
ca.WithProvisionerLimit(100),
)
// 返回某个 provisioner 的加密密钥,即用于签发 token 的私钥的加密 JWE
key, err := client.ProvisionerKey("DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk")
对应实现为 ca/client.go 的 Provisioners 与 ProvisionerKey。示例源码注释提醒:服务器或普通客户端通常不需要这两个方法(token 的签名/验签由 step CLI 负责),它们主要面向管理类工具。
1.7 TLS Config:为服务器与客户端注入证书
下面演示如何构造可直接注入服务器与客户端的 tls.Config 对象。默认情况下这些方法会启动 Go routine,在证书生命周期过去约三分之二时自动续期。
// 获取可取消的 context 以停止续期 goroutine 和定时器
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 获取服务器用 tls.Config
tlsConfig, err := client.GetServerTLSConfig(ctx, sign, pk)
// 获取客户端用 tls.Config
tlsConfig, err := client.GetClientTLSConfig(ctx, sign, pk)
// 获取客户端 http.Transport,可作为 http.RoundTripper 用于 http.Client
tr, err := client.Transport(ctx, sign, pk)
从 ca/tls.go 的实现看:GetClientTLSConfig 返回配置了签名证书和根证书池的 tls.Config,且客户端证书到期前自动轮换;GetServerTLSConfig 默认只验证“若提供则验证”的客户端证书;Transport 则等价于 getClientTLSConfig 后取出其中的 http.RoundTripper。示例中还展示了将 tls.Config 挂到 http.Server.TLSConfig、http.Transport.TLSClientConfig 的标准用法。
1.8 运行 Basic Client
先启动证书颁发机构:
certificates $ bin/step-ca examples/pki/config/ca.json
2018/11/02 18:29:25 Serving HTTPS on :9000 ...
再用新 token 运行 client.go:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/basic-client/client.go $(step ca token client.smallstep.com)
程序会依次打印 Health、Root、Sign、Renew、Provisioners、Provisioner Key 等各方法的 JSON 响应,完整覆盖上文所有 API。
二、Bootstrap Client & Server:一行代码获得自动续期的 TLS 服务
第二个示例把 CA 和一个简单的 TLS 服务器、TLS 客户端一起跑起来,演示另外两个辅助方法——BootstrapServer 与 BootstrapClient。它们相比手动 NewClient + Sign + GetServerTLSConfig 的组合,把「解析 token → 申请证书 → 配置 TLS → 自动续期」整个流程封装成了一次调用(内部逻辑见 ca/bootstrap.go 的 BootstrapClient / BootstrapServer / BootstrapListener 及公共入口 createBootstrap)。
2.1 服务端:BootstrapServer(可选客户端证书)
// 获取可取消的 context 以停止续期 goroutine 和定时器
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 创建一个要求客户端证书的 http.Server
srv, err := ca.BootstrapServer(ctx, token, &http.Server{
Addr: ":8443",
Handler: handler,
})
if err != nil {
panic(err)
}
srv.ListenAndServeTLS("", "")
注意:示例实际使用的是 ca.VerifyClientCertIfGiven() 选项,即“若客户端提供了证书则验证,未提供也不强制”(见 examples/bootstrap-tls-server/server.go),对应 TLS 选项实现在 ca/tls_options.go。从 ca/bootstrap.go 的源码看,BootstrapServer 要求传入的 base.TLSConfig 必须为 nil,随后通过 GetServerTLSConfig 生成配置并回填;若 RequireClientAuth 为 false(服务端不强求客户端证书),还会自动追加 AddRootsToCAs() 选项以加载全部受信根。
2.2 服务端:BootstrapServerWithMTLS(严格 mTLS)
BootstrapServer 的默认行为其实是严格 mTLS(强制要求并验证客户端证书),示例特意用选项降级。若需要显式声明 mTLS 语义,可参考等价写法:
// 获取可取消的 context
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 创建不要求客户端证书的 http.Server
srv, err := ca.BootstrapServer(ctx, token, &http.Server{
Addr: ":8443",
Handler: handler,
}, ca.VerifyClientCertIfGiven())
if err != nil {
panic(err)
}
srv.ListenAndServeTLS("", "")
严格 mTLS 的完整演示在「三、Bootstrap mTLS Client & Server」中给出。
2.3 客户端:BootstrapClient
// 获取可取消的 context
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 创建 http.Client
client, err := ca.BootstrapClient(ctx, token)
if err != nil {
panic(err)
}
resp, err := client.Get("https://localhost:8443")
BootstrapClient(ca/bootstrap.go)返回一个已配置好 Transport 的 http.Client,Transport 内含 CA 签发的客户端证书,并在后台自动续期;服务端不强求客户端证书时还会自动追加 AddRootsToRootCAs()。示例客户端 examples/bootstrap-client/client.go 每秒向服务器发起一次请求并打印响应。
2.4 端到端运行验证
第一步,启动 Step CA:
certificates $ bin/step-ca examples/pki/config/ca.json
2018/11/02 18:29:25 Serving HTTPS on :9000 ...
第二步,启动 bootstrap-tls-server,输入 provisioner 密码 password:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-tls-server/server.go $(step ca token localhost)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
第三步,用系统证书包作为根去 curl,应当失败(系统信任列表里没有我们的私有 CA):
certificates $ curl https://localhost:8443
curl: (60) SSL certificate problem: unable to get local issuer certificate
...
第四步,改用 Step PKI 生成的根证书,请求成功:
certificates $ curl --cacert examples/pki/secrets/root_ca.crt https://localhost:8443
Hello nobody at 2018-11-03 01:49:25.66912 +0000 UTC!!!
响应中是 nobody,因为服务器未检测到 TLS 客户端证书。
第五步,用自带证书的客户端访问,服务器应能看到客户端证书的 Common Name:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-client/client.go $(step ca token Mike)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Server responded: Hello Mike at 2018-11-03 01:52:52.678215 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-03 01:52:53.681563 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-03 01:52:54.682787 +0000 UTC!!!
...
三、Bootstrap mTLS Client & Server:严格双向认证
本示例演示更严格的服务器配置:强制要求客户端提供有效证书(mTLS)。服务端源码 examples/bootstrap-mtls-server/server.go 与 TLS 版几乎相同,唯一区别是不传 ca.VerifyClientCertIfGiven() 选项,从而保留 BootstrapServer 默认的强制 mTLS 行为。
启动 CA:
certificates $ bin/step-ca examples/pki/config/ca.json
2018/11/02 18:29:25 Serving HTTPS on :9000 ...
启动 mTLS 服务器,输入密码 password:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-mtls-server/server.go $(step ca token localhost)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
此时即使携带正确的根证书包,curl 也会失败——因为服务器强制要求客户端证书:
certificates $ curl --cacert examples/pki/secrets/root_ca.crt https://localhost:8443
curl: (35) error:1401E412:SSL routines:CONNECT_CR_FINISHED:sslv3 alert bad certificate
改用我们的客户端(启动时向 Step CA 申请证书)则成功:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-client/client.go $(step ca token Mike)
✔ Key ID: DmAtZt2EhmZr_iTJJ387fr4Md2NbzMXGdXQNW1UWPXk (mariano@smallstep.com)
Please enter the password to decrypt the provisioner key:
Server responded: Hello Mike at 2018-11-07 21:54:00.140022 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-07 21:54:01.140827 +0000 UTC!!!
Server responded: Hello Mike at 2018-11-07 21:54:02.141578 +0000 UTC!!!
...
四、证书轮换(Certificate Rotation)机制解析
我们可以用 bootstrap 服务器演示证书自动轮换。CA 配置中增加了第二个 provisioner mike@smallstep.com,其默认证书有效期仅 2 分钟:
certificates $ export STEPPATH=examples/pki
certificates $ export STEP_CA_URL=https://localhost:9000
certificates $ go run examples/bootstrap-server/server.go $(step ca token localhost)
✔ Key ID: YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs (mike@smallstep.com)
Please enter the password to decrypt the provisioner key:
Listening on :8443 ...
证书将在有效期过去约 2/3 后轮换,本例即 74–80 秒之间。精确公式为:
<duration> - <duration>/3 - rand(<duration>/20)
(duration=120 秒时:120 − 40 − 随机 0~6 秒)。该公式与源码完全吻合——ca/renew.go 中 TLSRenewer 的默认参数为 renewBefore = period / 3(提前三分之一个周期续期)、renewJitter = period / 20(抖动为二十分之一个周期,用于打散大规模续期请求),Run 方法用 time.AfterFunc 调度下一次续期。WithRenewBefore / WithRenewJitter 可覆盖这两个默认值。
用如下命令观察证书是否在 74–80 秒后发生变化:
certificates $ step certificate inspect --insecure https://localhost:8443
五、NGINX + Step CA 证书:Docker 组合部署
docker 目录下的示例展示如何将 Step CA 与 NGINX 结合,为服务提供由 Step CA 签发的证书。它构建 3 个不同的 Docker 镜像:
- nginx-test:NGINX 镜像,内置使用 inotify-tools 监控证书文件变化并自动 reload NGINX 的脚本;
- step-ca-test:Step CA 镜像;
- step-renewer-test:step CLI 工具镜像,负责创建证书,并设置 cron 每 1 分钟续期(测试用途)。
运行前提是 Docker daemon 已启动。切换到 examples/docker 目录后执行 make:
certificates $ cd examples/docker/
docker $ make
GOOS=linux go build -o ca/step-ca github.com/smallstep/certificates/cmd/step-ca
GOOS=linux go build -o renewer/step github.com/smallstep/cli/cmd/step
docker build -t nginx-test:latest nginx
...
docker-compose up
WARNING: The Docker Engine you're using is running in swarm mode.
...
Creating network "docker_default" with the default driver
Creating docker_ca_1 ... done
Creating docker_renewer_1 ... done
Creating docker_nginx_1 ... done
Attaching to docker_ca_1, docker_renewer_1, docker_nginx_1
ca_1 | 2018/11/12 19:39:16 Serving HTTPS on :443 ...
nginx_1 | Setting up watches.
nginx_1 | Watches established.
...
make 会依次执行(对应 examples/docker/Makefile):编译 step-ca 与 step 二进制(binaries)→ 构建 3 个镜像(build)→ docker-compose up 启动容器(up)。
NGINX 监听本机 https://localhost:4443。为让证书域名校验通过,需要在 /etc/hosts 中添加:
127.0.0.1 nginx
然后用 cURL 验证:
docker $ curl --cacert ca/pki/secrets/root_ca.crt https://nginx:4443/
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...
用 make inspect 可观察到证书每分钟轮换一次:
docker $ make inspect | head
step certificate inspect https://localhost:4443 --insecure
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 220353801925419530569669982276277771655 (0xa5c6993a7e110e6f009c83c79edc1d87)
Signature Algorithm: ECDSA-SHA256
Issuer: CN=Smallstep Intermediate CA
Validity
Not Before: Nov 10 02:13:00 2018 UTC
Not After : Nov 11 02:13:00 2018 UTC
docker $ make inspect | head
step certificate inspect https://localhost:4443 --insecure
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 207756171799719353821615361892302471392 (0x9c4c621c04d3e8be401ff0d14c5440e0)
Signature Algorithm: ECDSA-SHA256
Issuer: CN=Smallstep Intermediate CA
Validity
Not Before: Nov 10 02:14:00 2018 UTC
Not After : Nov 11 02:14:00 2018 UTC
对比两次输出的 Serial Number 与 Not Before/Not After 可知证书已轮换。演示结束后清理容器与卷:
docker $ make down
docker-compose down
Stopping docker_nginx_1 ... done
Stopping docker_renewer_1 ... done
Stopping docker_ca_1 ... done
Removing docker_nginx_1 ... done
Removing docker_renewer_1 ... done
Removing docker_ca_1 ... done
Removing network docker_default
六、Basic Federation:多 CA 联邦
basic-federation 示例演示如何让多个自治证书颁发机构的依赖方(relying parties)安全通信。当服务分散在多个独立的 Kubernetes 集群、公有云或 Serverless 云函数之间时,联邦(Federation)正是打通跨边界服务通信所需的机制。
注意:该示例使用预生成的 PKI(公私钥材料),仅供示例演示,严禁在开发、预发或生产环境复用。
6.1 启动两个在线 CA
同时启动 Cloud CA 与 Kubernetes CA:
$ step-ca ./pki/cloud/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:38:52 Serving HTTPS on :1443 ...
$ step-ca ./pki/kubernetes/config/ca.federated.json
Please enter the password to decrypt intermediate_ca_key: password
2019/01/22 13:39:44 Serving HTTPS on :2443 ...
对比两种配置差异:Cloud CA 会在 federatedRoots 中列出 Kubernetes CA,反之亦然:
$ diff pki/cloud/config/ca.json pki/cloud/config/ca.federated.json
3c3
< "federatedRoots": [],
---
> "federatedRoots": ["pki/cloud/certs/kubernetes_root_ca.crt"],
6.2 启动演示服务器
演示服务器利用 ca SDK 自动申请证书、自动续期并拉取受信根集合。启动时会打印它将用于认证客户端证书的根证书列表(源码见 examples/basic-federation/server/main.go,其中 ListTrustedRoots 通过 ctx.Client.Federation() 与 ctx.Client.Roots() 对比,当联邦证书多于本地根时提示 "Server is using federated root certificates"):
go run server/main.go $(step ca token \
--ca-url https://localhost:1443 \
--root ./pki/cloud/certs/root_ca.crt \
127.0.0.1)
✔ Key ID: EE1ZiqkMaxsUdpz8SCSkRBzwK9TWUoidQnMnJ8Eryn8 (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server is using federated root certificates
Accepting certs anchored in CN=Smallstep Public Cloud Root CA
Accepting certs anchored in CN=Smallstep Kubernetes Root CA
Listening on :8443 ...
服务器通过 ca.AddFederationToClientCAs() 选项把联邦根注入客户端证书校验池(对应 ca/tls_options.go 的实现)。
6.3 运行演示客户端
SDK 同样提供客户端侧选项来对服务器做双向认证:自动处理证书引导、续期并拉取受信根集合。演示客户端每 5 秒向服务器发送一次 HTTP 请求(源码见 examples/basic-federation/client/main.go,通过 ca.AddFederationToRootCAs() 把联邦根加入信任根池):
$ go run client/main.go $(step ca token sdk_client \
--ca-url https://localhost:2443 \
--root ./pki/kubernetes/certs/root_ca.crt)
✔ Key ID: S5gYgpeqcIAgc1Zr4myZXpgJ_Ao4ryS6F6wqg9o8RYo (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key: password
Server responded: Hello sdk_client (cert issued by 'Smallstep Kubernetes Root CA') at 2019-01-23 00:51:38.576648 +0000 UTC
6.4 用 curl 扮演客户端
先用 Kubernetes CA 签发一个客户端证书:
$ step ca certificate kube_client kube_client.crt kube_client.key \
--ca-url https://localhost:2443 \
--root pki/kubernetes/certs/root_ca.crt
✔ Key ID: S5gYgpeqcIAgc1Zr4myZXpgJ_Ao4ryS6F6wqg9o8RYo (sebastian@smallstep.com)
✔ Please enter the password to decrypt the provisioner key:
✔ CA: https://localhost:2443/1.0/sign
✔ Certificate: kube_client.crt
✔ Private Key: kube_client.key
联邦依赖“多个受信根组成的 bundle”,需要先通过 step ca federation 从 Cloud CA 拉取(内含 Cloud Root CA 与联邦配置的 Kubernetes Root CA):
$ step ca federation --ca-url https://localhost:1443 \
--root pki/cloud/certs/root_ca.crt \
federated.pem
The federation certificate bundle has been saved in federated.pem.
最后把证书与联邦 bundle 一起交给 curl:
$ curl -i --cacert federated.pem \
--cert kube_client.crt \
--key kube_client.key \
https://127.0.0.1:8443
HTTP/2 200
content-type: text/plain; charset=utf-8
content-length: 105
date: Mon, 28 Jan 2019 15:24:54 GMT
Hello kube_client (cert issued by 'Smallstep Kubernetes Root CA') at 2019-01-28 15:24:54.864373 +0000 UTC
由于演示服务器已通过 Cloud CA 的联邦配置信任 Kubernetes CA 签发的证书,连接成功建立。
七、Custom Claims:自定义证书有效期
先用示例配置启动 CA:
certificates $ step-ca examples/pki/config/ca.json
2019/03/11 13:37:03 Serving HTTPS on :9000 ...
该示例配置了多个 provisioner 选项,其中两个通过 custom claims 扩展了证书有效期:
$ step ca provisioner list | jq '.[] | "\(.name): \(.claims.defaultTLSCertDuration)"'
# null 表示使用 step 默认的 24h 证书有效期
"mariano@smallstep.com: null"
"mike@smallstep.com: 2m0s"
"decade: 87600h0m0s"
"90days: 2160h0m0s"
查看 90days provisioner 的详细 claims 配置:
$ step ca provisioner list | jq '.[3].claims'
{
"maxTLSCertDuration": "2160h0m0s",
"defaultTLSCertDuration": "2160h0m0s"
}
对应到配置文件 examples/pki/config/ca.json 中,90days 与 decade provisioner 都设置了 claims.maxTLSCertDuration 与 claims.defaultTLSCertDuration(分别对应 2160h 与 87600h),而 mike@smallstep.com 额外设置了 minTLSCertDuration: 1m0s。这些 claims 直接约束了后续签发证书的 Validity 区间。
不同有效期的证书可以用对应 provisioner 生成。Duration 是形如 "300ms"、"2h45m" 的字符串——由十进制数字序列(可带小数)加单位后缀组成,合法时间单位有 ns、us(或 µs)、ms、s、m、h。
$ step ca certificate decade decade.crt decade.key
✔ Key ID: iu7VZxKUcquv1BCWuvEUOyRy4zYyCmgt61OpRW5VbRE (decade)
✔ Please enter the password to decrypt the provisioner key: password
✔ CA: https://localhost:9000/1.0/sign
✔ Certificate: decade.crt
✔ Private Key: decade.key
$ step certificate inspect --format json decade.crt | jq .validity
{
"start": "2019-03-11T22:34:30Z",
"end": "2029-03-08T22:34:30Z",
"length": 315360000
}
$ step ca certificate 90days 90days.crt 90days.key
✔ Key ID: 2LgjIvfirblnFMC6FjUr8jYkO8nOqz4rKoarCc8kiGU (90days)
✔ Please enter the password to decrypt the provisioner key: password
✔ CA: https://localhost:9000/1.0/sign
✔ Certificate: 90days.crt
✔ Private Key: 90days.key
$ step certificate inspect --format json 90days.crt | jq .validity
{
"start": "2019-03-11T22:35:39Z",
"end": "2019-06-09T22:35:39Z",
"length": 7776000
}
decade 证书的有效期为 315360000 秒(约 10 年),90days 为 7776000 秒(90 天),与 claims 配置一一对应。
八、配置管理工具集成(Puppet)
Puppet、Chef、Ansible、Salt 等配置管理工具能让自动化与部署变得更轻松可控。Step CLI 与 CA 从设计之初就面向自动化,可以很方便地用你喜欢的工具进行配置。
Puppet 场景提供了三个可直接加入 Puppet manifest 的片段文件(均位于 examples/puppet):
- step.pp:从源码安装
step,并配置step用户、组与主目录,供 Step CLI 和 CA 使用; - step_ca.pp:从源码安装
step-ca,配置证书与密钥并运行 Step CA; - tls_server.pp:你的服务接入 Step CA SDK,申请、接收并续期 TLS 证书的模板,可参考 bootstrap-tls-server/server.go 的简单集成示例。
注意:这是一个大幅简化的示例,无法独立运行。完整的 Puppet 配置应配合服务管理器(如 systemctl)与密钥存储(如 Hiera)使用。
仓库还提供了 Ansible 角色示例:smallstep-certs(证书签发)、smallstep-install(安装 step/step-ca)、smallstep-ssh(SSH 证书),用法与 Puppet 示例互补,可按需选择。
总结与进一步探索
从 ca.Client 的 8 类基础方法,到 Bootstrap* 系列的一站式引导,再到证书自动轮换的精确时机公式(duration - duration/3 - rand(duration/20))、Docker + NGINX 组合编排、双 CA 联邦与 Custom Claims 有效期控制,examples 目录完整覆盖了 Step CA 在生产自动化中的典型集成模式。若要深入底层,可继续阅读 ca/client.go、ca/bootstrap.go、ca/renew.go 与 ca/tls_options.go 的源码实现,或参考 ca/client_test.go 与 ca/bootstrap_test.go 中的端到端测试用例来验证各 API 的实际行为。