vcrypto - Secure Secrets Management in Python

vcrypto is a simple and effective utility for securely storing passwords and secrets in Python. It leverages Fernet encryption from the cryptography module instead of reinventing the wheel.

🔒 Why vcrypto?

Managing secrets in Python, especially in collaborative projects, can be cumbersome. Our approach simplifies it:

👉 One master private password (ignored in Git)
👉 A structured dictionary file with encrypted secrets
👉 Easily shareable - only the master password needs to be exchanged once
👉 Version-controlled secrets - since only encrypted values are stored

This package makes it easy to store and retrieve encrypted secrets in JSON or YAML formats.

📌 Features

• 🔐 AES-128 Encryption (Fernet) for secure storage.
• 📂 JSON/YAML Support for structured secret storage.
• 🛠️ Environment Variable Support for flexible key management.
• 🔑 Simple API for saving and retrieving secrets.

📝 Installation

Install via pip:

pip install vcrypto

🚀 Quickstart

1️⃣ Initialize vcrypto

Before using vcrypto, initialize it with:

from vcrypto import init_vcrypto

init_vcrypto(secrets_file="secrets.yaml", environ_var_name="MY_ENV_VAR")

[!TIP] You only need to initialize it once.

This ensures vcrypto knows where to store secrets and how to retrieve the master password.

2️⃣ Store and Retrieve Secrets

Save a Secret

from vcrypto import save_secret

save_secret("SECRET_TOKEN", "super_secret_value")

Retrieve a Secret

from vcrypto import read_secret

token = read_secret("SECRET_TOKEN")
print(token)  # Output: super_secret_value

⚙️ Customization

The init_vcrypto function allows customization:

Example:

init_vcrypto(secrets_file="config/secrets.yaml", filename_master_password="config/master.password")

This setup stores both the master.password and secrets.yaml in the config/ folder.

[!CAUTION] The master password file must never be committed. The bundled .gitignore only excludes *.password, so if you choose a custom name make sure it is covered by your .gitignore. Committing the master password alongside the encrypted secrets.yaml defeats the entire scheme.

🛠️ Development

This project uses uv for dependency management.

Install dependencies

pip install uv
uv venv
uv install

💜 License

This project is licensed under the MIT License.

👤 Author

• Arnau Villoro