Merge remote-tracking branch 'upstream/main' into zeroize

README.md

@@ -2,17 +2,17 @@
 
 ## Overview
 
-RustyVault is a modern secret management system, written in Rust. RustyVault provides various features which support many scenarios including secure sotrage, cloud identity management, secret management, Kubernetes integration, PKI infrastructure, cryptographic computing, traditional key management, etc.
+RustyVault is a modern secret management system, written in Rust. RustyVault provides various features which support many scenarios including secure storage, cloud identity management, secret management, Kubernetes integration, PKI infrastructure, cryptographic computing, traditional key management, etc.
 
-RustyVault can be deployed in either cloud or physical environments. Depending on different requirements, RustyVault may run as standalone application with a set of RESTful APIs provided, and it can also be used as crate thus you can easily integrate it into your own Rust application.
+RustyVault can be deployed in either cloud or physical environments. Depending on different requirements, RustyVault may run as standalone application with a set of RESTful APIs provided, and it can also be used as a crate thus you can easily integrate it into your own Rust application.
 
 The core cryptographic module which provides cryptography functionality to RustVault can be configurable, for instance it could be [OpenSSL](https://github.com/openssl/openssl) or [Tongsuo](https://github.com/Tongsuo-Project/Tongsuo) project depending on the actual scenarios.
 
-The RustyVault is a subproject of [Tongsuo Project](https://github.com/Tongsuo-Project).
+One of the goals of RustyVault is to replace Hashicorp Vault seamlessly if you are seeking for an OSI-approved open-source license and enterprise level features.
 
 ## Feature
 
-Part of the features provided by Rustyvault are as follows:
+Part of the features provided by RustyVault are as follows:
 
 * Working Mode
   * standalone process w/HTTP APIs
@@ -58,4 +58,4 @@ Part of the features provided by Rustyvault are as follows:
 
 ## Design
 
-Read the [design](.\/design.md) document. This currently is in Chinese only.
+Read the [design](./design.md) document.

design-cn.md

@@ -0,0 +1,20 @@
+# RustyVault Design
+
+根据：[RustyVault需求文档](.\/req.md)中的整体需求点，进行功能细化。本文档对RustyVault的整体架构进行描述。
+
+# 结构图
+
+<img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/RustyVault.png" width=50% height=50% />
+
+说明如下：
+
+1. 虚线框中为RustyVault，其整体上分为三大部分：RustyVault Core, RustyVault Modules和RustyVault Surface.
+  * RustVault Core，此组件是RustyVault的核心组件，由多个Manager组成，不同的Manager分管不同功能。例如Module Manager负责对RustyVault的各个功能模块进行管理，提供模块的热插拔等机制；Crypto Manager则对接底层密码库（铜锁），通过rust-tongsuo的Rust binding来调用铜锁的C API实现各种密码学功能等；
+  * RustVault Modules，此部分由多个Module组成，是RustyVault的实际执行各种功能的环节，即RustyVault的实际功能代码都位于此。例如，PKI Module提供了完整的PKI能力，如扮演CA进行X.509证书的签发、吊销等管理工作；Crypto Module则依赖于RustyVault Core中的Crypto Manager对底层密码学原语进行调用，以实现对外提供诸如加密解密、签名验签等功能；
+  * RustyVault Surface，此组件是直接和最终用户打交道的部分，对外提供HTTPS接入能力，并对API请求进行解析后，转发给某个实际功能的Module上，由该Module进行处理后，返回处理结果给用户。此外，此组件还负责整体的配置解析等工作。
+
+2. RustyVault需要依赖于底层的密码学算法库（也可称之为软件密码模块），由底层密码库提供全部的密码学相关功能。RustyVault默认的底层密码库是铜锁。
+
+3. 密码硬件，如加密机、加密卡等，的使用对RustyVault是透明的，该过程由铜锁屏蔽，因此RustyVault对于硬件的差异和对接是无感的。
+
+4. RustyVault中的敏感安全参数（如各种密钥、随机数、认证信息等）中存在持久化存储需求的，可以在本地加密存储，或者连接外部存储（如etcd）。连接外部存储对于创建RustyVault集群是必须的。存储方面的管理由RustyVault Core中的Storage Manager负责，RustyVault的其他组件也无需感知不同存储方式之间的使用差异。

design.md

@@ -1,20 +1,20 @@
 # RustyVault Design
 
-根据：[RustyVault需求文档](.\/req.md)中的整体需求点，进行功能细化。本文档对RustyVault的整体架构进行描述。
+As per: [RustyVault Requirements Document](./req.md). In this document we describe the architecture of RustyVault.
 
-# 结构图
+# Architecture Diagram
 
 <img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/RustyVault.png" width=50% height=50% />
 
-说明如下：
+Detailed description:
 
-1. 虚线框中为RustyVault，其整体上分为三大部分：RustyVault Core, RustyVault Modules和RustyVault Surface.
-  * RustVault Core，此组件是RustyVault的核心组件，由多个Manager组成，不同的Manager分管不同功能。例如Module Manager负责对RustyVault的各个功能模块进行管理，提供模块的热插拔等机制；Crypto Manager则对接底层密码库（铜锁），通过rust-tongsuo的Rust binding来调用铜锁的C API实现各种密码学功能等；
-  * RustVault Modules，此部分由多个Module组成，是RustyVault的实际执行各种功能的环节，即RustyVault的实际功能代码都位于此。例如，PKI Module提供了完整的PKI能力，如扮演CA进行X.509证书的签发、吊销等管理工作；Crypto Module则依赖于RustyVault Core中的Crypto Manager对底层密码学原语进行调用，以实现对外提供诸如加密解密、签名验签等功能；
-  * RustyVault Surface，此组件是直接和最终用户打交道的部分，对外提供HTTPS接入能力，并对API请求进行解析后，转发给某个实际功能的Module上，由该Module进行处理后，返回处理结果给用户。此外，此组件还负责整体的配置解析等工作。
+1. RustyVault contains three main components: RustyVault Core, RustyVault Modules and RustyVault Interface.
+  * RustVault Core, the core component of RustyVault, contains many 'manager's. Each manager is in charge of a specific mechanism or layer. For instance, the 'Module Manager' handles all module management stuffs in RustyVault, providing mechanisms as module loading/unloading; meanwhile the 'Crypto Manager' provides one abstract layer for the crypto modules to call the underlying cryptography library to do the real cryptographic jobs.
+  * RustVault Modules, which consists several modules, is where the real features of RustyVault take place. That is to say, most functionality code sits in RustyVault Modules. For instance, the PKI Module provides a whole CA functionality, such as issuing X.509 certificates; the Crypto Module then contains the code that invokes a specific cryptography library utilizing the abstrace layer provided by Crypto Manager in the RustyVault Core.
+  * RustyVault Interface, is the part that interacts with the end users. The RustyVault Interface provides a set of RESTful APIs via an HTTPS server. After the server receives the API requests, it then routes these requests to one corresponding backend RustyVault Modules. That module then addresses the request and finally responds to the caller.
 
-2. RustyVault需要依赖于底层的密码学算法库（也可称之为软件密码模块），由底层密码库提供全部的密码学相关功能。RustyVault默认的底层密码库是铜锁。
+2. RustyVault depends on cryptography libraries (or cryptographic modules) to have the functionality such as encryption, signing, TLS connections and etc. Depending on the configuration, the cryptography library may be various, including native Rust crypto crates (ring, Rustls...), OpenSSL (via rust-openssl), Tongsuo...
 
-3. 密码硬件，如加密机、加密卡等，的使用对RustyVault是透明的，该过程由铜锁屏蔽，因此RustyVault对于硬件的差异和对接是无感的。
+3. RustyVault is able to utilize many different cryptographic hardware, such as HSMs or cryptography cards. But RustyVault doesn't talk to these hardware equipments directly, instead the underlying cryptography library sits between them and makes it easier for RustyVault to reach the hardware ability.
 
-4. RustyVault中的敏感安全参数（如各种密钥、随机数、认证信息等）中存在持久化存储需求的，可以在本地加密存储，或者连接外部存储（如etcd）。连接外部存储对于创建RustyVault集群是必须的。存储方面的管理由RustyVault Core中的Storage Manager负责，RustyVault的其他组件也无需感知不同存储方式之间的使用差异。
+4. The sensitive data in RustyVault (such as secrets, credentials, password, keys...) can be stored in local storage or an external remote storage such as etcd. The external storage is necessary if RustyVault runs in cluster. Different storage method is managed by the Storage Manager in the RustyVault Core component. Thanks to this design, other modules of RustyVault don't need to deal with different types of storage.

req-cn.md

@@ -0,0 +1,67 @@
+# 动机
+
+HashiCorp Vault是云原生领域被广泛使用的Secret Management产品，也是CNCF的项目。在实际使用中，Vault存在一些不足，例如：
+
+1. 对中国商用密码算法合规性没有支持
+2. 存在一定的性能问题
+3. 对密码硬件的支持不佳
+4. 高级功能不开源
+5. ……
+
+且目前市面上除了Vault之外，也几乎没有比较靠谱的Key/Secret Management类的开源实现。基于此，我们计划启动一个新的开源项目来解决上述问题。
+
+这个新的项目需要覆盖传统密钥管理系统（KMS）的大部分功能，也可能需要兼顾云原生时代对身份、Secret等方面的管理。因此，该系统可能存在如下需求纲领：
+
+1. 支持国产密码学算法
+2. 性能
+3. 高可用
+4. 底层硬件利用
+5. 内存安全
+
+# 需求列表
+
+语言：Rust
+
+名字：RustyVault
+
+功能：
+
+* API
+  * RESTful
+     * 可考虑一定程度兼容Vault的API，降低迁移成本（待定）
+  * gRPC （低优先级）
+* 用户和认证
+  * 基于数字证书的用户身份认证
+  * 基于用户名和口令的用户身份认证
+  * 基本的访问控制规则
+  * 基于用户的密钥管理体系
+* 配置方式
+  * 配置文件
+  * 支持热重启
+* 公钥基础设施（PKI）CA能力
+  * X.509证书签发：RSA/ECC/SM2
+  * X.509证书吊销：OCSP, CRL
+* 密钥管理
+  * 对称密钥：生成/存储/轮转
+  * 非对称密钥：RSA/ECC/SM2
+* 传统密码学算法支持
+  * 对称加密算法：AES, SM4
+  * 公钥密码算法：
+      * 签名算法：RSA/ECDSA/EdDSA/SM2/环签名
+      * 加密算法：RSA/SM2
+  * 哈希算法：SHA1/SHA2/SM3
+  * 随机数生成：国密合规的随机数生成算法
+* 前沿密码学算法支持
+  * 半同态算法：Paillier, EC-ElGamal
+  * 零知识证明：Bulletproofs
+  * 后量子密码学算法（待定）
+* 硬件适配
+  * 通过指令集、加速卡等进行密码算法性能优化
+  * 通过加密卡、加密机等进行密钥保护和密钥管理
+* 集群和高可用
+  * 全主模式（多读多写）
+* 存储能力
+  * 本地加密存储
+  * etcd等中心化存储
+* 日志和监控
+  * 文件日志

req.md

@@ -1,67 +1,70 @@
-# 动机
+# Motivation
 
-HashiCorp Vault是云原生领域被广泛使用的Secret Management产品，也是CNCF的项目。在实际使用中，Vault存在一些不足，例如：
+HashiCorp Vault is the most widely used secret management product in cloud native realm. But in practice, it has some disadvantages:
 
-1. 对中国商用密码算法合规性没有支持
-2. 存在一定的性能问题
-3. 对密码硬件的支持不佳
-4. 高级功能不开源
-5. ……
+1. Open-source license is not OSI-approved any more;
+2. Lack of cryptography compliance ability except FIPS, including:
+  * cryptography algorithms
+  * cryptography validations in other countries and regions
+3. Inadequate cryptography performance especially in  critical scenarios;
+4. Many useful features are not open-sourced
+5. ...
 
-且目前市面上除了Vault之外，也几乎没有比较靠谱的Key/Secret Management类的开源实现。基于此，我们计划启动一个新的开源项目来解决上述问题。
+And compared to Hashicorp Vault, there is rare open source key/secret management project available in the market. Thus, we started a new open source project to address the issues.
 
-这个新的项目需要覆盖传统密钥管理系统（KMS）的大部分功能，也可能需要兼顾云原生时代对身份、Secret等方面的管理。因此，该系统可能存在如下需求纲领：
+The new project needs to fulfill most features the a traditional KMS has. It also needs to be a replacement for Hashicorp Vault, with the features that even are not included in the open source versions of Vault. As such, the new project should be:
 
-1. 支持国产密码学算法
-2. 性能
-3. 高可用
-4. 底层硬件利用
-5. 内存安全
+1. Written in Rust to achieve memory safe
+2. Fully compatible with Hashicorp Vault on APIs and data format
+3. Configurable underlying cryptographic module
+4. High performance on cryptography operations
+5. High availability
+6. Support for underlying cryptography hardware
+7. OSI-approved open-source license
 
-# 需求列表
+# Requirements List
 
-语言：Rust
+Language: Rust
 
-名字：RustyVault
+Project Name: RustyVault
 
-功能：
+Features:
 
 * API
   * RESTful
-     * 可考虑一定程度兼容Vault的API，降低迁移成本（待定）
-  * gRPC （低优先级）
-* 用户和认证
-  * 基于数字证书的用户身份认证
-  * 基于用户名和口令的用户身份认证
-  * 基本的访问控制规则
-  * 基于用户的密钥管理体系
-* 配置方式
-  * 配置文件
-  * 支持热重启
-* 公钥基础设施（PKI）CA能力
-  * X.509证书签发：RSA/ECC/SM2
-  * X.509证书吊销：OCSP, CRL
-* 密钥管理
-  * 对称密钥：生成/存储/轮转
-  * 非对称密钥：RSA/ECC/SM2
-* 传统密码学算法支持
-  * 对称加密算法：AES, SM4
-  * 公钥密码算法：
-      * 签名算法：RSA/ECDSA/EdDSA/SM2/环签名
-      * 加密算法：RSA/SM2
-  * 哈希算法：SHA1/SHA2/SM3
-  * 随机数生成：国密合规的随机数生成算法
-* 前沿密码学算法支持
-  * 半同态算法：Paillier, EC-ElGamal
-  * 零知识证明：Bulletproofs
-  * 后量子密码学算法（待定）
-* 硬件适配
-  * 通过指令集、加速卡等进行密码算法性能优化
-  * 通过加密卡、加密机等进行密钥保护和密钥管理
-* 集群和高可用
-  * 全主模式（多读多写）
-* 存储能力
-  * 本地加密存储
-  * etcd等中心化存储
-* 日志和监控
-  * 文件日志
+     * Compatible with Hashicorp Vault
+  * gRPC (low priority)
+* User and Authentication
+  * X.509 based authentication
+  * Password based authentication
+  * Basic ACL
+  * Role based secret management
+* Configuration
+  * Support configuration file
+  * Dynamic reload
+* PKI/CA
+  * X.509 issuing: RSA/ECC/SM2
+  * X.509 revocation: OCSP, CRL
+* Key Management
+  * Symmetric: generation/storage/rotation
+  * Public key type: RSA/ECC/SM2
+* Cryptography Algorithm
+  * Symmetric ciphers: AES, SM4
+  * Public key algorithms:
+      * Signature: RSA/ECDSA/EdDSA/SM2/Ring Signature
+      * Encryption: RSA/SM2
+  * Digest: SHA1/SHA2/SM3
+* Advanced Cryptography Algorithm
+  * PHE: Paillier, EC-ElGamal
+  * ZKP: Bulletproofs
+  * Post Quantum Cryptography
+* Hardware Support
+  * Acceleration card or CPU instruction sets
+  * HSMs
+* Cluster and HA
+  * Active - Active mode
+* Storage
+  * local disk
+  * etcd/consul...
+* Logging and Audit
+  * TBD