If you've ever worked with .env files, you know the problem: they contain your most sensitive credentials—database passwords, API keys, secret tokens—all sitting in plain text. One accidental commit to GitHub, one insecure share, and you're potentially exposing your entire application's secrets to the world.
I came across this issue repeatedly in developer discussions online, and it frustrated me that there wasn't a simple, educational solution that developers could understand, modify, and adapt to their needs. So I built one from scratch.
The Problem with Plain Text Configuration
Environment files are inherently insecure. They're designed for convenience, not security. When you store credentials in plain text:
- Accidentally committing them to version control exposes everything
- Sharing configuration across teams means sharing raw secrets
- There's no protection against tampering or unauthorized access
- No encryption means anyone with file access has complete credential access
The common advice? "Just don't commit your .env files." But that doesn't solve the real problem—it just avoids it.
A Different Approach: Encrypted Environment Files
I designed a custom encryption tool that transforms plain text environment files into encrypted .compiled files. These files can be safely committed to version control, shared across teams, and distributed without fear—they're completely useless without the encryption key.
The core design:
- Encrypt configuration files using ChaCha20-Poly1305 AEAD
- Derive keys from passwords using PBKDF2-HMAC-SHA256 with 300,000 iterations
- Verify integrity using BLAKE2s with constant-time comparison
- Create self-contained binary files that resist tampering
You can find the complete implementation here: Custom-Env-Setup on GitHub
How It Works
The encryption process is straightforward:
# Encrypt your .env file
python cli.py -k mySecretKey -f .env
This reads your environment file, converts it to JSON, generates a random nonce, derives an encryption key using PBKDF2, encrypts everything with ChaCha20-Poly1305, and creates a .compiled file with integrity verification.
Loading the encrypted variables in your application is just as simple:
from main import Getter
# Load encrypted environment
env_loader = Getter('.env.compiled', 'mySecretKey')
if env_loader.env:
database_url = env_loader.env.get('DATABASE_URL')
api_key = env_loader.env.get('API_KEY')
You can integrate this into your applications with command-line arguments, interactive prompts, or even auto-load variables directly into os.environ.
Why These Specific Algorithms?
I chose each component deliberately:
ChaCha20-Poly1305 is fast on any device—from servers to embedded systems—and provides authenticated encryption. This means both confidentiality and integrity protection in a single operation.
PBKDF2-HMAC-SHA256 with 300,000 iterations makes brute-force attacks computationally expensive. Even if someone has your encrypted file, cracking it without the key becomes practically infeasible.
BLAKE2s is incredibly fast for integrity verification while maintaining cryptographic strength. The constant-time comparison prevents timing attacks.
The Honest Truth: This is a Proof of Concept
I need to be clear about something important: this is not production-grade by default. This is an intentional choice, not an oversight.
The tool is designed as an educational proof-of-concept to demonstrate secure environment encryption patterns. It has intentional simplifications:
No versioning: Production systems need version identifiers to support algorithm upgrades and backward compatibility. I omitted this to keep the implementation focused on the core encryption pattern.
Nonce-as-salt: The implementation uses the encryption nonce as the PBKDF2 salt. This ensures the same password produces different keys for different encryptions, but highest-security standards would typically use an independent random salt.
Why these simplifications? Because the main goal isn't to provide a turnkey production system—it's to introduce the design pattern in a way developers can understand, learn from, and modify. The code is clear, readable, and extensible.
Is It Secure?
Yes—for its intended purpose. It uses industry-standard algorithms and protects your data effectively. It's more than adequate for development environments, learning projects, and custom security workflows.
But it doesn't meet every cryptographic requirement for the absolute highest possible safety standards used in critical production systems. That's by design. You can enhance it by:
- Adding file format versioning
- Using independent salts
- Implementing key rotation mechanisms
- Adding HSM support for key management
- Increasing PBKDF2 iterations further
The implementation is built to be modified. That's the point.
Flexible Licensing for Real-World Use
The tool is licensed under GPL v3 with a special exception:
- Using it as a component in your app? Use it under any license you want.
- Building a new environment encryption tool based on this? Must be GPL v3.
- Creating a library specifically for env encryption? Must be GPL v3.
This lets developers integrate the functionality into their projects without viral GPL requirements, while ensuring improvements to the core encryption tool remain open source.
Building It From Scratch
The entire implementation is built on OpenSSL, with a custom C library for the ChaCha20-Poly1305 operations and Python wrappers for easy integration. The Windows crypto.dll is pre-compiled with OpenSSL 3.6 statically linked—no external dependencies needed.
For Linux or macOS, you can compile it yourself with either static linking (self-contained like the Windows version) or dynamic linking (requires system OpenSSL). The repository includes complete compilation instructions for all platforms.
Who Is This For?
This tool is for developers who:
- Want to understand how environment encryption works
- Need a simple solution for development environments
- Want a starting point to build their own secure configuration system
- Value learning and customization over black-box solutions
It's not for developers who:
- Need a turnkey production-grade system without modifications
- Don't want to understand the cryptographic decisions being made
- Require enterprise-level key management integration out of the box
Try It Yourself
The complete source code, documentation, and compilation instructions are available on GitHub:
https://github.com/hejhdiss/Custom-Env-Setup
Clone it, try it, modify it. Break it and fix it. That's how you learn.
I built this because I saw a problem that many developers face and wanted to share my solution. It's not perfect—it's not meant to be. It's meant to be educational, modifiable, and useful.
If you find it helpful, star the repository. If you find ways to improve it, contributions are welcome. And if you use it in your projects, I'd love to hear about it.
Top comments (0)