← docs

Security Overview

Written by Mot

Security is an evermoving target - an arms race. But that doesn't mean it should be hard to use. Good design can make complex things simple, and that is what we are after with dotenv and dotenv-vault.

dotenv is a security tool. It has been since it was first developed in 2013. We saw developers struggling to keep their secrets safe so we pioneered the .env file format standard. The design led to better DSX - which led to safer secrets for millions of developers. Today, we are taking that to the next logical step.

What is the problem with .env files today? The world has changed. Developers manage secrets at far greater scale than a decade ago. .env files are not easily shareable between machines, environments, and team members. As a result, developers often share secrets over Slack, email, text message, and post-it notes. It's not scaleable and fraught with security risks. For a CTO or CSO it is a risk they should not take.

So, today, we are extending the .env file format to support syncing across machines, environments, and team members. It's an exciting development and we welcome you to go on this journey with us.

We are designing a handful of extensions and services on top of the .env file format to make this happen. They are:

.envfile Trusted and proven file format for securing development secrets
.env.vaultidentifier Uniquely identifies your project on dotenv-vault
.env.mecredential Uniquely authorizes you to access a project's shared .env file
dotenv-vault Sync environment variables, securely.
How dotenv-vault works.

Step 1

npx dotenv-vault push

You run npx dotenv-vault push. The request is started.

Step 2

Encrypted Connection

The .env file is encrypted and sent securely over SSL to Dotenv's in-memory servers.

Step 3

Dotenv Servers

This encrypted payload is decrypted and briefly held in memory to complete the next steps. Afterward, the memory is flushed. Rest assured the decrypted version is never peristed to Dotenv systems.

Step 4

Parsing

The .env file is parsed line by line - in memory.

Note: There are some differences between dotenv parsers across various languages and frameworks. So far Dotenv Vault handles these 100%, and we continue to add test cases to cover all edge cases.

KEY=VALUE

Step 5

Secret Extraction

Each key/value pair (and any comments) are extracted - in memory.

KEY=VALUE
KEY VALUE

Step 6

Secret Division

The secret is divided into its separate key and value. This is by design. They will be stored in separate databases for added security. This way if an attacker somehow gained access to one database they would not be able to make sense of the data - having only half of the puzzle.

KEYkey_b46…
VALUEval_a8e…

Step 7

EncryptionAES-GCM Algorithm

The KEY is encrypted. The VALUE is encrypted. They are encrypted with different master encryption keys. This way if an attacker somehow gained access to the VALUE decryption key they would find the data useless. They would not know if the secret belonged to Twilio or to AWS.


Encryption uses the AES-GCM algorithm. It is:

Additionally, all master encryption keys are rotated on an unpublished schedule, further adding to the level of security.

val_a8e…

Dotenv Vault Store

token_fd4b…

Step 8

TokenizationVALUE

The encrypted VALUE is sent to Dotenv Vault for safe storage. A token is returned as an identifier. The token is used in the next step for mapping the KEY to the VALUE for later secure-read operations.


Multiple security measures go into the Vault. They include but are not limited to:

  • Separate datastore from the application database
  • Not accessible via the internet and all external connections are prevented
  • Encrypted clients are required and these clients have to go through the application - which has its own additional layers of encryption
  • There are stricter TLS requirements for connecting to the Vault. TLS 1.0 cannot be used to connect.
  • The secrets stored in the Vault are not just encrypted at the datastore level. They are also encrypted at each datastore entry as you saw in the prior step(s).
key_b46… token_fd4b…

Dotenv Application Database

Step 9

Store Key Part with Token

Lastly, the encrypted KEY and token (representing the encrypted VALUE) are placed in an envelope and stored together in the application database.

Step 10

Success 201

A success message is returned to the user.

And this is just the start. There are also integrations into 3rd party services like AWS Secrets, AWS Parameter Store, Vercel, Netlify, Slack, Heroku, GitHub, and more - as well as plans to allow you to 'bring your own vault'™.

It is going to be an exciting journey. Thank you for using dotenv and dotenv-vault.


Learn more about security for dotenv-vault.