Skip to main content
Join the official 2020 Python Developers SurveyStart the survey!

A simple on-disk secure stash for secrets

Project description

# Python Secure Stash

A simple on-disk secure stash for secrets, written in python.
Requires python >= 3 to work.

**This is a new project. Use with caution.**

# Basic API Usage

>>> from sstash.sstash import SecureStash

>>> ss = SecureStash('my_stash','my_password1234')

>>> ss.write_value(['project','SomeService','token1'],b'622324c09486bf30ed3a9213954a35c34de84535')

>>> ss.read_value(['project','SomeService','token1'])

>>> ss.write_value(['project','SomeService','token2'],b'2435e188b48f4d1778279f1ae764fa5c1d272a03')

>>> ss.read_value(['project','SomeService','token2'])

>>> ss.remove_key(['project','SomeService','token1'])

>>> ss.read_value(['project','SomeService','token1'])
sstash.exceptions.SSKeyError: Key ['project', 'SomeService', 'token1'] was not found in store.


# Installation

First make sure you have those packages:

apt install libffi-dev python3-dev

Then install from Pypi:

pip install sstash

# Tutorial

secure_stash allows you to encrypt your secrets on disk using a simple python
API. A secure_stash is a single file on disk.

To keep the data inside the data store hidden from other people, we
encrypt it using a password.

To create a new stash file, we run a python line of this form:

ss = SecureStash('my_stash','my_password1234')

If my_stash has never existed before, this line will create a new stash file
called my_stash. It will be empty, and it will be encrypted using the password
'my_password1234'. If the stash my_stash already exists, it will be opened.

The secure stash is built as a tree based data store.

For example, If you store the bytes b'hello' in the key ['a','b','c'], and the
bytes b'bye' in the key ['a','b','d'], you will get the following tree inside
the data store:


|--'c' : b'hello'
|--'d' : b'bye'

If you then store the bytes b'chocolate' inside the key ['a','e'], you will get
the following tree:


| |--'c' : b'hello'
| |--'d' : b'bye'
|--'e': b'chocolate'

If we then remove the key ['a','b','c'] we will get the following tree:


| |--'d' : b'bye'
|--'e': b'chocolate'

# Cryptography used

secure_stash is based on well known cryptography primitives. For key derivation
(Creating a key from the given user password) it uses pbkdf2 (Python's standard
The random for the salt for the password is taken from os.urandom.

PyNaCl's Secret Key Encryption is used for encrypting the data store. PyNaCl
uses Secret Key Encryption uses Salsa20 steam cipher for encryption and
Poly1305 MAC for authentication.

All of the cryptography code can be found inside the file

# Tests

Proudly tested by py.test.
To run the tests (Make sure that you are at the root directory first):

py.test sstash

## Exceptions:

All the exceptions can be imported from


The base exception is sstash.exceptions.SSError.
Other exceptions are:

- sstash.exceptions.SSKeyError
- sstash.exceptions.SSValueError
- sstash.exceptions.SSCryptoError

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sstash, version 0.17
Filename, size File type Python version Upload date Hashes
Filename, size sstash-0.17.tar.gz (6.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page