# vault-client

[![Build Status](https://travis-ci.org/Metaswitch/vault-client.svg?branch=master)](https://travis-ci.org/Metaswitch/vault-client) [![crates.io](https://img.shields.io/crates/v/vault-client.svg)](https://crates.io/crates/vault-client) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green.svg)](http://www.apache.org/licenses/LICENSE-2.0)

**vault-client** is a native client library for [HashiCorp Vault](https://www.vaultproject.io/) written in Rust. It is an alternative to [hashicorp_vault](https://crates.io/crates/hashicorp_vault), a less featured client that covers a broader range of the Vault API.

It uses an autogenerated client library for talking to the Vault API. **vault-client** then talks to the Vault server to keep its own authentication up to date, as well as keeping any secrets it has previously issued up to date. All secrets issued are cached, so that the **vault-client** can continue providing limited service if the Vault server goes down.

At the moment, the [token authentication backend](https://www.vaultproject.io/docs/auth/token.html) and [PKI secret backend](https://www.vaultproject.io/docs/secrets/pki/index.html) are the only back-ends supported. However, **vault-client** is designed to be readily extensible - contributions of support for other backends are very welcome.

## Developing

### vault-api

This crate has vault-api as a dependency, which provides a thin autogenerated client for the Vault API.

To add support for a new section of the Vault API, update the [swagger specification](vault-api/api/swagger.yaml) to include the new endpoints. Then, run `make`, checking the results in.

### Documentation

https://docs.rs/vault_client/

### Rustfmt

The CI pipeline for this crate will attempt to perform rustfmt, and will fail if it finds any differences. To avoid this, make sure to run `./run-in-docker.sh make rustfmt` before committing. (The reason for running in docker is to ensure that you use the same version of `rustfmt` as the CI pipeline.)

### Running a local vault server.

To run a local vault server, follow the following instructions:

1. [Install Vault](https://www.vaultproject.io/intro/getting-started/install.html)

2. [Generate the necessary SSL certificates](https://dunne.io/vault-and-self-signed-ssl-certificates)

    - You can instead use the pre-generated ones in `test/certificates`. To use, run `echo 000a > certificates/serialfile`,
      then `touch certificates/certindex`. Then run `sudo update-ca-trust enable`, copy `certificates/root.cer` to
      `/etc/pki/ca-trust/source/anchors/ca.crt`, and then run `sudo update-ca-trust extract`.

3. Run vault: `vault server -config=vault.config`, see the `vault.config` file in this directory for example
configuration.

4. Now we're going to configure the Vault further. Set up some environment variables, which allow you to use the Vault
CLI as a client of the Vault server. This can either be run from the Vault Server VM itself, or from elsewhere:
    ```
    export VAULT_ADDR="https://127.0.0.1:8200"
    export VAULT_CACERT="certificates/root.cer"
    ```
    Note that the address used must agree with the Common Name (`CN`) of the Vault's certificate. This may mean that you
    can't talk to the Vault server over `127.0.0.1`, depending on the certificate.

5. Run `vault init` and:
    ```
    export VAULT_TOKEN="<initial root token, or a new one that you created from that>"
    ```

6. Then: `vault unseal` three times (one for each key)

7. Mount the PKI backend. See [docs](https://www.vaultproject.io/docs/secrets/pki/) or follow the instructions below.
    ```
    vault mount pki
    vault mount-tune -max-lease-ttl=87600h pki
    vault write pki/root/generate/internal common_name=<this server's hostname/IP> ttl=87600h
    vault write pki/config/urls issuing_certificates="https://<this server's IP>:8200/v1/pki/ca" crl_distribution_points="https://<this server's IP>:8200/v1/pki/crl"
    vault write pki/roles/metaswitch allow_any_name="true" max_ttl="720h"
    ```
    - Now, you can manually write certificates with:
        - `vault write pki/issue/metaswitch common_name=blah.example.com`