vault-client

vault-client is a native client library for HashiCorp Vault written in Rust. It is an alternative to 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 and PKI secret backend 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 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

2. Generate the necessary 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 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