Metadata-Version: 2.2
Name: vcrypto
Version: 4.0.1
Summary: Utility to easily store passwords/secrets
Author-email: Arnau Villoro <arnau@villoro.com>
Maintainer-email: Arnau Villoro <arnau@villoro.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=44.0.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: pytest>=8.3.4
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: ruff>=0.9.7

# Palette Material Design
Utility to easily store password/secrets. It uses `Fernet` from the [cryptography](https://cryptography.io/en/latest/) module instead of reinventing the wheel.

Fernet is a symmetric encryption that uses 128-bit AES in CBC mode and PKCS7 padding with HMAC using SHA256 for authentication. You can read more about it [here](https://medium.com/coinmonks/if-youre-struggling-picking-a-crypto-suite-fernet-may-be-the-answer-95196c0fec4b).

## Why vcrypto?
It is always annoying to deal with secrets and passwords in python especially if you work with other people. What we found that worked best for us was:

* Create one master private password (ignored from git)
* Have dict-like file with the rest of passwords encrypted

This module provides the class `Cipher` to handle that easily.

The idea behind this module is to be able to **create a `json` or `yaml` with encrypted secrets**. The keys will be public but the values won't. This way you can **store the dictionary of secrets in git** and easily share them with other people working in the same project. You will only need to **share the `master.password` once**. And all the other passwords/secrets will be tracked with git.

## Installation

You can install it with pip by running:

    pip install vcrypto

## Usage

```python
from vcrypto import Cipher

# Create a cipher instance
cipher = Cipher()

# Create a new master password
cipher.create_password()

# Store a secret
cipher.save_secret("secret", "I like python")

# Retrive a secret
cipher.get_secret("secret")
```

### Customization

There are three paramaters to customize the cipher:

1. **secrets_file:** path of the file with secrets. Can be a `json` or `yaml`.
2. **filename_master_password:** path of the file with the master password
3. **environ_var_name:** if passed it allows to read the master password from an environ var.

> For `yaml` you need to install `pyyaml`

For example you could do:

```python
cipher = Cipher(secrets_file="data/secrets.yaml", filename_master_password="data/master.secret")
```

This will allow you to store both the `master.password` and `secrets.yaml` in the folder `data`.

There is not much more customization since the idea is to keep it simple.

### Integrating it in other projects
We usually have one or more python files with utilities, for example `utilities.py`.

To use vcrypto we initiallize the `cipher` there and then create a `get_secret` dummy function that will call the cipher.

```python
from vcrypto import Cipher

cipher = Cipher(secrets_file="data/secrets.yaml", filename_master_password="data/master.secret")

def get_secret(key):
    return cipher.get_secret(key)
```

Then you can use it elsewhere with:

```python
import utilities as u

u.get_secret("secret")
```

## Development

This package relies on [poetry](https://villoro.com/post/poetry) and `pre-commit`. In order to develop you need to install both libraries with:

```sh
pip install poetry pre-commit
poetry install
pre-commit install
```

Then you need to add `poetry run` before any python shell command. For example:

```sh
# DO
poetry run python master.py

# don't do
python master.py
```

## Authors
* [Arnau Villoro](https://villoro.com)

## License
The content of this repository is licensed under a [MIT](https://opensource.org/licenses/MIT).
