NAME

WebService::HashiCorp::Vault - An API for managing secrets with Vault

SYNOPSIS

use WebService::HashiCorp::Vault;

DESCRIPTION

WebService::HashiCorp::Vault is a module written in pure Raku for managing secrets with Vault by HashiCorp. For more information on what Vault is and how to use it, visit the official Vault website.

Note: This is a work in progress, and the supported endpoints are subject to change.

PRE-REQUISITES

• HashiCorp's executable for Vault, available from their website

• JSON::Tiny

• Cro HTTP Client tools

• The latest Raku compiler (this project was created with v6.d)

INSTALLATION

Installation is by the standard Raku package manager, Zef

zef install WebService::HashiCorp::Vault

To successfully run the test suite, you will need to have your Vault instance running and unsealed. Please set the environment variable $VAULT_TOKEN with the value of your token prior to running the tests.

Also ensure you set $VAULT_ADDR with the address/port of your running Vault instance.

USAGE

Connecting to a Running Vault Instance

Using an authentication token

use WebService::HashiCorp::Vault;
my $connection = Client.new(baseURL => 'http://127.0.0.1:8200',
    token => '<token generated by your Vault server>');

You don't have to pass in VAULT_ADDR:

use WebService::HashiCorp::Vault;
my $connection = Client.new(token => '<token generated by your Vault server>');

You don't have to pass in VAULT_TOKEN:

export VAULT_TOKEN=<token generated by your vault server>

use WebService::HashiCorp::Vault;
my $connection = Client.new();

Note that if you do not pass the Vault URL explicitly, and the environment variable $VAULT_ADDR is not set, the Client will use the default value http://127.0.0.1:8200

Working With Secrets

Saving Secrets

    # Save SecretV1 'foo' into vault 'cubbyhole'
    my $status = $connection.putSecretV1(vault => 'cubbyhole', key => 'foo',
        keyValues => %('bar', 'baz'));

    say $status.status;  # Will return standard HTTP return code 204 on success

    # Save SecretV2 'foo' into vault 'secret'
    my $status = $connection.putSecretV2(vault => 'secret', key => 'foo',
        keyValues => %('bar', 'baz'));

    say $status.status;  # Will return standard HTTP return code 204 on success

Listing Secrets

To list all the secret keys in the vault 'cubbyhole'

    say $connection.listV1Secrets(vault => 'cubbyhole');

If successful, the output will be a list of secret keys: ['foo', 'foo1', 'snafu'].

To list all the key/pair values found in a specific vault and key:

    # get a SecretV1 from vault 'cubbyhole'
    say $connection.getSecretV1(vault => 'cubbyhole', key => 'foo').data;

    # get a SecretV2 from vault 'secret'
    say $connection.getSecretV2(vault => 'secret', key => 'foo').data;

Deleting Secrets

    # Delete SecretV1 'foo' from vault 'cubbyhole'
    say $connection.deleteV1Secret(vault => 'cubbyhole', key => 'foo');
    # Will return 204 upon successful completion (standard HTTP return code)

    # Delete SecretV2 from vault 'secret'
    say $connection.deleteV2Secret(vault => 'secret', key => 'foo');
    # Will return 204 upon successful completion (standard HTTP return code)

AUTHOR

Dean Powell [email protected]

COPYRIGHT AND LICENSE

Copyright 2023 Dean Powell

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

class WebService::HashiCorp::Vault::Client

A client for communicating with the Vault API

multi method baseURL

multi method baseURL() returns Mu

Return the baseURL

multi method baseURL

multi method baseURL(
    $url
) returns Mu

Set the baseURL

multi method token

multi method token() returns Mu

Return the current session token

multi method token

multi method token(
    $aToken
) returns Mu

Set the current session token

method deleteV1Secret

method deleteV1Secret(
    Str :$vault!,
    Str :$key!
) returns Mu

Delete the secret with the key vault Will catch any generic error

method generateRandomBytes

method generateRandomBytes(
    Str :$format!,
    Int :$length!
) returns Mu

Return high-quality random bytes of the given length, in the requested format. Supported formats are: =item base64 =item hex

method getEncryptionKeyStatus

method getEncryptionKeyStatus() returns Mu

Query for encryption key status $status is a KeyStatus object with the following attributes: Int encryptions Str installTime Int leaseDuration Bool renewable Str requestId

method getSecretV1

method getSecretV1(
    Str :$vault!,
    Str :$key!
) returns Mu

Return the V1 secret found in the given vault, at the given key The returned value is a SecretV1 object with the following attributes: ResponseHeader header (Hash of key/value pairs) data