Serval DNA项目密钥环REST API详解

概述

Serval DNA项目是一个创新的去中心化网络解决方案，其核心功能之一是通过密钥环(Keyring)机制管理加密身份。本文将深入解析Serval DNA的密钥环REST API，帮助开发者理解和使用这一重要功能。

核心概念

1. Serval ID系统

Serval网络中的每个身份都由以下两种加密ID构成：

1. Serval ID(SID)

   • 256位公钥，基于Curve25519的crypto-box密钥空间
   • 用途：网络地址、MDP消息加密、Rhizome bundle标识等

2. Serval Signing ID

   • 256位公钥，基于Curve25519的crypto-sign密钥空间
   • 用途：路由消息防伪、MDP消息认证

2. 组合ID(Combined IDs)

自2016年7月起，Serval DNA采用了一种优化方案：

• 从Signing ID派生出SID，而非独立生成
• 优势：减少密钥生成数量，提高效率
• 技术基础：libsodium库提供的密钥空间转换功能

3. 辅助标识

• DID(Dialled Identity)：5-31位的电话号码格式字符串
• Name：1-63字节的用户友好名称
• Rhizome Secret：用于保护Bundle Secret的独立密钥

安全机制

1. PIN保护

• 可选设置的身份解锁密码
• 空PIN表示身份永久解锁
• 非空PIN的身份在密钥环文件中加密存储
• 重要特性：无后门机制，丢失PIN将永久锁定身份

2. 解锁机制

• 所有API请求可通过pin参数提供密码
• 解锁状态会被缓存，直到显式锁定
• 锁定操作需通过专门API调用

REST API详解

1. 身份列表查询

端点：GET /restful/keyring/identities.json

功能：获取所有已解锁身份列表

参数：

• pin：可选解锁密码

响应格式：JSON表格，包含sid、identity、did、name字段

2. 身份创建

端点：POST /restful/keyring/add

功能：创建新随机身份

参数：

• pin：可选密码
• did：可选电话号码
• name：可选名称

响应：201 Created + 身份详情JSON

3. 身份查询

端点：GET /restful/keyring/SID

功能：查询特定身份详情

参数：

• pin：可选解锁密码

响应：200 OK + 身份详情JSON 或 404 Not Found

4. 身份删除

端点：DELETE /restful/keyring/SID

功能：删除指定身份

参数：

• pin：可选解锁密码

响应：200 OK + 被删身份详情 或 404 Not Found

5. 身份更新

端点：PATCH /restful/keyring/SID

功能：修改身份属性

参数：

• pin：可选解锁密码
• did：设置/清除电话号码
• name：设置/清除名称

响应：200 OK 或 400/404错误

6. 身份锁定

端点：PUT /restful/keyring/SID/lock

功能：锁定指定身份

响应：200 OK + 被锁身份详情 或 404 Not Found

开发建议

1. 错误处理：注意处理400、404等常见错误码
2. 安全实践：
   • 敏感操作应始终使用PIN保护
   • 及时锁定不再使用的身份
3. 性能考虑：批量操作时注意API调用频率
4. 数据验证：客户端应验证DID和Name的格式要求

总结

Serval DNA的密钥环REST API提供了一套完整的安全身份管理方案，开发者可以利用这些接口实现：

• 安全的身份创建与管理
• 灵活的身份属性配置
• 细粒度的访问控制
• 与其他Serval网络服务的无缝集成

理解这些API的工作原理和最佳实践，将帮助开发者构建更安全、可靠的Serval网络应用。