【免费下载链接】openpencilThe worlds first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址https://gitcode.com/gh_mirrors/op/openpencil点击查看免费下载本篇技术指南围绕 OpenPencil 协作中继collab relay体系中一个关键的安全组件展开为 relay locator 提供 Ed25519 签名的OPLSOpenPencil Locator SigningUnix-socket 适配器op-collab-relay-locator-hsm。该组件以独立的非 root 容器形态运行通过 Unix 域套接字与 locator 进程通信将私钥与 PIN 严格隔离在无网络命名空间内。读完本文你将掌握该适配器的威胁模型与协议细节、密钥画像active next 双密钥、宿主机准备步骤、初始化与签发provision流程、生产启动与健康检查、AB → BC 的无缝密钥轮换以及基于真实 SoftHSM 的集成验证方法。一、设计定位为什么 locator 的私钥要单独隔离relay locator 负责签发出行凭证relay locator其签名的权威性依赖于一把专用的 Ed25519 私钥。如果这把私钥直接放在 locator 进程内一旦 locator 被攻破私钥随即泄露。OpenPencil 的做法是将私钥从 locator 中剥离交给一个独立运行的签名适配器容器。从 lib.rs 的 crate 级文档可以看到其安全模型的四条支柱调用方身份只信任 Unix peer credentials通过SO_PEERCREDLinux/getpeereidBSD获取对端 UID/GID 进行鉴权绝不信任请求载荷中自述的身份配置与 PIN 文件严格校验读取前必须验证 owner、mode、link count并以O_NOFOLLOW打开防止被替换的符号链接重定向读取监听套接字、flock 锁文件、心跳文件均以显式 mode 创建并在服务任何请求前按 uid/gid/mode 预期重新校验连配置 schema 都是 POSIX 形态的配置里携带预期的客户端 uid/gid 与受sun_path限制的套接字路径。整个 crate 以cfg(unix)门控——在 Windows 上编译这些所有权与 peer 身份检查要么意味着悄悄关闭它们、要么需要发明未经审计的 ACL 替代品因此二进制在非 Unix 平台会打印UNSUPPORTED_PLATFORM错误并退出而不是提供一个看起来还能工作的弱化版本。部署上的隔离则由 compose.yaml 落实network_mode: none无网络命名空间、read_only: true、cap_drop: ALL、no-new-privileges: true、pids_limit: 64、mem_limit: 128m。只有这个容器能挂载 SoftHSM token 目录和 user PINlocator 容器对signer.sock只读既读不到 token 存储也读不到 PIN 和私钥。二、OPLS v1 协议单连接单请求339 字节定长帧适配器与 locator 之间运行一个极简的私有协议OPLSOpenPencil Locator Signingv1定义在 protocol.rspub const OPLS_VERSION: u8 1; pub const REQUEST_BYTES: usize 4 1 1 1 64 LOCATOR_CANONICAL_SIGNING_BYTES; // 411164268 339 pub const RESPONSE_BYTES: usize 4 1 1 64; // 70请求帧339 字节OPLS魔数4 字节→ 协议版本1 字节恒为 1→ 操作码1 字节SIGN_OPERATION 1→ key id 长度1 字节→ 64 字节定长 key id 槽位右侧零填充→ 268 字节 canonical 签名输入。响应帧70 字节OPLR魔数4 字节→ 版本1 字节→ 状态码1 字节0 OK1 REJECTED→ 64 字节 Ed25519 签名。其中 268 字节的签名输入正是 relay 协议中 locator 的 canonical 签名字节见 locator.rs 的LOCATOR_CANONICAL_SIGNING_BYTES: usize 268因此适配器不改变既有 268 字节签名输入的形态——locator 端照常构造 canonical 字节只是把签名动作委托出去。服务端在签名前会做双重校验key id 校验decode_request长度非零且不超过MAX_LOCATOR_KEY_ID_BYTES64槽位剩余部分必须为零填充字符需落在可打印 ASCII0x21..0x7e区间并且必须精确等于配置的active_kidlocator 域校验validate_locator_domaincanonical 字节的第 0 字节必须是RELAY_PROTOCOL_VERSION1第 1 字节必须是本区域 wire 值cn 1global 2route id、generation、owner static 字段不能全零expected discovery id 与 key id 需满足定长槽位的零填充 ASCII 规则not_before非零、expires not_before且配对窗口不超过MAX_PAIRING_LIFETIME_SECS3600 秒即 1 小时。连接语义server.rs每个连接只接受恰好一个 339 字节请求随后再读 1 字节并期望 EOF——若有任何尾部字节直接回复REJECTED。读写均受request_timeout_ms配置项默认 2000ms超时保护。所有校验失败统一走SignerError::Rejected对外只回OPLR拒绝帧不暴露内部原因。三、密钥画像active next 双密钥与非导出约束适配器的配置里恰好有两把公钥条目active当前生效与 next轮换预备。active_kid必须精确标识其中一把见 config.rs 的校验active_kid must identify exactly one configured key。3.1 配置项与约束配置文件 schema 定义在 config.rsvalidate()强制的边界包括字段含义校验规则源码依据version配置版本必须等于 1region区域cn或global对应 wire 值 1 / 2socket_path监听套接字路径绝对路径、无..穿越、不超过 100 字节Unix socket 限制expected_client_uid/gid期望的 locator 身份必须非 rootpkcs11_module_pathSoftHSM 模块路径绝对、有界、无父目录穿越token_labeltoken 标签1–32 字节安全 ASCIIpin_fileuser PIN 文件路径绝对、有界、无父目录穿越active_kid当前生效 key id1–64 字节安全 ASCII且必须恰好匹配keys中一个条目keys密钥对列表必须恰好两条active nextkid 与 object_id 全局唯一request_timeout_ms单请求超时100–5000默认 2000安全 ASCII指is_safe_asciiconfig.rs仅允许 ASCII 字母、数字以及-、_、.。object_id_hex必须是小写十六进制、1–32 字节长度。若历史环境里还沿用包含其他标点的可打印 wire id必须在使用本适配器前完成迁移。仓库附带的 config.example.json 展示了完整示例{ version: 1, region: global, socket_path: /run/openpencil-hsm/signer.sock, expected_client_uid: 65532, expected_client_gid: 65532, pkcs11_module_path: /usr/lib/softhsm/libsofthsm2.so, token_label: openpencil-locator-global, pin_file: /run/secrets/locator-hsm-pin, active_kid: replace-with-active-public-kid, keys: [ { kid: replace-with-active-public-kid, object_id_hex: 7101 }, { kid: replace-with-next-public-kid, object_id_hex: 7102 } ], request_timeout_ms: 2000 }3.2 启动时的属性强制校验KeyStore::open在启动时对两把密钥逐一执行load_pairpkcs11.rs要求每个 object id 与 label 恰好标识一对隔离的公私钥对象并校验属性类型CKK_EC_EDWARDS、Ed25519 参数SoftHSM 使用 PKCS#11 定义的PrintableString形式edwards25519、KeyGenMechanism CKK_EC_EDWARDS_KEY_PAIR_GEN、Local true密钥在 token 本地生成私钥CKA_SENSITIVE true、CKA_EXTRACTABLE false、CKA_ALWAYS_SENSITIVE true、CKA_NEVER_EXTRACTABLE true用途私钥仅CKA_SIGN true、公钥仅CKA_VERIFY trueCKA_DERIVE false持久化CKA_TOKEN true、label/object id 精确匹配且不存在重复的配对对象。3.3 公钥导出两种下游格式initialize与provision都不导出私钥字节。public命令输出PublicKeySet{version:1,keys:[{kid:...,public_key_ed25519:...}]}其中public_key_ed25519是 32 字节公钥的 base64url 无填充编码pkcs11.rs。这份格式正是 relay 侧 key-file 解析器接受的格式pinned_locator_keys.rsversion: 1kidpublic_key_ed25519单文件上限 64KB、最多 64 把。而 signed desktop bootstrap 使用的 JWKS 中同一个 base64url 公钥值放在x字段下见 collab_jwks.rs 中kty:OKP,crv:Ed25519,alg:Ed25519,use:sig,key_ops:[verify],kid:...,x:URL_SAFE_NO_PAD.encode(public_key)的构造。四、宿主机准备目录、PIN、tmpfiles 与 Compose 输入4.1 数字身份约定仓库内联镜像使用的固定身份为locator65532:65532signer65533:65532共享 gid。CN 与 Global 两个区域必须使用独立的目录、token 标签、key id 与 object id具体的公网主机与生成的 key id 属于私有部署清单不应进入本仓库。4.2 外部宿主路径在每个区域 Linux 宿主机上准备命令来自 README.mdsudo install -d -o 65533 -g 65532 -m 0700 /secure/openpencil/locator-hsm/tokens sudo install -o 65533 -g 65532 -m 0400 /dev/null /secure/openpencil/locator-hsm/user-pin sudo install -o 65533 -g 65532 -m 0400 /dev/null /secure/openpencil/locator-hsm/so-pin sudo install -o root -g 65532 -m 0440 \ deploy/collab-relay-locator-hsm/config.example.json \ /secure/openpencil/locator-hsm/config.json sudo install -o root -g root -m 0644 \ deploy/collab-relay-locator-hsm/openpencil-locator-hsm.conf \ /etc/tmpfiles.d/openpencil-locator-hsm.conf sudo systemd-tmpfiles --create /etc/tmpfiles.d/openpencil-locator-hsm.conf要点示例中的 region、token label、active/next 公钥 id、唯一 object id 都必须替换为实际值两个 PIN 文件通过运营方秘密通道填充严禁把 PIN 写到命令行、Compose environment 或 shell 历史Docker 文件型挂载会保留宿主所有权而忽略uid/mode声明所以必须确认宿主机上的数字权限符合预期仓库内联的 tmpfiles 规则d /run/openpencil/locator-hsm 0770 root 65532 -会在每次启动后重建易失的/run套接字目录属主root:65532、mode0770。必须在 Compose 之前安装绝不要让 Docker 以root:root0755自动创建缺失的 bind 源目录。4.3 Compose 输入变量export OPENPENCIL_COLLAB_HSM_CONFIG_HOST_FILE/secure/openpencil/locator-hsm/config.json export OPENPENCIL_COLLAB_HSM_PIN_HOST_FILE/secure/openpencil/locator-hsm/user-pin export OPENPENCIL_COLLAB_HSM_TOKEN_HOST_DIR/secure/openpencil/locator-hsm/tokens export OPENPENCIL_COLLAB_HSM_SOCKET_HOST_DIR/run/openpencil/locator-hsm这些变量在 compose.yaml 中通过${VAR:?set absolute ...}强制必填分别以只读 bind 挂载到容器内/run/openpencil-config/locator-hsm.json、/run/secrets/locator-hsm-pin以及直接挂载 token 目录可写与/run/openpencil-hsm套接字目录。五、初始化 token 与逐把签发密钥签名适配器二进制支持五个子命令解析逻辑见 main.rsserve、check、public、provision --kid KID、initialize --so-pin-file PATH均需--config PATH。5.1 构建镜像并初始化空 tokenSO PIN 是一次性额外挂载不属于运行态服务的一部分docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ build locator-hsm docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm \ -v /secure/openpencil/locator-hsm/so-pin:/run/secrets/locator-hsm-so-pin:ro \ locator-hsm initialize --config /run/openpencil-config/locator-hsm.json \ --so-pin-file /run/secrets/locator-hsm-so-pininitializepkcs11.rs要求存储中恰好有一个未初始化 slot、其余 slot 已初始化数量为 0并且拒绝覆盖已存在的同名 token label随后以 SO PIN 初始化 token、以 SO 会话登录并设置 user PIN。5.2 逐把 provision两把配置好的 key id 必须一次一把地签发。这样部分失败是显式的且绝不在静默中复用或替换既有对象docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm provision \ --config /run/openpencil-config/locator-hsm.json --kid replace-with-active-public-kid docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm provision \ --config /run/openpencil-config/locator-hsm.json --kid replace-with-next-public-kidprovisionpkcs11.rs先用require_id_and_label_absent确认 object id 与 label 均不存在防止覆盖再以CKK_EC_EDWARDS_KEY_PAIR_GEN机制生成密钥对随后用该私钥签名一把 locator 形态的 canary 并软件验签通过后才返回公钥记录。集成测试 softhsm.rs 还验证了对已签发的 key 再次 provision 必须报错。5.3 导出公钥候选文件并分发docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm public \ --config /run/openpencil-config/locator-hsm.json /secure/public/locator-keys.candidate.json校验该候选文件后把同一组 activenext分发给 relay 与 signed desktop bootstrap再开始签发流量。SO PIN 在把恢复副本放入运营方控制的秘密系统后应从日常操作中移除文件与挂载一并移除。六、生产启动、就绪检查与健康探针只有当公开策略文件collab-policy与公钥文件都就绪后才把 signer 与 locator 一起启动export OPENPENCIL_COLLAB_POLICY_HOST_FILE/secure/public/collab-policy.json export OPENPENCIL_COLLAB_LOCATOR_HSM_KEY_IDreplace-with-active-public-kid export OPENPENCIL_COLLAB_LOCATOR_HSM_PEER_UID65533 export OPENPENCIL_COLLAB_LOCATOR_HSM_PEER_GID65532 docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ -f deploy/collab-relay-locator/compose.yaml \ -f deploy/collab-relay-locator/compose.production.global.yaml \ -f deploy/collab-relay-locator/compose.hsm.yaml \ up --build -d上面是 Global 区域命令CN 区域只需把区域 overlay 换成compose.production.cn.yaml。这些 overlay硬编码了匹配的 home region 与宿主 bind没有可覆盖的 host-bind 变量。6.1 就绪语义双重校验 canaryserve启动前与check命令都会KeyStore::open加载两对密钥并逐一执行readiness_canary——用每把私钥对 locator 形态的 canary 做 HSM 签名并立即软件验签canary 构造见 protocol.rsprobe_socket再校验已绑定的套接字与心跳新鲜度。容器健康检查由 Dockerfile 定义每 30s 执行一次check同时要求 Unix 套接字存在、主服务循环写出的心跳文件signer.ready在 10 秒内更新过server.rs。locator 侧通过 compose.hsm.yaml 的depends_on: locator-hsm: condition: service_healthy等待 signer 健康后才启动。6.2 套接字与文件的安全加固监听套接字创建后强制 mode0660绑定前逐层校验父目录非符号链接、属主/权限安全并用flock独占锁文件signer.lockmode0600防止双实例server.rs退出时通过SocketGuard记录 device/inode仅在套接字身份未变时才清理残留每个连接先以SO_PEERCREDLinuxserver.rs校验对端 uid/gid 必须等于配置的expected_client_uid/gid即 locator65532:65532不匹配直接拒绝配置与 PIN 的读取secure_file.rs配置必须是单链接常规文件、属主为 root 或 signer uid、group/other 不可写mode 0o022 0、大小上限 16KBPIN 文件必须是 signer uid 属主、mode 严格0400、8–128 字节可打印 ASCII 且无结尾换行读入后用Zeroizing包裹以便退出时清零。七、密钥轮换AB → BC全程无空窗轮换采用先扩大验证集合、再收窄到新集合的策略从 A(active)B(next) 迁移到 BC先全量发布 AB确认 relay 与 signed desktop bootstrap 都已持有当前 AB 集合准备候选配置构造 B(active)C(next) 的候选SignerConfig将其挂载进一次性 signerprovision C导出 BC 候选公钥文件合并重叠验证集把当前与候选公钥文件合并为 ABC 重叠 bundle。relay 的 pinned verifier 最多接受 64 把密钥源码依据 pinned_locator_keys.rs 的MAX_PINNED_VERIFIER_KEYS: usize 64jq -s {version: 1, keys: ([.[].keys[]] | unique_by(.kid))} \ /secure/public/locator-keys.current.json \ /secure/public/locator-keys.candidate.json \ /secure/public/locator-keys.overlap.json原子切换向 relay 与 signed desktop bootstrap 分发 ABC原子安装 BC signer 配置重启 signer 与 locator保留 A 一段时间在最大 locator 生命周期与回滚窗口内继续把 A 保留在 verifier bundle 中之后才单独发布 BC。注意signer 的public命令只输出其配置中的成对密钥不做 verifier 历史合并本适配器故意没有密钥销毁命令退役是独立且需审计的 token 管理操作。每次启动或晋升时locator 的OPENPENCIL_COLLAB_LOCATOR_HSM_KEY_ID必须与 signer 配置的active_kid完全一致locator 侧解析见 production.rs比对逻辑见 hsm.rs。在开放流量前应执行一次带认证的 locator 签发并用新分发的公钥验证返回签名。八、验证与集成测试仓库的 Docker 测试目标在真实 SoftHSM 模块上运行集成测试docker build --target test \ -f deploy/collab-relay-locator-hsm/Dockerfile . docker build -f deploy/collab-relay-locator-hsm/Dockerfile .--target test阶段Dockerfile安装softhsm2并设置OPENPENCIL_SOFTHSM2_MODULE/usr/lib/softhsm/libsofthsm2.so运行cargo test --locked -p op-collab-relay-locator-hsm --test softhsm。该测试softhsm.rs使用临时 token 目录与临时softhsm2.conf完整演练initialize → 两把逐次 provision并断言重复 provision 失败→ open 后导出 2 把公钥 → 对 canary 签名并verify_strict软件验签 →篡改区域 wire 值后签名必须被拒绝。运行时镜像则以 Debian bookworm-slim 为基础创建openpencil-locator-hsm用户uid 65533、gid 65532安装softhsm2通过SOFTHSM2_CONF/etc/openpencil-softhsm2.conf指向仓库内联的 softhsm2.confdirectories.tokendir/var/lib/openpencil-softhsm/tokens/、objectstore.backendfile、log.levelERROR、slots.removablefalse最终以USER 65533:65532运行默认CMD [serve, ...]。九、小结安全边界一览本适配器的核心价值在于把私钥所在与私钥使用者拆到两个不同信任域locator 只见一个只读的 Unix 套接字它既看不到 token 目录、PIN也看不到私钥对象签名请求必须同时通过 peer credential 身份校验、key id 精确匹配、区域与窗口语义校验且每次 HSM 签名在返回前都要用 token 公钥做一次软件验签。轮换流程以先合后拆的方式保证验证集在迁移期间始终覆盖新旧密钥。部署时请务必遵守CN/Global 资源严格分离、PIN 只走秘密通道、tmpfiles 先于 Compose 安装、以及每次晋升后先做一次真实签发验证再开放流量。关联资源索引适配器源码lib.rs、config.rs、protocol.rs、server.rs、pkcs11.rs、secure_file.rs、main.rs集成测试softhsm.rs部署资产compose.yaml、Dockerfile、config.example.json、softhsm2.conf、openpencil-locator-hsm.conflocator 侧对接hsm.rs、production.rs、compose.yaml、compose.hsm.yaml、compose.production.global.yaml、compose.production.cn.yaml协议与公钥解析locator.rs、pinned_locator_keys.rs赞分享【免费下载链接】openpencilThe worlds first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址https://gitcode.com/gh_mirrors/op/openpencil点击查看免费下载相关推荐Windows 激活 4 种方法一步到位Windows 激活 4 种方法一步到位 MASMicrosoft Activation Scripts是开源的 Windows 与 Office 激活工具操作系统5类抖音内容一次抓完无水印批量下载工具douyin-downloader使用说明5类抖音内容一次抓完无水印批量下载工具douyin downloader使用说明 douyin downloader 是一款免费开源的抖音下载工具覆盖无水印网页爬虫CLImicroduck 发布管线 CI 配置指南双密钥签名、staging→stable 提升与密钥轮换实战microduck 发布管线 CI 配置指南双密钥签名、staging→stable 提升与密钥轮换实战 导读 本文基于 microduck 仓库的 CI 一机器人嵌入式具身智能智能硬件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
【免费下载链接】openpencilThe worlds first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址https://gitcode.com/gh_mirrors/op/openpencil点击查看免费下载本篇技术指南围绕 OpenPencil 协作中继collab relay体系中一个关键的安全组件展开为 relay locator 提供 Ed25519 签名的OPLSOpenPencil Locator SigningUnix-socket 适配器op-collab-relay-locator-hsm。该组件以独立的非 root 容器形态运行通过 Unix 域套接字与 locator 进程通信将私钥与 PIN 严格隔离在无网络命名空间内。读完本文你将掌握该适配器的威胁模型与协议细节、密钥画像active next 双密钥、宿主机准备步骤、初始化与签发provision流程、生产启动与健康检查、AB → BC 的无缝密钥轮换以及基于真实 SoftHSM 的集成验证方法。一、设计定位为什么 locator 的私钥要单独隔离relay locator 负责签发出行凭证relay locator其签名的权威性依赖于一把专用的 Ed25519 私钥。如果这把私钥直接放在 locator 进程内一旦 locator 被攻破私钥随即泄露。OpenPencil 的做法是将私钥从 locator 中剥离交给一个独立运行的签名适配器容器。从 lib.rs 的 crate 级文档可以看到其安全模型的四条支柱调用方身份只信任 Unix peer credentials通过SO_PEERCREDLinux/getpeereidBSD获取对端 UID/GID 进行鉴权绝不信任请求载荷中自述的身份配置与 PIN 文件严格校验读取前必须验证 owner、mode、link count并以O_NOFOLLOW打开防止被替换的符号链接重定向读取监听套接字、flock 锁文件、心跳文件均以显式 mode 创建并在服务任何请求前按 uid/gid/mode 预期重新校验连配置 schema 都是 POSIX 形态的配置里携带预期的客户端 uid/gid 与受sun_path限制的套接字路径。整个 crate 以cfg(unix)门控——在 Windows 上编译这些所有权与 peer 身份检查要么意味着悄悄关闭它们、要么需要发明未经审计的 ACL 替代品因此二进制在非 Unix 平台会打印UNSUPPORTED_PLATFORM错误并退出而不是提供一个看起来还能工作的弱化版本。部署上的隔离则由 compose.yaml 落实network_mode: none无网络命名空间、read_only: true、cap_drop: ALL、no-new-privileges: true、pids_limit: 64、mem_limit: 128m。只有这个容器能挂载 SoftHSM token 目录和 user PINlocator 容器对signer.sock只读既读不到 token 存储也读不到 PIN 和私钥。二、OPLS v1 协议单连接单请求339 字节定长帧适配器与 locator 之间运行一个极简的私有协议OPLSOpenPencil Locator Signingv1定义在 protocol.rspub const OPLS_VERSION: u8 1; pub const REQUEST_BYTES: usize 4 1 1 1 64 LOCATOR_CANONICAL_SIGNING_BYTES; // 411164268 339 pub const RESPONSE_BYTES: usize 4 1 1 64; // 70请求帧339 字节OPLS魔数4 字节→ 协议版本1 字节恒为 1→ 操作码1 字节SIGN_OPERATION 1→ key id 长度1 字节→ 64 字节定长 key id 槽位右侧零填充→ 268 字节 canonical 签名输入。响应帧70 字节OPLR魔数4 字节→ 版本1 字节→ 状态码1 字节0 OK1 REJECTED→ 64 字节 Ed25519 签名。其中 268 字节的签名输入正是 relay 协议中 locator 的 canonical 签名字节见 locator.rs 的LOCATOR_CANONICAL_SIGNING_BYTES: usize 268因此适配器不改变既有 268 字节签名输入的形态——locator 端照常构造 canonical 字节只是把签名动作委托出去。服务端在签名前会做双重校验key id 校验decode_request长度非零且不超过MAX_LOCATOR_KEY_ID_BYTES64槽位剩余部分必须为零填充字符需落在可打印 ASCII0x21..0x7e区间并且必须精确等于配置的active_kidlocator 域校验validate_locator_domaincanonical 字节的第 0 字节必须是RELAY_PROTOCOL_VERSION1第 1 字节必须是本区域 wire 值cn 1global 2route id、generation、owner static 字段不能全零expected discovery id 与 key id 需满足定长槽位的零填充 ASCII 规则not_before非零、expires not_before且配对窗口不超过MAX_PAIRING_LIFETIME_SECS3600 秒即 1 小时。连接语义server.rs每个连接只接受恰好一个 339 字节请求随后再读 1 字节并期望 EOF——若有任何尾部字节直接回复REJECTED。读写均受request_timeout_ms配置项默认 2000ms超时保护。所有校验失败统一走SignerError::Rejected对外只回OPLR拒绝帧不暴露内部原因。三、密钥画像active next 双密钥与非导出约束适配器的配置里恰好有两把公钥条目active当前生效与 next轮换预备。active_kid必须精确标识其中一把见 config.rs 的校验active_kid must identify exactly one configured key。3.1 配置项与约束配置文件 schema 定义在 config.rsvalidate()强制的边界包括字段含义校验规则源码依据version配置版本必须等于 1region区域cn或global对应 wire 值 1 / 2socket_path监听套接字路径绝对路径、无..穿越、不超过 100 字节Unix socket 限制expected_client_uid/gid期望的 locator 身份必须非 rootpkcs11_module_pathSoftHSM 模块路径绝对、有界、无父目录穿越token_labeltoken 标签1–32 字节安全 ASCIIpin_fileuser PIN 文件路径绝对、有界、无父目录穿越active_kid当前生效 key id1–64 字节安全 ASCII且必须恰好匹配keys中一个条目keys密钥对列表必须恰好两条active nextkid 与 object_id 全局唯一request_timeout_ms单请求超时100–5000默认 2000安全 ASCII指is_safe_asciiconfig.rs仅允许 ASCII 字母、数字以及-、_、.。object_id_hex必须是小写十六进制、1–32 字节长度。若历史环境里还沿用包含其他标点的可打印 wire id必须在使用本适配器前完成迁移。仓库附带的 config.example.json 展示了完整示例{ version: 1, region: global, socket_path: /run/openpencil-hsm/signer.sock, expected_client_uid: 65532, expected_client_gid: 65532, pkcs11_module_path: /usr/lib/softhsm/libsofthsm2.so, token_label: openpencil-locator-global, pin_file: /run/secrets/locator-hsm-pin, active_kid: replace-with-active-public-kid, keys: [ { kid: replace-with-active-public-kid, object_id_hex: 7101 }, { kid: replace-with-next-public-kid, object_id_hex: 7102 } ], request_timeout_ms: 2000 }3.2 启动时的属性强制校验KeyStore::open在启动时对两把密钥逐一执行load_pairpkcs11.rs要求每个 object id 与 label 恰好标识一对隔离的公私钥对象并校验属性类型CKK_EC_EDWARDS、Ed25519 参数SoftHSM 使用 PKCS#11 定义的PrintableString形式edwards25519、KeyGenMechanism CKK_EC_EDWARDS_KEY_PAIR_GEN、Local true密钥在 token 本地生成私钥CKA_SENSITIVE true、CKA_EXTRACTABLE false、CKA_ALWAYS_SENSITIVE true、CKA_NEVER_EXTRACTABLE true用途私钥仅CKA_SIGN true、公钥仅CKA_VERIFY trueCKA_DERIVE false持久化CKA_TOKEN true、label/object id 精确匹配且不存在重复的配对对象。3.3 公钥导出两种下游格式initialize与provision都不导出私钥字节。public命令输出PublicKeySet{version:1,keys:[{kid:...,public_key_ed25519:...}]}其中public_key_ed25519是 32 字节公钥的 base64url 无填充编码pkcs11.rs。这份格式正是 relay 侧 key-file 解析器接受的格式pinned_locator_keys.rsversion: 1kidpublic_key_ed25519单文件上限 64KB、最多 64 把。而 signed desktop bootstrap 使用的 JWKS 中同一个 base64url 公钥值放在x字段下见 collab_jwks.rs 中kty:OKP,crv:Ed25519,alg:Ed25519,use:sig,key_ops:[verify],kid:...,x:URL_SAFE_NO_PAD.encode(public_key)的构造。四、宿主机准备目录、PIN、tmpfiles 与 Compose 输入4.1 数字身份约定仓库内联镜像使用的固定身份为locator65532:65532signer65533:65532共享 gid。CN 与 Global 两个区域必须使用独立的目录、token 标签、key id 与 object id具体的公网主机与生成的 key id 属于私有部署清单不应进入本仓库。4.2 外部宿主路径在每个区域 Linux 宿主机上准备命令来自 README.mdsudo install -d -o 65533 -g 65532 -m 0700 /secure/openpencil/locator-hsm/tokens sudo install -o 65533 -g 65532 -m 0400 /dev/null /secure/openpencil/locator-hsm/user-pin sudo install -o 65533 -g 65532 -m 0400 /dev/null /secure/openpencil/locator-hsm/so-pin sudo install -o root -g 65532 -m 0440 \ deploy/collab-relay-locator-hsm/config.example.json \ /secure/openpencil/locator-hsm/config.json sudo install -o root -g root -m 0644 \ deploy/collab-relay-locator-hsm/openpencil-locator-hsm.conf \ /etc/tmpfiles.d/openpencil-locator-hsm.conf sudo systemd-tmpfiles --create /etc/tmpfiles.d/openpencil-locator-hsm.conf要点示例中的 region、token label、active/next 公钥 id、唯一 object id 都必须替换为实际值两个 PIN 文件通过运营方秘密通道填充严禁把 PIN 写到命令行、Compose environment 或 shell 历史Docker 文件型挂载会保留宿主所有权而忽略uid/mode声明所以必须确认宿主机上的数字权限符合预期仓库内联的 tmpfiles 规则d /run/openpencil/locator-hsm 0770 root 65532 -会在每次启动后重建易失的/run套接字目录属主root:65532、mode0770。必须在 Compose 之前安装绝不要让 Docker 以root:root0755自动创建缺失的 bind 源目录。4.3 Compose 输入变量export OPENPENCIL_COLLAB_HSM_CONFIG_HOST_FILE/secure/openpencil/locator-hsm/config.json export OPENPENCIL_COLLAB_HSM_PIN_HOST_FILE/secure/openpencil/locator-hsm/user-pin export OPENPENCIL_COLLAB_HSM_TOKEN_HOST_DIR/secure/openpencil/locator-hsm/tokens export OPENPENCIL_COLLAB_HSM_SOCKET_HOST_DIR/run/openpencil/locator-hsm这些变量在 compose.yaml 中通过${VAR:?set absolute ...}强制必填分别以只读 bind 挂载到容器内/run/openpencil-config/locator-hsm.json、/run/secrets/locator-hsm-pin以及直接挂载 token 目录可写与/run/openpencil-hsm套接字目录。五、初始化 token 与逐把签发密钥签名适配器二进制支持五个子命令解析逻辑见 main.rsserve、check、public、provision --kid KID、initialize --so-pin-file PATH均需--config PATH。5.1 构建镜像并初始化空 tokenSO PIN 是一次性额外挂载不属于运行态服务的一部分docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ build locator-hsm docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm \ -v /secure/openpencil/locator-hsm/so-pin:/run/secrets/locator-hsm-so-pin:ro \ locator-hsm initialize --config /run/openpencil-config/locator-hsm.json \ --so-pin-file /run/secrets/locator-hsm-so-pininitializepkcs11.rs要求存储中恰好有一个未初始化 slot、其余 slot 已初始化数量为 0并且拒绝覆盖已存在的同名 token label随后以 SO PIN 初始化 token、以 SO 会话登录并设置 user PIN。5.2 逐把 provision两把配置好的 key id 必须一次一把地签发。这样部分失败是显式的且绝不在静默中复用或替换既有对象docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm provision \ --config /run/openpencil-config/locator-hsm.json --kid replace-with-active-public-kid docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm provision \ --config /run/openpencil-config/locator-hsm.json --kid replace-with-next-public-kidprovisionpkcs11.rs先用require_id_and_label_absent确认 object id 与 label 均不存在防止覆盖再以CKK_EC_EDWARDS_KEY_PAIR_GEN机制生成密钥对随后用该私钥签名一把 locator 形态的 canary 并软件验签通过后才返回公钥记录。集成测试 softhsm.rs 还验证了对已签发的 key 再次 provision 必须报错。5.3 导出公钥候选文件并分发docker compose -f deploy/collab-relay-locator-hsm/compose.yaml \ run --rm locator-hsm public \ --config /run/openpencil-config/locator-hsm.json /secure/public/locator-keys.candidate.json校验该候选文件后把同一组 activenext分发给 relay 与 signed desktop bootstrap再开始签发流量。SO PIN 在把恢复副本放入运营方控制的秘密系统后应从日常操作中移除文件与挂载一并移除。六、生产启动、就绪检查与健康探针只有当公开策略文件collab-policy与公钥文件都就绪后才把 signer 与 locator 一起启动export OPENPENCIL_COLLAB_POLICY_HOST_FILE/secure/public/collab-policy.json export OPENPENCIL_COLLAB_LOCATOR_HSM_KEY_IDreplace-with-active-public-kid export OPENPENCIL_COLLAB_LOCATOR_HSM_PEER_UID65533 export OPENPENCIL_COLLAB_LOCATOR_HSM_PEER_GID65532 docker compose \ -f deploy/collab-relay-locator-hsm/compose.yaml \ -f deploy/collab-relay-locator/compose.yaml \ -f deploy/collab-relay-locator/compose.production.global.yaml \ -f deploy/collab-relay-locator/compose.hsm.yaml \ up --build -d上面是 Global 区域命令CN 区域只需把区域 overlay 换成compose.production.cn.yaml。这些 overlay硬编码了匹配的 home region 与宿主 bind没有可覆盖的 host-bind 变量。6.1 就绪语义双重校验 canaryserve启动前与check命令都会KeyStore::open加载两对密钥并逐一执行readiness_canary——用每把私钥对 locator 形态的 canary 做 HSM 签名并立即软件验签canary 构造见 protocol.rsprobe_socket再校验已绑定的套接字与心跳新鲜度。容器健康检查由 Dockerfile 定义每 30s 执行一次check同时要求 Unix 套接字存在、主服务循环写出的心跳文件signer.ready在 10 秒内更新过server.rs。locator 侧通过 compose.hsm.yaml 的depends_on: locator-hsm: condition: service_healthy等待 signer 健康后才启动。6.2 套接字与文件的安全加固监听套接字创建后强制 mode0660绑定前逐层校验父目录非符号链接、属主/权限安全并用flock独占锁文件signer.lockmode0600防止双实例server.rs退出时通过SocketGuard记录 device/inode仅在套接字身份未变时才清理残留每个连接先以SO_PEERCREDLinuxserver.rs校验对端 uid/gid 必须等于配置的expected_client_uid/gid即 locator65532:65532不匹配直接拒绝配置与 PIN 的读取secure_file.rs配置必须是单链接常规文件、属主为 root 或 signer uid、group/other 不可写mode 0o022 0、大小上限 16KBPIN 文件必须是 signer uid 属主、mode 严格0400、8–128 字节可打印 ASCII 且无结尾换行读入后用Zeroizing包裹以便退出时清零。七、密钥轮换AB → BC全程无空窗轮换采用先扩大验证集合、再收窄到新集合的策略从 A(active)B(next) 迁移到 BC先全量发布 AB确认 relay 与 signed desktop bootstrap 都已持有当前 AB 集合准备候选配置构造 B(active)C(next) 的候选SignerConfig将其挂载进一次性 signerprovision C导出 BC 候选公钥文件合并重叠验证集把当前与候选公钥文件合并为 ABC 重叠 bundle。relay 的 pinned verifier 最多接受 64 把密钥源码依据 pinned_locator_keys.rs 的MAX_PINNED_VERIFIER_KEYS: usize 64jq -s {version: 1, keys: ([.[].keys[]] | unique_by(.kid))} \ /secure/public/locator-keys.current.json \ /secure/public/locator-keys.candidate.json \ /secure/public/locator-keys.overlap.json原子切换向 relay 与 signed desktop bootstrap 分发 ABC原子安装 BC signer 配置重启 signer 与 locator保留 A 一段时间在最大 locator 生命周期与回滚窗口内继续把 A 保留在 verifier bundle 中之后才单独发布 BC。注意signer 的public命令只输出其配置中的成对密钥不做 verifier 历史合并本适配器故意没有密钥销毁命令退役是独立且需审计的 token 管理操作。每次启动或晋升时locator 的OPENPENCIL_COLLAB_LOCATOR_HSM_KEY_ID必须与 signer 配置的active_kid完全一致locator 侧解析见 production.rs比对逻辑见 hsm.rs。在开放流量前应执行一次带认证的 locator 签发并用新分发的公钥验证返回签名。八、验证与集成测试仓库的 Docker 测试目标在真实 SoftHSM 模块上运行集成测试docker build --target test \ -f deploy/collab-relay-locator-hsm/Dockerfile . docker build -f deploy/collab-relay-locator-hsm/Dockerfile .--target test阶段Dockerfile安装softhsm2并设置OPENPENCIL_SOFTHSM2_MODULE/usr/lib/softhsm/libsofthsm2.so运行cargo test --locked -p op-collab-relay-locator-hsm --test softhsm。该测试softhsm.rs使用临时 token 目录与临时softhsm2.conf完整演练initialize → 两把逐次 provision并断言重复 provision 失败→ open 后导出 2 把公钥 → 对 canary 签名并verify_strict软件验签 →篡改区域 wire 值后签名必须被拒绝。运行时镜像则以 Debian bookworm-slim 为基础创建openpencil-locator-hsm用户uid 65533、gid 65532安装softhsm2通过SOFTHSM2_CONF/etc/openpencil-softhsm2.conf指向仓库内联的 softhsm2.confdirectories.tokendir/var/lib/openpencil-softhsm/tokens/、objectstore.backendfile、log.levelERROR、slots.removablefalse最终以USER 65533:65532运行默认CMD [serve, ...]。九、小结安全边界一览本适配器的核心价值在于把私钥所在与私钥使用者拆到两个不同信任域locator 只见一个只读的 Unix 套接字它既看不到 token 目录、PIN也看不到私钥对象签名请求必须同时通过 peer credential 身份校验、key id 精确匹配、区域与窗口语义校验且每次 HSM 签名在返回前都要用 token 公钥做一次软件验签。轮换流程以先合后拆的方式保证验证集在迁移期间始终覆盖新旧密钥。部署时请务必遵守CN/Global 资源严格分离、PIN 只走秘密通道、tmpfiles 先于 Compose 安装、以及每次晋升后先做一次真实签发验证再开放流量。关联资源索引适配器源码lib.rs、config.rs、protocol.rs、server.rs、pkcs11.rs、secure_file.rs、main.rs集成测试softhsm.rs部署资产compose.yaml、Dockerfile、config.example.json、softhsm2.conf、openpencil-locator-hsm.conflocator 侧对接hsm.rs、production.rs、compose.yaml、compose.hsm.yaml、compose.production.global.yaml、compose.production.cn.yaml协议与公钥解析locator.rs、pinned_locator_keys.rs赞分享【免费下载链接】openpencilThe worlds first open-source AI-native vector design tool and the first to feature concurrent Agent Teams. Design-as-Code. Turn prompts into UI directly on the live canvas. A modern alternative to Pencil.项目地址https://gitcode.com/gh_mirrors/op/openpencil点击查看免费下载相关推荐Windows 激活 4 种方法一步到位Windows 激活 4 种方法一步到位 MASMicrosoft Activation Scripts是开源的 Windows 与 Office 激活工具操作系统5类抖音内容一次抓完无水印批量下载工具douyin-downloader使用说明5类抖音内容一次抓完无水印批量下载工具douyin downloader使用说明 douyin downloader 是一款免费开源的抖音下载工具覆盖无水印网页爬虫CLImicroduck 发布管线 CI 配置指南双密钥签名、staging→stable 提升与密钥轮换实战microduck 发布管线 CI 配置指南双密钥签名、staging→stable 提升与密钥轮换实战 导读 本文基于 microduck 仓库的 CI 一机器人嵌入式具身智能智能硬件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
