CredStash Documentation

CredStash uses a combination of AWS Key Management Service (KMS) and Amazon DynamoDB (DDB) to manage secrets:

• Master Key: Stored in AWS KMS within secure HSM-backed storage. The master key never leaves the KMS service.
• Credential Store: Uses a DynamoDB table to store credentials. This provides low-latency fetches and scalable throughput.
• Retrieval: By default, get operations fetch the highest version number available for a specific credential key.

Credentials in CredStash are versioned and immutable.

Versioning Commands

• Rotate/Add Version: Use the -v flag to create a new version.

  credstash put foo baz -v

• Get Specific Version: Use the -v flag with get to retrieve a specific version.
• Auto-increment Versions: Use the -a flag with put to automatically increment the version number. Note that versions are left-padded with zeros (e.g., 001, 025) to ensure correct lexicographical sorting in DynamoDB.
• List Credentials: Use the list command to see all credentials and their versions.

Note on Sorting: Because DynamoDB uses lexicographical sorting, CredStash pads integer versions with zeros up to 19 characters.

After installing the package and ensuring your AWS credentials are accessible (via IAM roles, environment variables, or AWS config files), run the setup command to create the necessary DynamoDB table for credential storage.

Prerequisites

1. A KMS key named credstash must exist (or a custom name provided via -k).
2. AWS credentials must be available to boto/botocore.

Execution

credstash setup

CredStash handles credential rotation through versioning. Every credential in the store has a version number. To update a credential, you perform a put operation with a new version number. When performing a get operation, CredStash automatically fetches the most recent (highest version) version of that credential.

You can rotate credentials in two ways:

1. Manual Versioning: Specify the version number explicitly using the -v flag.
2. Autoincrementing: Use the -a flag to let CredStash attempt to autoincrement the version number.

To install CredStash, first ensure any Linux-specific build dependencies are installed, then use pip.

Linux Dependencies If you are on Linux, you must install build dependencies for the cryptography library:

• Debian/Ubuntu: sudo apt-get install build-essential libssl-dev libffi-dev python-dev
• Fedora/RHEL: sudo yum install gcc libffi-devel python-devel openssl-devel

Python Installation

pip install credstash

To include optional YAML support, use:

pip install credstash[YAML]

CredStash allows you to control which AWS region and account profile it uses.

Specifying Region

• Use the -r flag: credstash -r us-west-2 get my-secret
• Or set the AWS_DEFAULT_REGION environment variable.

Using AWS Profiles To work with different AWS accounts, set the AWS_PROFILE environment variable to match a profile in your ~/.aws/credentials file.

export AWS_PROFILE=prod
credstash get my-secret

Use the get command to fetch and decrypt a credential. The decrypted value is printed to stdout.

Basic Usage

export DB_PASSWORD=$(credstash get myapp.db.prod)

Retrieving with Encryption Context If the secret was stored with encryption context (key-value pairs), you must provide the exact same pairs to successfully decrypt it.

export DB_PASSWORD=$(credstash get myapp.db.prod environment=prod app.tier=db)

Use the put command to store a credential. CredStash encrypts the value using a unique data encryption key wrapped by your KMS master key, then stores it in DynamoDB.

Basic Usage

credstash put [credential-name] [credential-value]

Input Methods

• Direct Argument: credstash put myapp.db.prod supersecretpassword1234
• From a File: Prefix the filename with @.

  credstash put myapp.db.prod @secret.txt

• From stdin: Use - as the secret argument.

  echo "my-secret" | credstash put myapp.db.prod -

Adding Encryption Context You can associate key-value pairs with a secret for auditing or access control. These must be provided during get to decrypt the secret.

credstash put myapp.db.prod supersecretpassword1234 app.tier=db environment=prod

Use setup to prepare the DynamoDB table and configuration.

Usage: credstash setup [--save-kms-region SAVE_KMS_REGION] [--tags [TAGS ...]]

Key Options:

• --save-kms-region SAVE_KMS_REGION: Saves the KMS region to ~/.credstash so it is used independently of the DynamoDB table region.
• --tags [TAGS ...]: A space-separated list of Key=Value pairs to apply as tags to the DynamoDB table.

usage: credstash setup [-h] [--save-kms-region SAVE_KMS_REGION]
                          [--tags [TAGS [TAGS ...]]]

Use the put command to store a secret. You can provide the value directly, via a file (prefixed with @), or via stdin (using -).

Usage: credstash put <credential> [value] [context [context ...]]

Key Options:

• -k KEY: The KMS key-id to use (defaults to alias/credstash).
• -c COMMENT: Add a comment/reference to the value.
• -v VERSION: Specify a version (defaults to 1).
• -a, --autoversion: Automatically increment the version (ignores -v).
• -d DIGEST: Hashing algorithm (e.g., SHA256, SHA512, MD5). Defaults to SHA256.
• -P, --prompt: Prompt for the secret instead of providing it as an argument.

usage: credstash put [-h] [-k KEY] [-c COMMENT] [-v VERSION] [-a]
                        [-d {SHA,SHA224,SHA256,SHA384,SHA512,MD5}] [-P]
                        credential [value] [context [context ...]]

Use getall to retrieve multiple credentials from the store.

Usage: credstash getall [context [context ...]]

Key Options:

• -v VERSION: Get a specific version (defaults to latest).
• -f FORMAT: Output format: json (default), yaml, csv, or dotenv.

usage: credstash getall [-h] [-r REGION] [-t TABLE] [-p PROFILE | -n ARN] [-v VERSION] [-f {json,yaml,csv,dotenv}]
                            [context [context ...]]