Guardian/CoverDrop 项目 REST API 规范详解

项目概述

Guardian/CoverDrop 是一个安全通信系统，提供了一套完整的 REST API 接口，用于用户端和记者端的安全数据传输。该系统采用了严格的签名验证机制，确保所有数据交换的安全性。

API 设计原则

1. 严格的身份验证：所有修改资源的请求都必须使用签名表单
2. 清晰的权限划分：API 路径明确区分用户端(/user/)和记者端(/journalist/)
3. 版本控制：所有 API 都带有版本前缀(/v1/)
4. 错误处理标准化：统一的错误响应格式

签名表单机制

CoverDrop 系统要求所有修改数据库资源的请求都必须使用签名表单。这种机制确保了请求的完整性和真实性。

签名表单结构

{
  "body": "<base64编码的JSON对象>",
  "signature": "<hex编码的签名>",
  "timestamp": "<UTC时间戳>",
  "signing_pk": "<hex编码的签名公钥>"
}

验证流程

1. 服务器接收请求后，首先验证签名是否有效
2. 检查时间戳是否在有效期内
3. 验证签名公钥是否存在于密钥库中

常见错误响应

401 未授权

{
  "error": "signature verification failed"
}

404 未找到

{
  "error": "Signing key not found in key repository, it is either expired or never existed"
}

核心 API 端点详解

1. 系统状态检查

GET /v1/healthcheck

• 用途：基础健康检查
• 响应示例：

{
  "name": "api",
  "status": "ok",
  "commit": "45b61edc158ac02908c88c2ce944556cc9d8f4df",
  "branch": "main"
}

GET /v1/status

• 用途：获取系统运行状态
• 状态值：
  • AVAILABLE：系统正常运行
  • UNAVAILABLE：系统不可用
  • DEGRADED_PERFORMANCE：性能下降
  • SCHEDULED_MAINTENANCE：计划维护中
  • NO_INFORMATION：无系统状态信息

POST /v1/status

• 用途：更新系统状态
• 权限：需要管理员密钥对
• 请求示例：

{
  "body": "eyJzdGF0dXM...",
  "signature": "c41127d0f54...",
  "timestamp": "2024-01-04T17:19:01.820879Z",
  "signing_pk": "cb516f4dcf3f..."
}

2. 日志管理

POST /v1/logging

• 用途：动态调整日志级别
• 使用场景：调试时无需重启服务即可获取详细日志
• 权限：需要管理员密钥对

3. 公钥管理

GET /v1/public-keys

• 用途：获取所有公钥信息
• 返回内容：
  • 组织公钥
  • CoverNode 身份公钥
  • CoverNode 消息公钥
  • 所有记者公钥
  • 已注册记者信息
  • 默认记者ID(可选)

公钥操作端点

CoverDrop 系统提供了完整的公钥生命周期管理：

1. 记者公钥管理：

   • POST /v1/public-keys/journalists - 添加记者信息
   • DELETE /v1/public-keys/journalists/delete - 删除记者
   • PATCH /v1/public-keys/journalists/update-profile - 更新记者信息

2. CoverNode 公钥管理：

   • 配置公钥：POST /v1/public-keys/covernode/provisioning-public-key
   • 身份公钥：POST /v1/public-keys/covernode/identity-public-key
   • 消息公钥：POST /v1/public-keys/covernode/messaging-public-key

3. 记者端公钥管理：

   • 配置公钥：POST /v1/public-keys/journalist/provisioning-public-key
   • 身份公钥：POST /v1/public-keys/journalist/identity-public-key
   • 消息公钥：POST /v1/public-keys/journalist/messaging-public-key

4. 用户端接口

死信投递(Dead Drops)管理

• GET /v1/user/dead-drops - 获取死信投递记录
• POST /v1/user/dead-drops - 创建新的死信投递

5. 记者端接口

死信投递管理

• GET /v1/journalist/dead-drops - 记者获取死信投递记录
• POST /v1/journalist/dead-drops - 记者创建死信投递

安全最佳实践

1. 密钥轮换：系统会检测密钥轮换频率，防止过于频繁的更换
2. 请求时效性：所有请求都必须包含有效时间戳
3. 最小权限原则：不同操作需要不同级别的密钥对授权
4. 错误信息最小化：错误响应不泄露系统内部细节

常见问题解答

Q: 为什么我的签名请求被拒绝？ A: 可能原因：1) 签名验证失败 2) 时间戳过期 3) 签名公钥不存在或已过期

Q: 如何获取系统当前状态？ A: 使用 GET /v1/status 端点，无需认证即可获取系统状态信息

Q: 记者信息更新失败可能是什么原因？ A: 常见原因：1) 描述过长 2) 签名无效 3) 权限不足

通过本文的详细解读，开发者可以全面了解 Guardian/CoverDrop 项目的 REST API 设计理念和使用方法，为系统集成和二次开发提供参考。