libvault

A C++ library for Hashicorp Vault

C++ 17

This project assumes a C++ 17 capable compiler. This includes GCC 8 or higher, and clang 3.8 or higher. Support for lower standards versions of C++ will not be accepted due to inconsistent implementations of optional.

Dependencies

• cURL
• Catch2 (test only)

Usage

The following example shows both a secret put and get. The most common scenario is get for most applications and the put will happen outside of the application by another process. Additional examples are located in the example directory.

#include <iostream>
#include <libvault/VaultClient.h>

int main(void)
{
  Vault::HttpErrorCallback httpErrorCallback = [&](std::string err) {
    std::cout << err << std::endl;
  };

  Vault::AppRoleStrategy authStrategy{
    Vault::RoleId{"<role_id>"},
    Vault::SecretId{"<secret_id>"}
  };

  Vault::Config config = Vault::ConfigBuilder().build();
  Vault::Client vaultClient{config, authStrategy, httpErrorCallback};
  Vault::SecretMount mount{"/test"};
  Vault::KeyValue kv{vaultClient, mount};
  Vault::Path key{"hello"};
  Vault::Parameters parameters(
    {
      {"foo","world"},
      {"baz","quux"},
      {"something", "something else"},
    }
  );

  kv.create(key, parameters);

  std::cout << kv.read(key).value() << std::endl;
}

JSON Serialization

This project uses nlohmann/json internally but does not expose it. This project makes no assumptions about serialization and returns std:string values that can be serialized by the tooling of your choice. Should you choose to use nlohmann/json you can add the json.hpp file to your project. This project's integration tests have multiple examples of how to use it.

Feature Support

The following tables show support for each of the secret backends, auth methods, and system endpoints. Because the surface area is so large, endpoints are implemented as needed. Pull requests are welcome. Feel free to file an issue or submit a pull request for additional support.

* Requires an enterprise license and cannot be integration tested

* Requires an enterprise license and cannot be integration tested

* Requires an enterprise license and cannot be integration tested

Compile and Install

This project uses CMake. To build the library run the following commands from the project root:

mkdir build
cd build
cmake ../
make

Compile Options

The following custom options can be provided to CMake to control your build:

• ENABLE_TEST [ON|OFF] - [Default ON] Standard unit tests (Requires the Catch2 testing library)
• ENABLE_INTEGRATION_TEST [ON|OFF] - [Default OFF] Enable integration tests (Requires configured, running Vault)
• ENABLE_COVERAGE [ON|OFF] - [Default OFF] Enable gcov code coverage
• LINK_CURL [ON|OFF] - [Default OFF] Link curl library when compiling

Local Development

This project uses a standard C++ development with CMake environment. Additionally, a running and configured instance of Vault is required to run the integration tests. This project contains scripts that will download Vault, configure it, and run it. You are of course welcome to use your own Vault instance, but you will need to use the configuration from the script folder for the tests to pass.

Vault Setup

Use the provided scripts to setup and run your Vault environment:

$ script/fetch_vault
$ script/vault
# In another terminal window
$ script/bootstrap

This will ensure you have a working instance of Vault that will work with the integration tests. Note that this setup does not demonstrate a production worthy configuration and should only be used for reference or inside of this project. For you production Vault setup please consult the Hashicorp Vault best practices.