SecureStore Python library

This repository/package houses a Python implementation of the cross-platform, language-agnostic SecureStore secrets specification. In particular, this library may be used for interacting with SecureStore secrets containers, providing an easy-to-use and idiomatic interface for loading SecureStore containers and decrypting/retrieving secrets from your frontend or backend application, interactively or with key-based decryption.

Usage

This python library is largely intended to be used alongside one of the SecureStore cli companion apps, used to create SecureStore values and manage (add/remove/update) the secrets stored therein. In this example, we'll be using the ssclient cli utility to create a new store.

Creating a secrets vault

Typical SecureStore usage begins by creating a new SecureStore "vault" (an encrypted secrets container) that will store the credentials (usually both usernames/access keys and passwords/api keys) that your app will need for one or more services. Begin by compiling or downloading and installing a copy of ssclient, the SecureStore companion cli.

While you can compile it yourself or manually download pre-built binaries for your platform, you might find it easiest to just install it with npm:

~> npm install --global @neosmart/ssclient

after which you can proceed with the following steps:

~> mkdir secure/
~> cd secure/
~> ssclient create --export-key secrets.key
Password: ************
Confirm Password: ************

# Now you can use `ssclient -p` with your password or
# `ssclient -k secrets.key` to get or set additional
# secrets using the same encryption/decryption key.

Adding secrets

Secrets may be added with your password or the equivalent encryption key file, and may be specified in-line as arguments to ssclient or more securely at a prompt by omitting the value when calling ssclient create:

# ssclient defaults to password-based decryption:
~> ssclient set aws:s3:accessId AKIAV4EXAMPLE7QWERT
Password: *********

similarly:

# Use `-k secrets.key` to load the encryption key and
# skip the prompt for the vault password:
~> ssclient -k secrets.key set aws:s3:accessKey
Value: v1Lp9X7mN2B5vR8zQ4tW1eY6uI0oP3aS5dF7gH9j

Retrieving secrets

Secrets can be retrieved at the commandline with ssclient or programmatically with a SecureStore library for your development language or framework of choice.

This library contains the python implementation of the SecureStore protocol. The SecureStore protocol was intentionally designed to maximize security and compatibility, and, as such, has minimal dependencies (only a dependency on cryptography and compatible with very old versions of python3).

This project has been uploaded to PyPi and can be installed with pip or your favorite modern alternative:

pip install securestore

after which you can use the library as follows:

from securestore import SecretsManager, KeySource

key = KeySource.from_file("secure/secrets.key")
sman = SecretsManager.from_file("secure/secrets.json", key)

# Retrieve and decrypt a specific secret
s3AccessId  = sman.get("aws:s3:accessId")
s3AccessKey = sman.get("aws:s3:accessKey")

# List all available keys in the vault
for key in sman.keys():
    print(f"* {key}")

Interactively decoding secrets

Normally you would use ssclient locally with password-based decryption to manage secrets in the secrets.json vault, then use key-based decryption to allow for securely decrypting the secrets at runtime without hardcoding any secrets, as shown above. But you can also use this library interactively (or otherwise) to decrypt a SecureStore vault using a password instead:

from securestore import SecretsManager

key = KeySource.from_password("MyPASsWOrd42")
sman = SecretsManager.from_file("secrets.json", key)

sman.get("aws:s3:accessId")
...

API overview

The SecureStore library provides a high-level interface for decrypting and accessing secrets stored in SecureStore v3 vaults.

The following types/classes/interfaces are exposed by this library:

SecretsManager

The primary class used to open vaults and retrieve secrets.

KeySource

An abstraction layer for authentication credentials. Use this to define how the vault should be unlocked.