Skip to content

Latest commit

 

History

History
236 lines (200 loc) · 10.2 KB

README.md

File metadata and controls

236 lines (200 loc) · 10.2 KB

libvault

CMake Version

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.

Secret Backend Implemented Integration Tested
Active Directory Yes No
Ali Cloud Yes No
AWS Yes No
Azure Yes No
Consul Yes No
Cubbyhole Yes Yes
Cassandra Yes No
Couchbase Yes No
Elasticsearch Yes No
Influxdb Yes No
HanaDB Yes No
MongoDB Yes No
MongoDB Atlas Yes No
MSSQL Yes No
MySQL/MariaDB Yes No
Oracle Yes No
PostgreSQL Yes Partial
Redshift Yes No
Google Cloud Yes No
Google Cloud KMS Yes No
Key Management* Yes No*
KMIP Yes No*
Key/Value V1 Yes Partial
Key/Value V2 Yes Partial
Identity Yes No
MongoDB Atlas Yes No
Nomad Yes No
OpenLDAP Yes No
PKI Yes Partial
RabbitMQ Yes Partial
SSH Yes No
TOTP Yes Yes
Transform Yes No*
Transit Yes Partial

* Requires an enterprise license and cannot be integration tested

Auth Method Implemented Integration Tested
AliCloud Yes No
AppRole Yes Yes
AWS Yes No
Azure Yes No
Cloud Foundry Yes No
GitHub Yes No
Google Cloud Yes No
JWT/OIDC Yes No
Kerberos Yes No
Kubernetes Yes No
LDAP Yes No
OCI Yes No
Okta Yes No
RADIUS Yes No
TLS Certificate Yes No
Tokens Yes Yes
Username/Password Yes No

* Requires an enterprise license and cannot be integration tested

System Backend Implemented Integration Tested
/sys/health Yes Yes
/sys/leader Yes Yes
/sys/auth Yes Yes
/sys/wrapping Yes Yes
/sys/audit Yes No
/sys/audit-hash Yes No
/sys/capabilities Yes No
/sys/capabilities-accessor Yes No
/sys/capabilities-self Yes No
/sys/config/auditing Yes No
/sys/config/control-group Yes No
/sys/config/cors Yes No
/sys/config/state Yes No
/sys/config/ui Yes No
/sys/control-group Yes No
/sys/host-info Yes No
/sys/init Yes No
/sys/internal/counters Yes No
/sys/plugins/reload/backend Yes No
/sys/internal/ui/mounts Yes No
/sys/key-status Yes No
/sys/leases Yes No
/sys/license Yes No
/sys/metrics Yes No
/sys/mounts Yes No
/sys/remount Yes No
/sys/rotate Yes No
/sys/seal Yes No
/sys/seal-status Yes No
/sys/step-down Yes No
/sys/unseal Yes No
/sys/mfa Yes No
/sys/namespaces Yes No*
/sys/generate-root Yes No
/sys/internal/specs/openapi Yes No
/sys/plugins/catalog Yes No
/sys/policy Yes No
/sys/policies Yes No*
/sys/pprof Yes No
/sys/raw Yes No
/sys/sealwrap/rewrap Yes No
/sys/tools Yes No
/sys/rekey No No
/sys/rekey-recovery-key No No
/sys/replication No No
/sys/storage No No

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