Merge pull request #30 from WeBankFinTech/develop

Merge develop to master

docs/zh_CN/docs/capacity-estimation.md

@@ -0,0 +1,149 @@
+# WeIdentity 存储容量预估
+
+WeIdentity 在区块链上存储的信息主要包括：
+1. WeIdentity Document（存储在 Event）。
+2. WeIdentity DID 的总表。
+3. WeIdentity Credential 在链上的存证（即Evidence）。
+4. 所有 CPT 的定义（以JSON格式存储）。
+5. Authority Issuer。
+6. Specific Issuer。
+
+一般情况下，需要注意上面的第1，2，3项的容量。
+
+WeIdentity 容量预估：
+
+```JAVA
+链上所占总空间 = WeIdentity DID 数量 * 52 Bytes * 10 +
+  Evidence 数量 * 220 Bytes * 10 +
+  CPT 数量 * 4560 Bytes * 10 +
+  Authority Issuer 数量 * 724 Bytes * 10 +
+  Specific Issuer 数量 * 372 Bytes * 10
+```
+
+```JAVA
+Event 所占总空间 = WeIdentity DID 数量 * 1464 Bytes * 3
+```
+
+例如，假设一条联盟链，总共创建`1000万个`WeID，并且将Credential的存证上链，每天 `20000 条`存证上链（这种情况下，容量评估可以只考虑上面列出的前三项）。则`两年`时间，部署 WeIdentity 的区块链节点，大概会占用的空间（仅做参考）：
+* 链上所占总空间 = 10000000 * 52 Bytes * 10 + 2 * 365 * 20000 * 220 Bytes * 10 = 35.6 GBytes
+* Event 所占总空间 = 10000000 * 1464 Bytes * 3 =  41.9 GBytes
+
+综上，单节点占用空间 35.6 + 41.9 = 77.5 GBytes
+
+## 1. WeIdentity Document，即每个 WeIdentity DID 的属性集合，存储在 Event。
+
+```JSON
+所有的 WeIdentity Document 所占 Event 空间 = WeIdentity DID 数量 * 1464 Bytes * 3
+```
+
+#### 解释：
+
+Event 的结构如下：
+```javascript
+event WeIdAttributeChanged(
+    address indexed identity ---> 20 Bytes
+    bytes32 key ---> 32 Bytes
+    bytes value ---> 不同的 Attribute，value所占空间不通。下面详细解释。
+    uint previousBlock ---> 8 Bytes
+    int updated ---> 8 Bytes
+);
+```
+
+这里假设，每个 WeIdentity Document 包含了下面的字段：
+* 1 个 Created 字段，保存在 1 个 Event 中。long型的 timestamp，转为 String，value 占 13 Bytes。单个 Event 结构占 81 Bytes。
+* 3 个 Public Key 字段，保存在 3 个 Event 中。保存形式是`"PublicKey/address"`，value 占64+1+20 = 85 Bytes。单个 Event 结构占 153 Bytes。(即没增加一个 Public Key，增加 153 Bytes)。
+* 3 个 Authentication 字段，保存在 3 个 Event 中。保存形式是`"PublicKey/address"`，value 占 64+1+20 = 85 Bytes。单个 Event 结构占 153 Bytes(即没增加一个 Authentication，增加 153 Bytes)。
+* 5 个 Service Endpoint 字段，保存在 5 个 Event 中。这里预估每个 value 占 30 Bytes。单个 Event 结构占 98 Bytes。
+
+即总共需要使用 12 个 Event 结构存储 WeIdentity Document 的所有属性。因此，单个 WeIdentity Document 所占 Event 存储空间为 81 + 3 * 153 + 3 * 153 + 5 * 93 = 1464 Bytes。
+
+
+## 2. WeIdentity DID 的总表所占容量预估
+
+WeIdentity DID 的总表，存储在链上，存储了所有公开的 WeIdentity DID 的 ID到 Document 的映射关系。
+
+```javascript
+WeIdentity DID 的总表在链上所占空间 = WeIdentity DID 数量 * 52 Bytes * 10
+```
+
+#### 解释：
+key 是 WeAddress，使用`address`存储，占 20 Bytes； WeAddress；Event 所在块位置使用`unit`存储，占 32 Bytes（256 bits）。单个 WeID 占用52 Bytes。
+
+
+## 3. WeIdentity Credential 的 Evidence 所占容量预估
+
+```
+所有 Evidence 在链上所占空间 = Evidence 数量 * 220 Bytes * 10
+```
+
+#### 解释：
+key 是 WeAddress，占 20 Bytes；单个 Evidence 在链上的数据结构如下，占200 Bytes：
+
+```javascript
+{
+bytes32[] dataHash, ---> 动态数组，目前使用 2 个 byte32，占 64 Bytes。
+address[] signer, ---> 动态数组，目前使用 1 个 byte32， 占 32 Bytes。
+bytes32 r, ---> 占 32 Bytes。
+bytes32 s, ---> 占 32 Bytes。
+uint8 v, ---> 占 8 Bytes。
+bytes32[] extra ---> 动态数组，目前使用 32 Bytes。
+}
+```
+
+## 4. 所有 CPT 的定义所占容量预估
+
+```javascript
+CPT 在链上所占空间 = CPT 数量 * 4560 Bytes * 10
+```
+
+#### 解释：
+key 是`uint`，占 32 Bytes；单个 CPT 在链上的存储结构如下，占用空间 4528 Bytes，如下所示：
+
+```javascript
+{
+uint cptId ---> 8 Bytes
+address cptPublisher ---> 32 Bytes
+int[8] cptIntArray ---> 64 Bytes
+bytes32[8] cptBytes32Array ---> 256 Bytes
+bytes32[128] cptJsonSchemaArray ---> 4096 Bytes
+uint8 cptV ---> 8 Bytes
+bytes32 cptR ---> 32 Bytes
+bytes32 cptS ---> 32 Bytes
+}
+```
+
+## 5. Authority Issuer 所占容量预估
+
+```javascript
+Authority Issuer 合约在链上所占空间 = Authority Issuer 数量 * 724 Bytes * 10
+```
+
+#### 解释：
+key 是 WeAddress，占 20 Bytes；单个Authority Issuer 在链上的存储结构，704 byte
+
+```javascript
+{
+address addr, ---> 32 Bytes
+bytes32[16] attribBytes32, ---> 512 Bytes
+int[16] attribInt, ---> 128 Bytes
+bytes accValue ---> 32 Bytes
+}
+```
+
+## 6. Specific Issuer 所占容量预估
+
+```javascript
+Specific Issuer 合约在链上所占空间 = Specific Issuer 数量 * 372 Bytes * 10
+```
+
+#### 解释：
+key 是 WeAddress，占 20 Bytes；单个 Specific Issuer 在链上存储结构，占 352 Bytes,结构如下：
+
+```javascript
+{
+bytes32 typeName; ---> 32 Bytes
+address[] fellow; ---> 32 Bytes
+mapping (address => bool) isFellow; ---> 32 Bytes
+bytes32[8] extra; ---> 256 Bytes
+}
+```

docs/zh_CN/docs/faq.md

@@ -147,3 +147,9 @@ Credential的重新生成则为重新发行一个Credential ID不相同的全新
 [Quantum_computing_attacks](https://en.wikipedia.org/wiki/Elliptic-curve_cryptography#Quantum_computing_attacks)
 
 ---
+
+- **在 FISCO-BCOS 上部署 WeIdentity，部署区块链节点的机器需要准备多大的硬盘？**
+
+详见 [WeIdentity 存储容量预估](./capacity-estimation.md)
+
+---

docs/zh_CN/docs/miscellaneous.md

@@ -0,0 +1,7 @@
+# 杂项
+
+* [部署 WeIdentity 服务的区块链节点存储空间预估](./capacity-estimation.md)
+
+* [weid-java-sdk 如何进行单元测试](./how-to-run-unit-test.md)
+
+* [安全建议](./security-suggestion.md)

docs/zh_CN/docs/security-suggestion.md

@@ -0,0 +1,47 @@
+# 安全建议
+
+## 1.网络安全：
+* 与合作方传输数据需要使用加密协议，并验证身份有效性，如通讯使用 HTTPS
+* 接口数据除了 HTTPS，接口内容尽量再次加密
+* 防中间人劫持，APP写死服务器的证书（可定期下发更换），APP 连接到服务器前，会检查是否证书对的上
+* 网络区域隔离： 如生产与开发、测试、办公隔离
+* 外网出口部署流量清洗、DDOS 防护等安全措施（可以使用云服务商或者运营服务厂商提供的服务）
+
+## 2.主机安全：
+* 主机防护：提供外网服户的 WEB 系统请求应经 WAF 过滤，降低恶意请求访问的风险；IDS 入侵检测
+* 主机防入侵检测，可使用云服务提供商的防入侵检测服务
+* Windows 机器部署杀毒软件
+* 接入业务风控(接入反欺诈/常用设备监控)
+* 不允许非标准操作系统及非标准软件，例如破解或者盗版软件
+* 禁止使用弱密码，建立弱密码扫描检测机制
+* 禁止开放高危端口和服务
+
+## 3.数据安全：
+* iOS 防双击 Home 键系统屏幕截图信息泄漏（加模糊或者新生成图片，防止 iOS 在 APP 切换界面能看到敏感信息）
+* 密码键盘，自行实现无序的密码键盘(恶意软件有可能会通过监控屏幕点击，监控系统键盘)
+* 密码输入需要 * 遮挡、后台一些重要数据脱敏后返回前台
+* 禁止在前台（Web 和 APP）和后台 server 日志和配置文件中，明文记录用户名，密码或者密钥，也不打印和保存客户敏感信息，防止信息的泄露。
+* SDK 里面的密码等敏感信息用完即销毁（APP 不缓存密码）
+* 敏感数据要做好加密存储，例如对 Credential 数据：加密保存，秘钥如何存（KeyCenter 保存）
+* 数据出生产控制，比如使用 Citrix
+* 能查看所有用户信息的管理台，做好相应的鉴权
+
+## 4.应用安全：
+* 登录态和其它业务独立，避免登录泄漏影响到其它业务
+* 敏感接口调用，建议接入 2FA 双因子验证或者 MFA，比如必须输入图形验证码，手机验证码，人脸识别等
+* 密码恢复，需要 2FA 或者 MFA
+* 互联网 APP 类、Web 类业务系统发布前应进行代码扫描和接口安全扫描及安全渗透性测试，相应测试结果及整改情况应提交系统上线检视会进行评估。 对外的接口需要做渗透测试。
+例如常见的厂家：[绿盟](http://www.nsfocus.com.cn/)；[漏洞盒子](https://www.vulbox.com/)。
+常见漏洞见：[OWASP_Top_Ten_Project](https://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project) 或者 [2017-owasp-top-10](http://www.owasp.org.cn/owasp-project/2017-owasp-top-10)
+* SDK 被嵌入执行的父应用判断，避免恶意应用嵌入
+* SDK 升级能力，保存在 APP 里面的证书需要定时更新
+* Android 接入腾讯乐固加固和腾讯金刚扫描（发现四大组件权限设置问题，如调用方权限；防止仿编译等。）
+参考：[腾讯乐固](http://wiki.open.qq.com/wiki/%E5%BA%94%E7%94%A8%E5%8A%A0%E5%9B%BA)
+* Android 监测到 root 设备提示用户不安全问用户是否继续执行
+* Android APP 防止二次打包（对比签名）。
+* iOS反调试代码，监测是否越狱
+
+## 5.其它
+* 安全编码规范：OWASP 安全编码规范:
+ [(English Version) OWASP_SCP_Quick_Reference_Guide](https://www.owasp.org/index.php/File:OWASP_SCP_Quick_Reference_Guide_v2.pdf) ;
+[(中文) OWASP_SCP_Quick_Reference_Guide](https://www.owasp.org/index.php/File:OWASP_SCP_Quick_Reference_Guide_\(Chinese\).pdf)

docs/zh_CN/docs/weid-timeline.md

@@ -0,0 +1,3 @@
+#
+
+![weid-timeline](images/weid-timeline.png)

docs/zh_CN/index.rst

@@ -22,5 +22,6 @@ WeIdentity文档
    docs/use-cases.rst
    docs/weidentity-spec.rst
    docs/faq.md
+   docs/miscellaneous.md
    docs/weidentity-rest.rst
    WeIdentity JAVA SDK 文档 <https://weidentity.readthedocs.io/projects/javasdk/zh_CN/latest/>