Rand Stats

WebService::HashiCorp::Vault

zef:PowellDean

Actions Status

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

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 PowellDean@gmail.com
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 $key from vault $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