Metadata-Version: 2.4
Name: securestore
Version: 0.1.2
Summary: Python library for decrypting SecureStore secrets
Keywords: secrets,encryption,tooling
Author-email: Mahmoud Al-Qudsi <mqudsi@neosmart.net>
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-Expression: MIT OR Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: cryptography>=3.1
Project-URL: Funding, https://mqudsi.com/donate/
Project-URL: Homepage, https://neosmart.net/SecureStore/
Project-URL: Repository, https://github.com/neosmart/securestore-py.git

[![PyPI - Version](https://img.shields.io/pypi/v/securestore)](https://pypi.org/project/securestore/) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/securestore) ![PyPI - Types](https://img.shields.io/pypi/types/securestore)

# SecureStore Python library

This repository/package houses a Python implementation of the cross-platform, language-agnostic [SecureStore secrets specification](https://neosmart.net/SecureStore). In particular, this library may be used for interacting with [SecureStore](https://github.com/neosmart/securestore-rs) 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`](https://github.com/neosmart/securestore-rs/tree/master/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`](https://github.com/neosmart/securestore-rs/tree/master/ssclient), the SecureStore companion cli.

While you can compile it yourself or manually download [pre-built binaries for your platform](https://github.com/neosmart/securestore-rs/releases), you might find it easiest to just install it with `npm`:

```bash
~> npm install --global @neosmart/ssclient
```

after which you can proceed with the following steps:

```bash
~> 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`:

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

similarly:

```bash
# 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`](https://github.com/neosmart/securestore-rs/tree/master/ssclient) or programmatically with a SecureStore library [for your development language or framework of choice](https://neosmart.net/SecureStore).

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:

```sh
pip install securestore
```

after which you can use the library as follows:

```python
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:

```python
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.

| Method | Description |
| :--- | :--- |
| `from_file(path, key_source)` | **Static.** Opens a vault from a file on disk using a `KeySource`. |
| `from_json(json_str, key_source)` | **Static.** Opens a vault from the contents of the SecureStore vault as (string or bytes). |
| `from_dict(data, key_source)` | **Static.** Opens a vault from a pre-parsed dictionary. |
| `get(name)` | Retrieves and decrypts the secret associated with `name`. Returns `None` if the key does not exist. |
| `keys()` | Returns a list of all secret names (keys) available in the vault. |

---

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

| Method | Description |
| :--- | :--- |
| `from_password(password)` | **Static.** For decrypting the vault with a password string. |
| `from_file(path)` | **Static.** Loads a decryption key from a file (supports raw binary or ASCII-armored keys). |
| `from_key(key)` | **Static.** Creates a key source from the *contents* of a key (supports `bytes`, `str`, or `list` of integers). |

