Merge pull request #55 from InfoHunter/more-doc

Refactor and add documents

README.md

@@ -58,4 +58,4 @@ Part of the features provided by RustyVault are as follows:
 
 ## Design
 
-Read the [design](./design.md) document.
+Read the [design](./doc/design.md) document.

design-cn.md → doc/design-cn.md

@@ -4,7 +4,7 @@
 
 # 结构图
 
-<img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/RustyVault.png" width=50% height=50% />
+<img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/doc/RustyVault-arch.png" width=50% height=50% />
 
 说明如下：
 
@@ -17,4 +17,4 @@
 
 3. 密码硬件，如加密机、加密卡等，的使用对RustyVault是透明的，该过程由铜锁屏蔽，因此RustyVault对于硬件的差异和对接是无感的。
 
-4. RustyVault中的敏感安全参数（如各种密钥、随机数、认证信息等）中存在持久化存储需求的，可以在本地加密存储，或者连接外部存储（如etcd）。连接外部存储对于创建RustyVault集群是必须的。存储方面的管理由RustyVault Core中的Storage Manager负责，RustyVault的其他组件也无需感知不同存储方式之间的使用差异。
+4. RustyVault中的敏感安全参数（如各种密钥、随机数、认证信息等）中存在持久化存储需求的，可以在本地加密存储，或者连接外部存储（如etcd）。连接外部存储对于创建RustyVault集群是必须的。存储方面的管理由RustyVault Core中的Storage Manager负责，RustyVault的其他组件也无需感知不同存储方式之间的使用差异。

design.md → doc/design.md

@@ -4,7 +4,7 @@ As per: [RustyVault Requirements Document](./req.md). In this document we descri
 
 # Architecture Diagram
 
-<img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/RustyVault.png" width=50% height=50% />
+<img src="https://github.com/Tongsuo-Project/RustyVault/blob/main/doc/RustyVault-arch.png" width=50% height=50% />
 
 Detailed description:
 
@@ -17,4 +17,4 @@ Detailed description:
 
 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. 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.
+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.

doc/install.md

@@ -0,0 +1,73 @@
+# Install RustyVault
+
+RustyVault must be installed properly in your environment before it actually works. Currently RustyVault is only available by source code. RustyVault can be used as an application or a library, thus:
+
+1. RustyVault is available to compile from source code only, or
+2. RustyVault is availabe on [crates.io](https://crates.io/crates/rusty_vault) for other Rust projects.
+
+This document is about how to build and install RustyVault in the application form. For the library form, please go to [docs.rs](https://docs.rs/rusty_vault/latest/rusty_vault) for more information.
+
+## Operating System
+
+RustyVault is supposed to work on the following operating systems:
+
+* Linux
+* macOS
+* Windows (experimental)
+
+In this document, macOS is used as the demonstration operating system.
+
+## Prerequisite
+
+RustyVault is developed in [Rust](https://rust-lang.org) programming language, so Rust must be properly installed in your environment before building RustyVault.
+
+Read [this](https://www.rust-lang.org/tools/install) to make Rust work for you.
+
+## Build from Source
+
+Clone the latest RustyVault source code from Github:
+
+~~~
+git clone https://github.com/Tongsuo-Project/RustyVault.git
+~~~
+
+Then you have a directory called RustyVault now. Change directory into it.
+
+~~~
+cd RustyVault
+~~~
+
+Simply build the binary by using the tool Cargo.
+
+~~~
+cargo build
+~~~
+
+Rust toolchain is responsible for taking care of almost everything during the build process. After RustyVault is successfully built, you get a bundle of files in the `RustyVault/target/debug` directory. There will be a executable file called `rvault`, which is the application of RustyVault.
+
+## Verify RustyVault
+
+Simply run the following command:
+
+~~~
+target/debug/rvault --help
+~~~
+
+And you will get a response similar to:
+
+~~~
+A secure and high performance secret management software that is compatible with Hashicorp Vault.
+
+Usage: rvault [COMMAND]
+
+Commands:
+  server  Start a rusty_vault server
+  status  Print seal and HA status
+  help    Print this message or the help of the given subcommand(s)
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+~~~
+
+That means you now have a ready-to-use RustyVault binary.

doc/quick-start.md

@@ -0,0 +1,177 @@
+# RustyVault Quick Start
+
+In this document, we demonstrate several minimum but necessary steps for starting up a RustyVault server and make it functional for real features.
+
+This quick start document includes examples to:
+
+1. how to build RustyVault binary from source
+2. how to start a basic RustyVault server
+3. how to configure a RustyVault server
+4. how to use a RustyVault server to store sensitive data (the 'secrets', for instance)
+
+## Build from Source
+
+Read [install.md](./install.md) if you want more detailed information on installation.
+
+Clone RustyVault from Github:
+
+~~~
+% git clone https://github.com/Tongsuo-Project/RustyVault.git
+
+% cd RustyVault
+~~~
+
+Build RustyVault by using Rust toolchain:
+
+~~~
+% cargo build
+~~~
+
+If the build is successful, then you now have an executable binary file called `rvault` in `RustyVault/target/debug` directory.
+
+## Run the Server
+
+RustyVault runs as a daemon in the operation system. It's basically a server that provides a set of RESTful HTTP APIs. So after the server is running in the background, you can send HTTP requests to ask the server to do the jobs.
+
+To launch a RustyVault server, a configuration file is needed. As Hashicorp Vault, RustyVault can also parse HCL configuration files. A typical usable example RustyVault configuration file is as follows:
+
+~~~
+storage "file" {
+    path    = "./data"
+}
+
+listener "tcp" {
+    address     = "127.0.0.1:8200"
+    tls_disable = "true"
+    tls_cert_file = "servercert.pem"
+    tls_key_file = "serverkey.pem"
+    tls_disable_client_certs = false
+    tls_require_and_verify_client_cert = false
+}
+
+daemon = true
+daemon_user = "paul"
+daemon_group = "staff"
+
+work_dir = "/Users/paul/work/tmp/rusty_vault/"
+
+api_addr = "http://127.0.0.1:8200"
+log_level = "debug"
+pid_file = "rusty_vault.pid"
+~~~
+
+You need to change the variables like `daemon_user`, `daemon_group` and `work_dir` to the actual value in your environment. Then just copy and paste it to a local file, say, `rvault.hcl` somewhere on your machine.
+
+Then launch the server (assume you are still in `RustyVault` directory):
+
+~~~
+% target/debug/rvault server --config /path/to/rvault.hcl
+~~~
+
+Check the process is running:
+
+~~~
+% ps -xa | grep rvault
+
+89174 ??         0:00.46 target/debug/rvault server --config /Users/paul/work/tmp/rvault.hcl
+89448 ttys006    0:00.00 grep rvault
+~~~
+
+There should be an `rvault` process running in background.
+
+Now the server is listening on TCP port 8200 and it's ready for incoming HTTP requests.
+
+## Initialize RustyVault
+
+Before it's fully usable, a RustyVault server needs to be initialized. For instance, a master key is generated during the initialization procedure and is used to `seal` and `unseal` RustyVault, thus the data in RustyVault can be correctly encrypted.
+
+In this section, we use command line tool `curl` to manipulate the server and use `jq` to parse the JSON data in the HTTP responses. `jq` is not required, but we highly recommend to install it on your machine. Click [here](https://jqlang.github.io/jq/download/) for more information on installing `jq`.
+
+To launch the server, simply run:
+
+~~~
+% curl --request PUT --data '{"secret_shares": 1, "secret_threshold": 1}' http://127.0.0.1:8200/v1/sys/init | jq
+~~~
+
+The response should be similar to this:
+
+~~~
+{
+  "keys": [
+    "7df5ff90cd9417e04cbb9f6db65e0b16ce265d5108fd07e45bdae1a35bf5da6a"
+  ],
+  "root_token": "bc9e904b-acff-db3d-4cfd-f575cb36428a"
+}
+~~~
+
+Now we have a key to unseal RustyVault and a root token.
+
+You can check the initialization status by sending:
+
+~~~
+% curl http://127.0.0.1:8200/v1/sys/init | jq
+{
+  "initialized": true
+}
+~~~
+
+## Unseal the RustyVault Server
+
+When RustyVault is initialized properly, it's in the *sealed* status. *Seald* here means everything in RustyVault is encrypted and protected, thus no one can use any functionality RustyVault. You need to *unseal* it to make it fully functional.
+
+To unseal, the key generated in previous section will be used:
+
+~~~
+% curl --request PUT --data '{"key": "7df5ff90cd9417e04cbb9f6db65e0b16ce265d5108fd07e45bdae1a35bf5da6a"}' http://127.0.0.1:8200/v1/sys/unseal | jq
+~~~
+
+If everything went smoothly, then a response with `sealed: false` will be returned:
+
+~~~
+{
+  "sealed": false,
+  "t": 1,
+  "n": 1,
+  "progress": 0
+}
+~~~
+
+This indicates the RustyVault server is not sealed and it's ready to do more real jobs.
+
+## Write Secrets to RustyVault
+
+A frequently used feature of RustyVautl is *secret*, it's basically a secure key-value storage that can retain arbitary sensitive values such as password, credentials, tokens, keys and so forth.
+
+RustyVault needs client authentication for further operations. In this demonstration, we utilize the `root_token` generated in previous section for simplicity.
+
+Let's ask RustyVault to store a `foo: bar` value under the key `test`:
+
+~~~
+% curl --Header "Cookie: token=bc9e904b-acff-db3d-4cfd-f575cb36428a" --request POST --data '{ "foo": "bar" }' http://127.0.0.1:8200/v1/secret/test | jq
+~~~
+
+Then read it out:
+
+~~~
+% curl --Header "Cookie: token=bc9e904b-acff-db3d-4cfd-f575cb36428a" http://127.0.0.1:8200/v1/secret/test | jq
+{
+  "renewable": false,
+  "lease_id": "",
+  "lease_duration": 3600,
+  "auth": null,
+  "data": {
+    "foo": "bar"
+  }
+}
+~~~
+
+In the `data` section of the responsed JSON, you can see the `foo:bar` value once again!
+
+## Next Steps
+
+In this document, we built a RustyVault server, started it up and configured it to accept user commands such as storing sensitive data. All examples here are only for demonstration purposes, they may not safe in real production scenarios. Some more features are introduced in RustyVault to make it production ready:
+
+* Authentication methods: RustyVault offers different authentication methods, which allow you create new client tokens with fine-grained access policy,
+* More storage types: This demonstration uses local file as storage, but in reality it's neither efficient nor secure. RustyVault also supports other remote storage types like database, remote file system or so.
+* Running status: a log file is located in the working directory of RustyVault, important information is logged in it for debug or other purposes.
+* Compatibility with Hashicorp Vault: RustyVault is compatible with Hashicorp Vault, so most Hashicorp Vault documentation is also worth to read to help you understand RustyVault ;-)