bentools / shh-bundle
A Symfony bundle to handle secrets.
Installs: 11 823
Dependents: 0
Suggesters: 1
Security: 0
Stars: 2
Watchers: 4
Forks: 0
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.0
- bentools/shh: ~1.0
- symfony/config: ~5.4|~6.0
- symfony/console: ~5.4|~6.0
- symfony/dependency-injection: ~5.4|~6.0
- symfony/filesystem: ~5.4|~6.0
- symfony/http-kernel: ~5.4|~6.0
Requires (Dev)
- bentools/cartesian-product: ^1.3
- nyholm/symfony-bundle-test: ^1.4
- php-coveralls/php-coveralls: ^2.1
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ~7.0|~8.0
- squizlabs/php_codesniffer: ~3.7
- symfony/framework-bundle: ~5.4|~6.0
- symfony/var-dumper: ~5.4|~6.0
- thecodingmachine/safe: ^1.0
This package is auto-updated.
Last update: 2024-11-04 10:30:50 UTC
README
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 directorymkdir -p config/shh
(ormkdir -p app/config/shh
for Symfony 3) - Run
php bin/console shh:generate:keys
- If you provided one, store the passphrase in the
SHH_PASSPHRASE
environment variable - Add
config/shh/private.pem
(orapp/config/shh/private.pem
for Symfony 3) to your.gitignore
and upload it to your production server.
- Create a
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