开发者指南 · Zikaron
安全
本软件保管的是密钥与证据。本页说明它防范什么、依靠什么防范，以及维护者须遵守的规范。
报告漏洞
请通过仓库的私密漏洞报告提交，写明受影响的版本、复现步骤、观察到的结果以及你判断的影响。修复发布之前，请把细节限于私密渠道。
以下几类优先处理：签名绕过用户确认；核验对伪造的输入答「全部通过」；读出锁定状态下的本机数据或密钥；两份合规实现对同一输入给出相异的结论。
威胁模型
| 对手 | 防护 |
|---|---|
| 趁你离开时坐到机器前的人 | 口令门；输错五次锁定；闲置自动锁定；锁定时从内存清除主钥。 |
| 取得磁盘或备份文件的人 | 账本、设置、队列、身份登记与收到的授权都加密存放，密钥库另以口令加密；开锁前要读的机器设置与给别人读的导出件是明文。抵御离线穷举的，是口令与备份密码本身的强度，以及每次尝试都要跑的 scrypt（N=262144、r=8、p=1）。 |
| 伪造记录交给你的人 | 签名、账本链条与链上记录相互印证，核验逐项给出结论。 |
| 事后补造证据的人 | 上链给出时间上限；连续的账本占满了每一个位置。 |
| 说谎的节点 | 多个节点的读数相互对照；单一来源时明确标注。 |
| 诱导你签名的网页或应用 | 身份密钥只在 Zikaron 中使用；应用只签四个域里的两个：zikaron/1 与 zikaron/1-adoption。 |
以下情形在防护范围之外：已解锁机器上运行的恶意软件、内存读取、操作系统或硬件层面的攻破。对此，软件如实声明自身的边界。
密钥规范
- 签名确定
- 采用 RFC 6979 确定性随机数与低 s 值。同一把密钥对同一份字节，在任何合规工具上都签出同一个签名。
- 四个域相互独立
- 域的字面量写在被签消息中，一个域下的签名只在该域内有效。新增域时，选用与现有字面量全然相异的字面量。
- 只签自己组装的字节
- 应用只对自己组装、且用户已在确认卡上看过的内容签名；签名入口仅对此类内容开放。
- 密钥在内存中短暂停留
- 用后即清除。日志与错误信息中只写地址。
- 密码学调用集中一处
- 椭圆曲线、哈希、密钥派生的调用集中在指定模块，其他代码经由该模块使用。
读链规范
- 失败即答案缺席
- 节点连接失败、读数相异、扫描中断时，结论记为缺席，界面照此显示。网络故障与伪造记录，须让用户一眼分清。
- 绿灯只来自完整的检查
- 交易进入区块只算「确认中」；账本检查的报告读到它，才点亮绿灯。
- 回执成功才出队
- 条目在回执确认成功后离开队列；发送失败、等待超时的条目留在队列中。删除尚未发出的存证时，它也随之出队。
- 重发前先查
- 已上链的条目挡在队列之外。重启后继续等待原交易的回执。
- 逐次核对证书
- 每次连接都核对
https节点的证书链与主机名。TLS 用 rustls，根证书随应用内置，与系统的证书库分开。 - 输入设上限
- 每次读链 30 秒为限，应答至多 64 MiB。从发布地址取记录包只走
https，每个文件 20 秒、32 MiB，一个包至多 64 MiB，同源跳转至多 3 次。
隐私
- 应用的网络请求只有这几个去处：用户配置的节点、用户填写的发布地址、核验时用户给出的 https 地址，以及收到的授权文件里带着的发布地址（定期复核时也会去取）。除此之外，应用零更新检查、零遥测。
- 公共节点能看到查询的地址与合约，文档与界面如实告知。
- 条目中的文字随账本流出（记录包、授权文件、镜像），永久可读；文档如实告知。
- 短小、易猜的内容，其指纹能承受的穷举有限，文档提醒用户加入随机内容。
- 签入时的文件名与路径留在本机，与账本分开存放；记录名称写进条目，随条目公开。
依赖与供应链
Cargo.lock随仓库提交，发布构建使用--locked。- 依赖保持精简，核与存储尽量只用标准库。
- 升级密码学相关依赖时单独提交合并请求，附变更说明，并重跑全部一致性比对。
- 新增依赖须说明用途、维护状况与许可。
- 内嵌字体与其许可文本一并发布。
文件写入规范
- 先写临时文件并同步落盘，再重命名到位。
- 已有文件一律保留：备份、记录包、授权文件遇到同名时自动编号另存，并告知存放位置；密钥文件与命令行遇到同名即停止。
- 写完读回核对，密钥文件与备份尤其如此：读回相符才向用户报告成功。
- 恢复备份、更换主身份这类改动整步完成：要么全部生效，要么保持原状。批量签名在第一处失败停下，已签的保留。
- 主钥已失、永久封存的旧数据，字节原样移入
set-aside目录。 - 密钥文件权限设为 0600。
失败必须可见
每次操作落空，界面都给出明确提示。这类软件中代价最高的缺陷，是被用户当作成功的失败：一份以为已经上链的证据，到要用时才发现缺失。评审合并请求时，对每个新操作都问一句：它失败时，用户看到什么？