vaultrs 0.8.0

An asynchronous Rust client library for the Hashicorp Vault API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# vaultrs

<p align="center">
    <a href="https://crates.io/crates/vaultrs">
        <img src="https://img.shields.io/crates/v/vaultrs">
    </a>
    <a href="https://docs.rs/vaultrs">
        <img src="https://img.shields.io/docsrs/vaultrs" />
    </a>
    <a href="https://developer.hashicorp.com/vault/">
        <img src="https://img.shields.io/badge/Vault-1.8.2-green" />
    </a>
    <a href="https://github.com/jmgilman/vaultrs/actions/workflows/ci.yml">
        <img src="https://github.com/jmgilman/vaultrs/actions/workflows/ci.yml/badge.svg"/>
    </a>
</p>

> An asynchronous Rust client library for the [Hashicorp Vault][1] and [OpenBao][7] API

The following features are currently supported:

- Auth
  - [AppRole](https://developer.hashicorp.com/vault/docs/auth/approle)
  - [AWS](https://developer.hashicorp.com/vault/docs/auth/aws) (Only Vault is tested, as for OpenBao its an external plugin)
  - [JWT/OIDC](https://developer.hashicorp.com/vault/api-docs/auth/jwt)
  - [Kubernetes](https://developer.hashicorp.com/vault/docs/auth/kubernetes)
  - [Token](https://developer.hashicorp.com/vault/docs/auth/token)
  - [Certificate](https://developer.hashicorp.com/vault/docs/auth/cert)
  - [Userpass](https://developer.hashicorp.com/vault/docs/auth/userpass)
- Secrets
  - [AWS](https://developer.hashicorp.com/vault/docs/secrets/aws)
  - [Cubbyhole](https://developer.hashicorp.com/vault/docs/secrets/cubbyhole)
  - [Databases](https://developer.hashicorp.com/vault/api-docs/secret/databases)
  - [KV v1](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v1)
  - [KV v2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2)
  - [PKI](https://developer.hashicorp.com/vault/docs/secrets/pki)
  - [SSH](https://developer.hashicorp.com/vault/docs/secrets/ssh)
  - [Transit](https://developer.hashicorp.com/vault/api-docs/secret/transit)
- Sys
  - [Health](https://developer.hashicorp.com/vault/api-docs/system/health)
  - [Policies](https://developer.hashicorp.com/vault/api-docs/system/policy)
  - [Sealing](https://developer.hashicorp.com/vault/api-docs/system/seal)
  - [Wrapping](https://developer.hashicorp.com/vault/docs/concepts/response-wrapping)

See something missing?
[Open an issue](https://github.com/jmgilman/vaultrs/issues/new).

## Installation

First, choose one of the two TLS implementations for `vaultrs`' connection to
Vault:

- `rustls` (default) to use [Rustls](https://github.com/rustls/rustls)
- `native-tls` to use
  [rust-native-tls](https://github.com/sfackler/rust-native-tls), which builds
  on your platform-specific TLS implementation.

Then, add `vaultrs` as a dependency to your cargo.toml:

1. To use [Rustls](https://github.com/rustls/rustls), import as follows:

```toml
[dependencies]
vaultrs = "0.8.0"
```

2. To use [rust-native-tls](https://github.com/sfackler/rust-native-tls), which
   builds on your platform-specific TLS implementation, specify:

```toml
[dependencies]
vaultrs = { version = "0.8.0", default-features = false, features = [ "native-tls" ] }
```

## Usage

### Setup the client

The client is used to configure the connection to Vault and is required to be
passed to all API calls for execution. Behind the scenes it uses an asynchronous
client from [Reqwest](https://docs.rs/reqwest/) for communicating to Vault.

```rust
use vaultrs::client::{VaultClient, VaultClientSettingsBuilder};

// Create a client
let client = VaultClient::new(
    VaultClientSettingsBuilder::default()
        .address("https://127.0.0.1:8200")
        .token("TOKEN")
        .build()
        .unwrap()
).unwrap();
```

For more usages, take a look at [the documentation][6]

## Error Handling and Tracing

All errors generated by this crate are wrapped in the `ClientError` enum
provided by the crate. API warnings are automatically captured via `tracing` and
API errors are captured and returned as their own variant. Connection related
errors from `rustify` are wrapped and returned as a single variant.

All top level API operations are instrumented with `tracing`'s `#[instrument]`
attribute.

## Testing

See the the [tests][3] directory for tests. Run tests with `cargo test`.

**Note**: All tests rely on bringing up a local Vault development server using
Docker. In order to run tests Docker must be running locally (Docker Desktop
works). The first run will be longer than other because it will fetch images.

Some long-running tests are ignored by default locally. To run them do:

```sh
cargo test -- --include-ignored
```

## Contributing

Check out the [issues][2] for items needing attention or submit your own and
then:

1. Fork the repo (<https://github.com/jmgilman/vaultrs/fork>)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

See [CONTRIBUTING][5] for extensive documentation on the
architecture of this library and how to add additional functionality to it.

[1]: https://developer.hashicorp.com/vault/
[2]: https://github.com/jmgilman/vaultrs/issues
[3]: https://github.com/jmgilman/vaultrs/tree/master/vaultrs-tests/tests/api_tests
[5]: https://github.com/jmgilman/vaultrs/tree/master/CONTRIBUTING.md
[6]: https://docs.rs/vaultrs
[7]: https://openbao.org/