首页
/ Guardian/CoverDrop 项目 REST API 规范详解

Guardian/CoverDrop 项目 REST API 规范详解

2025-06-10 12:58:25作者:丁柯新Fawn

项目概述

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 设计理念和使用方法,为系统集成和二次开发提供参考。

登录后查看全文
热门项目推荐

热门内容推荐

最新内容推荐

项目优选

收起
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
149
1.95 K
kernelkernel
deepin linux kernel
C
22
6
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
980
395
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
192
274
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
931
555
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
145
190
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
8
0
金融AI编程实战金融AI编程实战
为非计算机科班出身 (例如财经类高校金融学院) 同学量身定制,新手友好,让学生以亲身实践开源开发的方式,学会使用计算机自动化自己的科研/创新工作。案例以量化投资为主线,涉及 Bash、Python、SQL、BI、AI 等全技术栈,培养面向未来的数智化人才 (如数据工程师、数据分析师、数据科学家、数据决策者、量化投资人)。
Jupyter Notebook
75
66
openHiTLS-examplesopenHiTLS-examples
本仓将为广大高校开发者提供开源实践和创新开发平台,收集和展示openHiTLS示例代码及创新应用,欢迎大家投稿,让全世界看到您的精巧密码实现设计,也让更多人通过您的优秀成果,理解、喜爱上密码技术。
C
65
518
CangjieCommunityCangjieCommunity
为仓颉编程语言开发者打造活跃、开放、高质量的社区环境
Markdown
1.11 K
0