credstash

Warnings

• breaking Credstash migrated from PyCrypto to Cryptography, and in v1.15.0, unsupported hashing methods were removed. Users with older secret stores (pre-v1.15.0) or custom hashing methods may experience decryption failures. Additionally, v1.13.4 introduced an upper bound on `cryptography` due to incompatibilities, which might cause installation issues with newer `cryptography` versions.
  Fix: Upgrade `credstash` to the latest version and ensure `cryptography` is within compatible bounds. For very old secret stores (prior to v1.15.0) that used removed hashing methods, consider re-encrypting secrets with a supported method or migrating data. On Linux, ensure C compiler and development libraries for `cryptography` are installed (e.g., `build-essential libssl-dev libffi-dev python-dev` for Debian/Ubuntu).
• gotcha Prior to v1.17.0, `credstash` might have logged sensitive information to local disk when imported as a library, potentially exposing secrets or causing issues in read-only environments. As of v1.17.0, logging is disabled by default when used as a library.
  Fix: Upgrade to `credstash` v1.17.0 or higher. For older versions, explicitly configure logging to prevent disk writes, or be aware of potential local log files.
• gotcha In `v1.17.1`, a bug was fixed where `kms_region` as an optional parameter could cause issues when other parameters were passed positionally. While fixed, relying solely on positional arguments for optional parameters can lead to unexpected behavior.
  Fix: Always use keyword arguments when calling `credstash` functions, especially for optional parameters like `kms_region`, to avoid positional argument conflicts. Upgrade to `v1.17.1` or newer.
• breaking Older versions of `credstash` (prior to December 2015) used unpadded integers for auto-versioning secrets, which could lead to incorrect sorting and retrieval of the latest secret once versions reached 10 or more. This is a significant issue for legacy secret stores.
  Fix: If you have a legacy secret store created before December 2015 and used auto-versioning, you must run the `credstash-migrate-autoversion.py` script provided in the repository to reformat version numbers to be lexicographically sortable. Newer versions of `credstash` automatically left-pad integer versions.
• gotcha Credstash requires an initial setup: a KMS master key (default alias `credstash`) must be created manually in AWS KMS, and the `credstash setup` command must be run to create the default DynamoDB table (`credential-store`). The library will not function without these prerequisites.
  Fix: Before using `credstash`, ensure a KMS key named `alias/credstash` exists in your AWS account and region, and run `credstash setup` from the command line (or manually create the `credential-store` DynamoDB table with `name` and `version` as primary keys).
• gotcha The default security model for `credstash` assumes the EC2 instance boundary as the security boundary. If an attacker gains sufficient access to an EC2 instance (e.g., to the instance metadata service or process memory), they may be able to retrieve credentials.
  Fix: Implement additional security measures on EC2 instances, such as restricting access to the Instance Metadata Service (IMDS) using `iptables` or configuring IMDSv2. Be aware that Python process memory dumps can expose secrets, a fundamental limitation when handling sensitive data in memory.

Install

• pip install credstash Basic installation
• pip install credstash[YAML] With YAML support

Imports

• credstash

  import credstash

  The common pattern is to import the `credstash` module directly and call methods like `credstash.getSecret()` or `credstash.putSecret()`.

Quickstart

This quickstart demonstrates how to programmatically store and retrieve a secret using the `credstash` Python API. It assumes AWS credentials are configured (e.g., via environment variables or an IAM role) and that a KMS key aliased 'credstash' and a DynamoDB table named 'credential-store' have been created. It uses explicit `boto3` clients for clarity, though `credstash` can often infer them from the environment.

import os
import credstash
import boto3

# Ensure AWS credentials are set up (e.g., via environment variables like AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
# Or configure a Boto3 session explicitly

# For demonstration, assume credentials are in env or IAM role is attached
# Set a specific region if not relying on AWS_DEFAULT_REGION or instance metadata
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')

# Initialize Boto3 clients if custom sessions or specific clients are needed
kms_client = boto3.client('kms', region_name=aws_region)
dynamodb_client = boto3.client('dynamodb', region_name=aws_region)

# Instantiate Credstash (optional, can also call functions directly)
stash = credstash.Credstash(table='credential-store', region=aws_region)

secret_name = "my_test_secret"
secret_value = "supersecretpassword123"

try:
    # Put a secret
    # By default, uses the 'credential-store' table and 'alias/credstash' KMS key
    # ensure these are set up (credstash setup and KMS key creation)
    stash.putSecret(name=secret_name, secret=secret_value, version='1', kms_key='alias/credstash', kms_client=kms_client)
    print(f"Secret '{secret_name}' version 1 stored successfully.")

    # Get the secret
    retrieved_secret = stash.getSecret(name=secret_name, kms_client=kms_client)
    print(f"Retrieved secret '{secret_name}': {retrieved_secret}")

    # Update the secret with a new version (auto-increment example)
    stash.putSecret(name=secret_name, secret='new_supersecret_value', autoversion=True, kms_key='alias/credstash', kms_client=kms_client)
    print(f"Secret '{secret_name}' updated with new version.")
    updated_secret = stash.getSecret(name=secret_name, kms_client=kms_client)
    print(f"Retrieved updated secret '{secret_name}': {updated_secret}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you have configured AWS credentials and run `credstash setup` and created a KMS key 'alias/credstash'.")