An asynchronous Rust client library for the Hashicorp Vault API

Overview

vaultrs

An asynchronous Rust client library for the Hashicorp Vault API

The following features are currently supported:

See something missing? Open an issue.

Installation

Add vaultrs as a dependency to your cargo.toml:

[dependencies]
vaultrs = "0.5.4"

Usage

Basic

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 for communicating to Vault.

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();

Secrets

The library currently supports all operations available for version 2 of the key/value store.

use serde::{Deserialize, Serialize};
use vaultrs::kv2;

// Create and read secrets
#[derive(Debug, Deserialize, Serialize)]
struct MySecret {
    key: String,
    password: String,
}

let secret = MySecret {
    key: "super".to_string(),
    password: "secret".to_string(),
};
kv2::set(
    &client,
    "secret",
    "mysecret",
    &secret,
).await;

let secret: MySecret = kv2::read(&client, "secret", "mysecret").await.unwrap();
println!("{}", secret.password) // "secret"

PKI

The library currently supports all operations available for the PKI secrets engine.

use vaultrs::api::pki::requests::GenerateCertificateRequest;
use vaultrs::pki::cert;

// Generate a certificate using the PKI backend
let cert = cert::generate(
    &client,
    "pki",
    "my_role",
    Some(GenerateCertificateRequest::builder().common_name("test.com")),
).await.unwrap();
println!("{}", cert.certificate) // "{PEM encoded certificate}"

Wrapping

All requests implement the ability to be wrapped. These can be passed in your application internally before being unwrapped.

use vaultrs::api::ResponseWrapper;
use vaultrs::api::sys::requests::ListMountsRequest;

let endpoint = ListMountsRequest::builder().build().unwrap();
let wrap_resp = endpoint.wrap(&client).await; // Wrapped response
assert!(wrap_resp.is_ok());

let wrap_resp = wrap_resp.unwrap(); // Unwrap Result<>
let info = wrap_resp.lookup(&client).await; // Check status of this wrapped response
assert!(info.is_ok());

let unwrap_resp = wrap_resp.unwrap(&client).await; // Unwrap the response
assert!(unwrap_resp.is_ok());

let info = wrap_resp.lookup(&client).await; // Error: response already unwrapped
assert!(info.is_err());

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 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).

Contributing

Check out the issues 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 for extensive documentation on the architecture of this library and how to add additional functionality to it.

Issues
  • feat: add tracing support.

    feat: add tracing support.

    Thought I'd take a shot at this one. Closes #8.

    I've added spans to every operation I can find, but I haven't added any additional log messages yet.

    Looks like it would be good to implement this in the rustify crate as well. In Client::execute for example.

    opened by fourbytes 5
  • Adds AppRole auth method

    Adds AppRole auth method

    Adds functionality needed for AppRole authentication:

    • Login with Approle
    • List Roles
    • Create/Update AppRole
    • Read AppRole
    • Delete AppRole
    • Read AppRole RoleID
    • Generate New Secret ID

    Some API endpoints remain to be implemented.

    opened by nhey 3
  • Adds support for using wrapping token as client token

    Adds support for using wrapping token as client token

    in order to unwrap said token without authenticating first.

    From the sys/wrapping/unwrap api docs (https://www.vaultproject.io/api-docs/system/wrapping-unwrap#wrapping-unwrap):

    This endpoint can be used by using a wrapping token as the client token in the API call, in which case the token parameter is not required [...]. Do not use the wrapping token in both locations; this will cause the wrapping token to be revoked but the value to be unable to be looked up, as it will basically be a double-use of the token!

    I have tested that it works. Should I add a test case to the cargo tests?

    opened by nhey 2
  • Fixes bug in generic login for clients

    Fixes bug in generic login for clients

    Apologies if I am fixing code that you did not intend to release yet; I am writing an application using this library and noticed the client login method does not take effect (requests to Vault are denied).

    opened by nhey 1
  • API Support: Database Secrets Engine

    API Support: Database Secrets Engine

    Support for the database secrets engine would be great to have.

    In our case, we're using the PostgreSQL plugin.

    enhancement api 
    opened by fourbytes 1
  • Introduce tracing to improve debugging

    Introduce tracing to improve debugging

    The library currently doesn't utilize any form of logging. The tokio project has a crate that introduces tracing which seems like a reasonable solution considering most consumers are likely already using the tokio runtime. It's also well-integrated with other logging crates for choose-your-adventure type support.

    enhancement stability 
    opened by jmgilman 0
  • Adds additional tracing to client and API functions

    Adds additional tracing to client and API functions

    • Instruments the Client
    • Instruments internal API functions including middleware
    opened by jmgilman 0
  • Adds dockertest-server and removes vaultrs-test for testing

    Adds dockertest-server and removes vaultrs-test for testing

    • Adds dockertest-server as the replacement for vaultrs-test
    • Converts tests to use dockertest-server
    • Removes vaultrs-test from repo and CI
    opened by jmgilman 0
  • Improves CI workflow

    Improves CI workflow

    • Breaks out crates into separate jobs
    • Adds caching
    • General cleanup
    opened by jmgilman 0
  • Workflow cleanup

    Workflow cleanup

    Integrates changes from a larger effort to standardize CI workflows across my Rust repositories.

    opened by jmgilman 0
  • AWS auth method

    AWS auth method

    Implements AWS auth (https://www.vaultproject.io/api-docs/auth/aws).

    I'm still working on the tests and I'm going to use localstack for this. Vault AWS API has some deprecated endpoints. Do you have any suggestions on how to support them (and whether to support them at all)?

    opened by Anexen 3
  • RUSTSEC-2020-0071: Potential segfault in the time crate

    RUSTSEC-2020-0071: Potential segfault in the time crate

    Potential segfault in the time crate

    | Details | | | ------------------- | ---------------------------------------------- | | Package | time | | Version | 0.1.43 | | URL | https://github.com/time-rs/time/issues/293 | | Date | 2020-11-18 | | Patched versions | >=0.2.23 | | Unaffected versions | =0.2.0,=0.2.1,=0.2.2,=0.2.3,=0.2.4,=0.2.5,=0.2.6 |

    Impact

    Unix-like operating systems may segfault due to dereferencing a dangling pointer in specific circumstances. This requires an environment variable to be set in a different thread than the affected functions. This may occur without the user's knowledge, notably in a third-party library.

    The affected functions from time 0.2.7 through 0.2.22 are:

    • time::UtcOffset::local_offset_at
    • time::UtcOffset::try_local_offset_at
    • time::UtcOffset::current_local_offset
    • time::UtcOffset::try_current_local_offset
    • time::OffsetDateTime::now_local
    • time::OffsetDateTime::try_now_local

    The affected functions in time 0.1 (all versions) are:

    • at
    • at_utc
    • now

    Non-Unix targets (including Windows and wasm) are unaffected.

    Patches

    Pending a proper fix, the internal method that determines the local offset has been modified to always return None on the affected operating systems. This has the effect of returning an Err on the try_* methods and UTC on the non-try_* methods.

    Users and library authors with time in their dependency tree should perform cargo update, which will pull in the updated, unaffected code.

    Users of time 0.1 do not have a patch and should upgrade to an unaffected version: time 0.2.23 or greater or the 0.3 series.

    Workarounds

    No workarounds are known.

    References

    time-rs/time#293

    See advisory page for additional details.

    dispensation security 
    opened by github-actions[bot] 0
  • RUSTSEC-2020-0159: Potential segfault in `localtime_r` invocations

    RUSTSEC-2020-0159: Potential segfault in `localtime_r` invocations

    Potential segfault in localtime_r invocations

    | Details | | | ------------------- | ---------------------------------------------- | | Package | chrono | | Version | 0.4.19 | | URL | https://github.com/chronotope/chrono/issues/499 | | Date | 2020-11-10 |

    Impact

    Unix-like operating systems may segfault due to dereferencing a dangling pointer in specific circumstances. This requires an environment variable to be set in a different thread than the affected functions. This may occur without the user's knowledge, notably in a third-party library.

    Workarounds

    No workarounds are known.

    References

    See advisory page for additional details.

    dispensation security 
    opened by github-actions[bot] 0
  • Add auth/kubernetes

    Add auth/kubernetes

    Implements auth via Kubernetes serviceaccount (https://www.vaultproject.io/api-docs/auth/kubernetes)

    Also: Added basic tests for all endpoints, except login. The reason being that it seems to require a dockertest server with a webserver that can simulate a TokenReviewResponse from a k8s apiserver. I think adding something like "httpmock" to you dockertest-server repository could do the trick? Perhaps, except that Vault requires TLS-connections to the APIserver, so it would require a TLS-proxy container as well, or a specialized docker image for handling all of the above.

    tldr, it was too much work for me to find a fitting solution for this at the moment. I would like to request help/suggestions for implementing the login test later at some point.

    opened by johanot 3
  • API Support: Consul Secrets Engine

    API Support: Consul Secrets Engine

    Tracking bug for implementing support for the Transit engine.

    enhancement good first issue api 
    opened by jmgilman 0
  • API Support: Cubbyhole Secrets Engine

    API Support: Cubbyhole Secrets Engine

    Tracking bug for implementing support for the Cubbyhole engine.

    enhancement good first issue api 
    opened by jmgilman 0
  • API Support: Transit Secrets Engine

    API Support: Transit Secrets Engine

    Tracking bug for implementing support for the Transit engine.

    enhancement good first issue api 
    opened by jmgilman 0
Notion Offical API client library for rust

Notion API client library for rust.

Jake Swenson 15 Nov 22, 2021
Meteor Client Installer - Installer to automate the install of Fabric and Meteor Client

This is an installer that automates the install of Meteor and Fabric

Jake Priddle 3 Jun 23, 2021
A library to access BGPKIT Broker API and enable searching for BGP data archive files over time from public available data sources.

BGPKIT Broker BGPKIT Broker is a online data API service that allows users to search for publicly available BGP archive files by time, collector, proj

BGPKIT 4 Nov 16, 2021
Yet another ROS2 client library written in Rust

RclRust Target CI Status Document Foxy (Ubuntu 20.04) Introduction This is yet another ROS2 client library written in Rust. I have implemented it inde

rclrust 19 Nov 22, 2021
librdkafka - the Apache Kafka C/C++ client library

librdkafka - the Apache Kafka C/C++ client library Copyright (c) 2012-2020, Magnus Edenhill. https://github.com/edenhill/librdkafka librdkafka is a C

Magnus Edenhill 5.6k Nov 28, 2021
Rust lib for Scaleway API

Notes This Scaleway API Crate is created and maintained by Qovery and used in production in the Qovery Engine. This project relies on OpenAPI Generato

Qovery 4 Nov 11, 2021
The official rust implementation of the SpamProtectionBot API

SpamProtection-rs Table of contents About Supported Rust version Features How to use Credits License About SpamProtection-Rust is a Rust wrapper for I

Intellivoid 10 Oct 3, 2021
Rust bindings for the KING OF TIME API

Rust bindings for the KING OF TIME API Example Prints if you are at work or not at work. $ cargo run --example tc -- status Record the time you start

Idein Inc. 2 Oct 11, 2021
A Rust API for D-Bus communication.

zbus A Rust API for D-Bus communication. The goal is to provide a safe and simple high- and low-level API akin to GDBus, that doesn't depend on C libr

Michael Murphy 2 Nov 6, 2021
A Discord bot for sending GeoGuessr challenge links that uses the GeoGuessr API written in rust.

GeoGuessr-bot-rs This is a simple implementation of a discord bot that send GeoGuessr-challenge links on demand. Features: Slash-commands Lightning-fa

Luukas Pörtfors 3 Nov 1, 2021
A rust wrapper for the spam protection API

SpamProtection-rs Table of contents About Supported Rust version Features How to use Credits License About This repo has been shifted to the official

cyberknight777 25 Nov 21, 2021
🚀 Fast and 100% API compatible postcss replacer, built in Rust

?? Fast and 100% API compatible postcss replacer, built in Rust

迷渡 258 Nov 23, 2021
Rust bindings for the Mattermost API

mattermost_api Rust bindings for the Mattermost API Installing Add the latest version to your Cargo.toml. Using Docs link. Developing Building Require

Matt Boulanger 0 Nov 8, 2021
A gui api explorer written in Rust.

Zzz - GUI Api platform Pronounced "Zees"; as in "catching some Z's". A pun on RESTful APIs. example URL: https://jsonplaceholder.typicode.com/todos/ T

Ryan Blecher 0 Nov 11, 2021
A Rust wrapper for the SponsorBlock API.

sponsor-block A Rust wrapper for the SponsorBlock API, which you can find complete documentation for here. Uses SponsorBlock data licensed under CC BY

Zacchary Dempsey-Plante 5 Nov 20, 2021
A powerful minecraft bedrock software written in Rust with a powerful Typescript plugin API.

Netrex A powerful minecraft bedrock software written in RustLang. Why Netrex? It's written in Rust. Unique and straight to the point. Typescript Plugi

Netrex 21 Nov 30, 2021
mdzk is a plain text Zettelkasten system that is based on the mdBook API.

mdzk A lovingly designed system and static publishing tool for your plain text Zettelkasten mdzk is a plain text Zettelkasten system that is based on

mdzk 98 Dec 1, 2021
A simple Pokedex API

A simple Pokedex API

Chris Tsang 1 Nov 14, 2021
Rust client for Pushover

Pushover RS Description It's a Rust client library you can use to interact with the Pushover messaging API. This client is unofficial and I'm in no wa

Emmanuel C. 1 Nov 24, 2021