README

This package helps you manage .env files for different deployment environments. Each .env file is securely encrypted and kept in your app's version control. When you deploy your app the appropriate environment-specific .env file is decrypted and moved into place.

This was partly inspired by Marcel's excellent credentials package. If you want to manage your credentials in a json file, with Laravel handling the encryption/decryption, and only have one deployment environment, that package may be a better fit for your needs.

Our package is different in the following ways:

We wanted to work with .env files directly and have the decrypted .env file end up where Laravel already expects it. The app makes use of the .env variables just like it normally would.
We need to manage .env files for multiple environments (like qa, uat, production). This package allows you to manage any number of environment-specific .env files.
We wanted to leverage services like AWS Key Management Service to handle encryption/decryption, with the option to add other encryption drivers (like ansible) or secrets management services (like AWS Secrets Manager) in the future.

Note

Laravel v9.32.0 introduced new env:encrypt and env:decrypt commands, which conflicted with the commands in this package. We have moved our commands in v2 to env:store and env:fetch.

Installation and Setup

Prerequisites

If you intend to enable compression you must have the Zlib Compression Extension installed and enabled.

Install the package

composer require stechstudio/laravel-env-security

Add the composer hook

In your composer.json file add php artisan env:fetch as a post-install hook. You likely already have a post-install-cmd section, add the new command so it looks like this:

"scripts": {
        "post-install-cmd": [
            ...
            "php artisan env:fetch"
        ]

Generate configuration (optional)

Default configuration is based on environment variables (e.g. driver, store env, destination file, aws, gcp). If you need to customize it you can publish the config by running:

php artisan vendor:publish --provider="STS\EnvSecurity\EnvSecurityServiceProvider" --tag="config"

Setup service provider (older versions of Laravel)

If you are using a version of Laravel earlier than 5.5, you will need to manually add the service provider to your config/app.php file:

'providers' => [
    ...
    STS\EnvSecurity\EnvSecurityServiceProvider::class,
]

Configuration Settings

Configuration Key	Environment Variable	Default	Description
`env-security.default`	ENV_DRIVER	`kms`	The default driver.
`env-security.editor`	EDITOR	`vi`	Preferred text editor.
`env-security.store`	ENV_STORAGE_PATH	`env`	The directory where should we keep the encrypted .env files
`env-security.destination`	ENV_DESTINATION_FILE	`.env`	This is where we will put the decrypted .env file
`env-security.enable_compression`	ENV_COMPRESSION	`false`	Should data be compressed prior to encrypting it?
`env-security.divers.kms.key_id`	AWS_KMS_KEY	`null`	An AWS Key ID or Alias
`env-security.drivers.kms.region`	AWS_KMS_REGION	`null`	An AWS Region the key is in.
`env-security.drivers.google_kms.project`	GOOGLE_KMS_PROJECT, GOOGLE_CLOUD_PROJECT	`null`, `null`	A Google CLoud Project Identifier
`env-security.drivers.google_kms.location`	GOOGLE_KMS_LOCATION	`global`	A Google Cloud KMS Location
`env-security.drivers.google_kms.key_ring`	GOOGLE_KMS_KEY_RING	`null`	A Google Cloud KMS Key Ring
`env-security.drivers.google_kms.key_id`	GOOGLE_KMS_KEY	`null`	A Google CLoud KMS Key

Environment resolutionss

In order for this package to decrypt the correct .env file when you deploy, you need to tell it how to figure out the environment.

By default it will look for a APP_ENV environment variable. However you can provide your own custom resolver with a callback function. Put this in your AppServiceProvider's boot method:

\EnvSecurity::resolveEnvironmentUsing(function() {
    // return the environment name
});

This way you can resolve out the environment based on hostname, an EC2 instance tag, etc. This will then decrypt the correct .env file based on the environment name you return.

Key name resolution

Normally we expect your key name to be specified in the .env file. However you may want to specify different keys depending on the environment. If you have, say, different restricted AWS IAM credentials setup for your environments, this would allow you to ensure each .env file can only be decrypted in the appropriate environment.

Of course your own local IAM credentials would still need full access to all keys, so that you can edit each .env file locally.

To resolve the key name, provide a callback function like this:

\EnvSecurity::resolveKeyUsing(function($environment) {
    return "myapp-$environment";
});

Notice that your resolver will receive the already-resolved environment name, so you can use this to help figure out which key name to return.

Drivers

AWS Key Management Service

AWS KMS is a managed service that makes it easy for you to create and control the encryption keys used to encrypt your data, and uses FIPS 140-2 validated hardware security modules to protect the security of your keys.

To use this driver set ENV_DRIVER=kms in your .env file.

In the AWS Console create your encryption key. Make sure your AWS IAM user has kms:Encrypt and kms:Decrypt permissions on this key.

Copy the Key ID and store it as AWS_KMS_KEY in your local .env file. As you setup environment-specific .env files, make sure to include this AWS_KMS_KEY in each .env file.

Google Cloud Key Management Service

Google KMS securely manages encryption keys and secrets on Google Cloud Platform. The Google KMS integration with Google HSM makes it simple to create a key protected by a FIPS 140-2 Level 3 device.

To use this driver set ENV_DRIVER=google_kms in your .env file.

In the Google Cloud Console create your key ring and key. Make sure your Google IAM user has the Cloud KMS CryptoKey Encrypter/Decrypter role for this key.

Copy the Project, Key Ring and Key storing them as GOOGLE_KMS_PROJECT, GOOGLE_KMS_KEY_RING and GOOGLE_KMS_KEY in your local .env file. As you setup environment-specific .env files, make sure to include these keys in each .env file.

Usage

Create/edit a .env file

Run php artisan env:edit [name] where [name] is the environment you wish to create or edit. This will open the file in vi for you to edit. Modify something in the file, save, and quit.

Use the EDITOR environment variable to set your preferred editor.

Decrypt your .env

Now you can run php artisan env:fetch [name] which will decrypt the ciphertext file you edited, and write the plaintext to your .env, replacing anything that was in it. Now if you look at your .env you should see your edit.

If no environment [name] is provided, the environment will be determined by your own custom resolution callback or the APP_ENV environment variable.

Encrypt and save your current .env

Sometimes you may want to take your current .env file and encrypt exactly as-is.

Run php artisan env:store [name] to do this, where name is the name of the encrypted environment file you wish to create. If you don't provide a name, your current APP_ENV environment name will be used.

First deploy

As you're reading through this, you're probably wondering how that first initial deploy is going to work. In order for this package to decrypt your .env config where all your sensitive credentials are stored, it needs account credentials with permission to your KMS key.

Yep, it's turtles all the way down.

There are a number of ways to handle this, all dependent on the environment and deployment process.

If you are using AWS EC2, you can assign IAM roles to grant the instance access to your KMS key.
For AWS, you can always put a ~/.aws/credentials file on the server to provide necessary AWS permissions, regardless of your host.
For GCP your project ID and credentials are discovered automatically.
Many deployment services like Laravel Forge or Laravel Envoyer provide ways to specify environment variables which you can use to provide credentials.
And of course, you can always just ssh in manually to a fresh new server and put the necessary environment variables in a temporary .env file as well, which will get overwritten on the first deploy.

stechstudio / laravel-env-security

Maintainers

Details