认证
访问 ctrl 的请求经 mTLS 用 Operator 身份认证，访问 node 数据面的请求带一张短期的会话凭证。本页介绍程序怎样获得 Operator 身份、两个入口的 TLS 怎样配置，以及怎样持续续期。
概述
已注册的 Operator 拥有集群管理权限，可以调用 Workspace API 和 Operator API。仅信任服务端证书不能获得任何权限。
身份是 ctrl 签发的客户端证书，有效期 30 天。程序有两种方式获得身份：
| 方式 | 程序做什么 |
|---|---|
| 读取 kibo 的 context 目录 | 读取 kibo context enroll 为它注册的目录里的文件 |
| 自己完成注册 | 调用 kibotos.enrollment.v1.EnrollmentService/Enroll，用注册密钥换取身份 |
访问 node 数据面的请求改用会话凭证认证，凭证由程序向 ctrl 申请，见数据面。
获得 Operator 身份
读取 kibo 的 context 目录
最简单的方式是用 kibo context enroll 为程序注册一个专用目录：
- 用
kibo enrollment create --operator为程序签发一把注册密钥。 - 把
KIBO_CONTEXT_DIR设为程序要读取的目录，执行注册。 - 注册成功后删除密钥文件。
下面的命令为名为 build-bot 的 Operator 签发密钥，把它注册到单独的目录，再删除密钥：
kibo enrollment create --operator build-bot --output build-bot.key
KIBO_CONTEXT_DIR="$HOME/.config/build-bot/kibo-context" kibo context enroll --endpoint https://ctrl.example.com:18092 --key-file build-bot.key
rm build-bot.key提供密钥的其他方式与代理设置见身份与注册。
目录默认在 $XDG_CONFIG_HOME/kibo/context，未设置时为 ~/.config/kibo/context；环境变量 KIBO_CONTEXT_DIR 可以指向其他位置。
重要
每个程序使用自己的目录。不要让程序读取你自己的 kibo 正在使用的目录，也不要让几个程序共用一个目录。使用者各自续期，ctrl 只接受一个身份的当前与上一张证书，使用者超过两个时总有一个被拒绝。
目录中有这些文件：
| 文件 | 用途 |
|---|---|
context.json | ctrl 地址 endpoint，以及可选的代理 proxy |
manifest.json | 记录其余文件的文件名与身份 URI |
identity-<serial>.pem / identity-<serial>.key | 客户端证书与私钥，用于 mTLS |
server-ca.pem | ctrl 的服务端 CA。访问 ctrl 时只信任它，不使用系统根证书，见TLS 配置 |
control-client-ca.pem | 签发客户端证书的 CA，用于本地校验 |
Go 程序可以用 Go SDK 打开这个目录，SDK 也负责续期。
自己完成注册
程序也可以直接使用注册密钥。Operator 用 kibo enrollment create --operator <id> 生成的密钥是一个三段式字符串：
kek1.<引导证书 DER>.<引导私钥 PKCS#8 DER>.<服务端 CA DER>三段都是 base64url 编码。用引导证书和私钥做 mTLS，信任第三段的服务端 CA，调用 kibotos.enrollment.v1.EnrollmentService/Enroll：
- 请求只有一个字段
certificate_request：DER 编码的 PKCS#10 CSR，不超过 8 KiB，不带扩展和名字。ctrl 忽略 CSR 中的 subject，身份完全由密钥对应的授权决定。 - 响应是
IssuedIdentity：identity_uri（形如spiffe://<trust-domain>/operator/<id>）、certificate（DER 证书）、ca_certificate（DER 格式的客户端 CA）、serial、not_before、not_after。私钥始终在客户端。 - 引导身份只能调用
Enroll。正式身份只能调用Renew，不能再调用Enroll。这个限制在服务端读取请求体之前就生效。 - 同一把密钥使用第二次返回
already_exists。
保存身份前，建议像 kibo 一样校验：
- CA 属于预期的信任域。
- 证书链有效。
- 证书中的公钥与自己的私钥匹配。
- URI 的类型和主体正确。
- 用途扩展和有效期合理。
请求与响应的消息见 EnrollmentService。
TLS 配置
ctrl 与 node 数据面验证服务端的方式不同，客户端按入口分别配置：
| 配置项 | ctrl | node 数据面 |
|---|---|---|
| 信任的 CA | 只信任 server-ca.pem，不使用系统根证书 | 系统根证书加上 server-ca.pem |
| 主机名 | 证书的 SAN 必须与地址中的主机名精确匹配 | 按标准规则校验 |
| 客户端凭据 | Operator 身份的证书与私钥，用于 mTLS | 放在 Authorization: Bearer 头里的会话凭证 |
| HTTP 重定向 | 不跟随 | 不跟随 |
访问 ctrl 时还要求 TLS 1.3 以上，ALPN 声明 h2。
数据面这样信任证书，部署方就可以把 node 放在公网 TLS 反向代理后面。证书怎样签发、node 的数据面证书覆盖哪些主机名，见服务端证书与数据面证书。
续期
身份有效期 30 天，剩余不到 10 天时应续期。
续期是用当前身份调用 kibotos.enrollment.v1.EnrollmentService/Renew，请求体是一个新私钥的 CSR。kibo context renew 做的就是这件事。
把请求换到新证书上
TLS 连接一直出示握手时的证书，一直有请求的连接也不会因空闲而关闭。
重要
长期运行的程序续期后，新请求要在出示新证书的连接上发出。继续使用续期前建立的连接，再续期一次后，其上的请求都会被拒绝。
各类证书的有效期、撤销与恢复见续期、撤销与恢复。