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 $baseURL if you've set the environment variable $VAULT_ADDR:

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

You don't have to pass in $token if you've set the environment variable $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.

• base64

• hex ) method generateRandomBytes(Str :$format!, Int :$length!) { my $random = RandomData.new(); my $gibberish = $random.generateRandomBytes( baseURL=>$!baseURL, tkn=>$!token, format=>$format, length=>$length );