Skip to content

Latest commit

 

History

History
245 lines (215 loc) · 10.5 KB

模块设计文档.md

File metadata and controls

245 lines (215 loc) · 10.5 KB
Raw

点对点加密邮件模块设计文档

功能设计

模块实现的核心业务是两个地址直接进行文本消息的收发，将会把加密后的消息内容存储在链上和节点文件系统中。

核心功能点

  1. 为地址绑定全链唯一的邮箱地址。
  2. 给指定邮箱地址发送邮件。
  3. 接收邮件。
  4. 查看邮件详情。

次要功能点

  1. 查看收件箱和发件箱邮件列表。
  2. 绑定邮箱地址和发送邮件额外支付手续费

概要设计

绑定邮箱地址

创建申请邮箱地址交易类型（type_200)，业务数据（txData）包括申请地址、邮箱地址、地址公钥。验证交易时，需要验证邮箱地址是否已经被占用、申请地址是否已经绑定或邮箱、申请地址的账户余额是否足够支付申请手续费和交易手续费。当交易确认后，节点将把申请地址、邮箱地址、公钥3个数据建立联系并存储到文件系统中。

绑定邮箱地址功能的作用有两点

  1. 提供比账户地址更利于人类记忆和书写的格式。
  2. 通过账户发生交易获取到账户地址的公钥，在发送邮件时需要通过公钥对邮件内容进行非对称加密。

发送邮件

创建发送邮件交易类型（type_201),业务数据（txData)中存储发件人地址（非邮箱地址）、收件人地址（非邮箱地址）、发送时间、加密后的邮件标题、加密后的邮件内容、发件人阅读权限key，收件人阅读权限key。

组装交易

发送邮件的参数为发件人账户地址、账户密码、收件人邮箱地址、邮件标题、邮件内容。处理步骤如下：

  1. 通过收件人邮箱地址查询到收件人邮箱信息，获取到收件人账户地址、收件人账户公钥。
  2. 生成一对加密邮件的钥匙对（KEY)，通过公钥对邮件标题和邮件内容进行加密处理；通过收件人和发件人的公钥对KEY的私钥进行加密分别获得收件人阅读权限key和发件人阅读权限key。在查看邮件内容时首先通过自己的私钥解密对应的阅读权限key，然后用阅读权限key解密邮件标题和邮件内容。从而达到数据公开存储，但只能发件人和收件人才能查看内容的目的。

验证交易

  1. 验证发件人账户地址绑定邮箱地址。
  2. 验证收件邮箱地址是否有效。
  3. 验证是否转入指定数量资产到手续费账户。

保存邮件数据

因为是演示模块，避免不必要的复杂度，存储没有采用数据库存储，而使用文件系统存储。邮件存储主要存储邮件与收件人、发件人的关系，以及邮件内容。

  1. 创建sender和recipient两个文件夹存储账户地址与邮件所在交易hash的关系。文件夹中以地址为文件名创建文件，文件中每一行存储一条此账户地址有关的邮件交易hash。sender文件夹存储发件人与邮件交易hash的关系，recipient文件夹存储收件人与邮件交易hash的关系。
  2. 创建mail-data文件夹存储邮件，使用邮件交易hash值作为文件名创建存储文件，文件内容为邮件内容byte数组的16进制字符串。

读取邮件

解密邮件信息

邮件内容是加密后存储，读取时需要进行解密操作。解密失败抛出异常。解密流程如下：

  1. 通过邮件hash值获取邮件内容。
  2. 反序列化邮件内容，首先将16进制转换成byte数组，然后按照以下顺序规则解析byte数组
  1. 变长类型存储收件人账户地址
  2. 变成类型存储发件人账户地址
  3. 变长类型存储收件人阅读权限key
  4. 变长类型存储发件人阅读权限key
  5. 变长类型存储邮件标题
  6. 变长类型存储邮件内容
  7. 4个byte存储64位int时间戳（1970年1月1日到当前毫秒数）
  1. 通过地址比较判断当前账户是收件人还是发件人，通过私钥解密对应的阅读权限key。
  2. 通过解密后的阅读权限key解密邮件标题和邮件内容。

读取收件列表或发件列表

在sender和recipient文件夹下找到账户地址同名的文件，按行读取hash值，然后使用hash值通过解密邮件信息获取邮件详情，最后组装成列表。

收取手续费

通过验证绑定邮箱交易和发送邮件交易的CoinData里是否包含向指定的黑洞地址(手续费地址）转入指定数量资产来实现手续费收取。

详细设计

源代码包结构

.
└── io
    └── nuls
        ├── Config.java
        ├── Constant.java
        ├── MyModule.java
        ├── NulsModuleBootstrap.java
        ├── Utils.java
        ├── controller
        │   ├── CreateMailAddressController.java
        │   ├── GetMailController.java
        │   ├── SendMailController.java
        │   ├── core
        │   │   ├── BaseController.java
        │   │   ├── NulsResourceConfig.java
        │   │   ├── Result.java
        │   │   └── WebServerManager.java
        │   └── vo
        │       ├── CreateMailAddressReq.java
        │       ├── GetMailListReq.java
        │       ├── MailAddressData.java
        │       ├── MailContentData.java
        │       ├── SendMailReq.java
        │       └── ViewMailReq.java
        ├── rpc
        │   ├── AccountTools.java
        │   ├── CallRpc.java
        │   ├── LegderTools.java
        │   ├── TransactionTools.java
        │   └── vo
        │       ├── Account.java
        │       ├── AccountBalance.java
        │       └── TxRegisterDetail.java
        ├── service
        │   ├── MailAddressService.java
        │   ├── SendMailService.java
        │   └── dto
        │       ├── MailAddress.java
        │       └── MailContent.java
        └── txhander
            ├── MailAddressProcessor.java
            ├── SendMailProcessor.java
            ├── TransactionDispatcher.java
            └── TransactionProcessor.java

Config.java

配置文件，通过nuls-core包的配置文件系统将外部NULS2.0通用配置读取到类中，本模块中需要使用chainId(链id）、assetId（资产id）、dataPath(数据存储路径），这3个配置属于全局通用配置，直接读取即可。另外定义了mailAddressFee（绑定邮箱手续费）、sendMailFee（发送邮件手续费）两个业务配置项，需要在module.ncf中配置。

Constant.java

常量定义类，定义了绑定邮箱交易类型(200)、发送邮件交易类型（201）、手续费黑洞地址。

MyModule.java

模块启动类，申明当前模块依赖account(账户）、ledger（账本）、transaction(交易)3个模块。nuls-core-rpc程序包将自动与这3个模块建立websocket长连接。 完成模块初始化工作：

  1. 创建存储数据的文件夹。
  2. 向交易模块注册交易类型。
  3. 初始化Restful WebServer服务（用户操作接口使用http协议提供）。

controller包

controller包提供用户操作接口

CreateMailAddressController.java

绑定账户邮箱地址相关接口。

GetMailController.java

获取邮箱信息相关接口。

SendMailController.java

发送邮件相关接口

core和vo包

HTTP接口框架及接口协议相关。

rpc包

访问其他模块的RPC接口相关工具类。

service包

数据存储逻辑相关包。

MailAddressService.java

存储账户绑定的邮箱地址信息相关服务。

SendMailService.java

发送邮件及查询邮件信息相关服务。

dto包

定义数据存储对象

txhander包

交易回调函数包

TransactionDispatcher.java

定义回调函数的RPC接口，根据交易类型分发到具体的处理类。

MailAddressProcessor.java

定义处理绑定邮箱地址交易类型（type_200）的回调函数。

SendMailProcessor.java

定义处理发送邮件交易类型（type_201）的回调函数。

用户操作接口列表

用户操作接口使用http方式提供，Request和Response的Content type为application/json，端口为9999。

返回值通用协议

{
    "success": true,  //成功状态
    "data": null,     //返回的数据
    "msg": null       //失败的原因
}

绑定邮箱地址

访问路径：/mail/createMailAddress
请求方式: POST
参数列表
参数名 参数类型 说明
address string 申请账户地址
mailAddress string 申请绑定的邮箱地址
password string 账户密码
返回值 string

交易的txHash值。

查询指定账户地址绑定的邮箱地址

访问路径：/mail/getMailAddress/{address}
请求方式：GET
参数列表
参数名 参数类型 说明
address string 账户地址
返回值 string

邮箱地址

发送邮件

访问路径：/mail/sendMail
请求方式：POST
参数列表
参数名 参数类型 说明
mailAddress string 收件人邮箱地址
senderAddress string 发件人账户地址
password string 发件人账户密码
title string 邮件标题
content string 邮件内容
返回值 string

交易txHash

获取指定邮件详情

访问路径：/mail/viewMail
请求方式：POST
参数列表
参数名 参数类型 说明
address string 账户地址
password string 账户密码
hash string 邮件交易hash
返回值 object
参数名 说明
hash 邮件交易hash
senderMailAddress 发件人邮箱地址
receiverMailAddress 收件人邮箱地址
title 邮件标题
content 邮件内容
sender 发件人账户地址
date 发件日期

获取收件箱列表、获取发件箱列表

访问路径：/mail/getSendList、/mail/getReceiveList
请求方式：POST
参数列表
参数名 参数类型 说明
address string 账户地址
password string 账户密码
返回值 list
参数名 说明
hash 邮件交易hash
senderMailAddress 发件人邮箱地址
receiverMailAddress 收件人邮箱地址
title 邮件标题
content 邮件内容
sender 发件人账户地址
date 发件日期