Shh! 🤫

Shh! is a proof-of-concept aiming at dealing with secrets within your Symfony application.

Why?

I was just reading Storing secrets for Symfony applications from Matthias Pigulla which came with a solution using a Ruby-powered external program.

Then I came up with the following question: why isn't there a PHP implementation of this? 🤔

Here are the key principles:

• Storing secrets in environment variables will actually expose them through phpinfo(), reports, logs, and child processes.
• Thanks to Symfony's Env Var Processors, Shh will expose them encrypted. They will be decrypted at the very last moment.
• Private key + an optional passphrase are required to decrypt secrets. They SHOULD be .gitgnored.
• You can then commit encrypted secrets to VCS as long as the private key is stored and communicated safely.
• You can change your passphrase a at any time.

Installation

composer require bentools/shh-bundle:^1.0

Configuration

• Add the bundle to your kernel (come on, you're not using Flex?).
• Generate your keys:
  • Create a shh directory into your config directory mkdir -p config/shh (or mkdir -p app/config/shh for Symfony 3)
  • Runphp bin/console shh:generate:keys
  • If you provided one, store the passphrase in the SHH_PASSPHRASE environment variable
  • Add config/shh/private.pem (or app/config/shh/private.pem for Symfony 3) to your .gitignore and upload it to your production server.

And you're ready to go!

If you want a different configuration, check out the configuration reference to discover the available options.

Usage

Check the environment is properly configured

bin/console shh:check // Will check that encryption / decryption work - both private and public keys are needed.

bin/console shh:check --encrypt-only // Will check that encryption works - only public key is needed?

Encrypt a value (public key needed)

bin/console shh:encrypt

Decrypt a value (public key + private key needed)

bin/console shh:decrypt

Decrypt secrets in environment variables

This library ships with an environment variable processor. You can use it like this:

# config/services.yaml
parameters:
    some_secret_thing: '%env(shh:SOME_ENCRYPTED_SECRET)%'

Working with a secrets file

You can store your encrypted secrets in a .secrets.json file at the root of your project directory (you can set a different path in the SHH_SECRETS_FILE environment variable).

This file can safely be committed to VCS (as soon as the private key isn't).

To encrypt and register a secret in this file, run the following command:

bin/console shh:register:secret my_secret # You will be prompted for the value of "my_secret"

You can then use your secrets in your configuration files in the following way:

# config/services.yaml
parameters:
    my_secret: '%env(shh:key:my_secret:json:file:SHH_SECRETS_FILE)%'

Changing passphrase

You can change your passphrase if needed: this will result in a new private key being generated. The public key remains unchanged.

bin/console shh:change:passphrase

As a result, a new private key will be regenerated. You just have to update it everywhere it is used, and update the SHH_PASSPHRASE environment variable as well.

You may do this every time an employee leaves the company, for instance.

Configuration reference

# config/packages/shh.yaml
parameters:
    env(SHH_SECRETS_FILE): '%kernel.project_dir%/.secrets.json'

shh:
    private_key_file:     '%kernel.project_dir%/config/shh/private.pem'
    public_key_file:      '%kernel.project_dir%/config/shh/public.pem'
    passphrase:           '%env(SHH_PASSPHRASE)%'

Tests

./vendor/bin/phpunit

Feedback

Don't hesitate to ping me on Symfony Slack: @bpolaszek.

License

MIT