Skip to content

Commit

Permalink
Add some more documents
Browse files Browse the repository at this point in the history
install.md and quick-start.md are added.
  • Loading branch information
InfoHunter committed Apr 30, 2024
1 parent 3529566 commit f3a98c0
Show file tree
Hide file tree
Showing 2 changed files with 250 additions and 0 deletions.
73 changes: 73 additions & 0 deletions doc/install.md
Original file line number Diff line number Diff line change
@@ -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.
177 changes: 177 additions & 0 deletions doc/quick-start.md
Original file line number Diff line number Diff line change
@@ -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 ;-)

0 comments on commit f3a98c0

Please sign in to comment.