ixnode/php-vault

Secure PHP Vault

v1.3.0 2022-01-04 23:17 UTC

Requires

• php: ^7.4 || ^8.0
• ext-json: *
• ext-sodium: *
• adhocore/cli: ^0.9.0

Requires (Dev)

• phpstan/phpstan: ^0.12.83
• phpunit/phpunit: ^9

MIT

• Björn Hempel

• security
• cryptography
• encryption
• deployment
• environment
• decryption
• continuous delivery
• env
• dotenv
• vault
• cicd

README

PHPVault is a PHP library that can create, read, encrypt and decrypt environment files (so-called dotenv files). For example is .env a plain file, .env.enc an encrypted file, etc. Within your project you can automatically load these encrypted environment variables from .env.enc into getenv(), $_ENV and $_SERVER. The corresponding key-value pairs within these dotenv files are encrypted and decrypted using an asymmetric encryption method (Public-key cryptography). Private keys are only available on productive systems for decrypting dotenv values. The public key, on the other hand, can be safely checked into the repository and is used everywhere to encrypt new values.

The strict separation of configuration and code is a fundamental principle of software development and is based on the The Twelve-Factor App methodology. One way to do this is to store these data into separate configuration files such as the dotenv files mentioned above. These are mostly unencrypted, but usually contain very sensitive data such as database access and API keys. They must therefore never be checked into the code repository! Since these are usually files within the project, there is still a risk that this could happen by mistake.

The PHPVault approach preserves the principle of separation and goes one step further: It encrypts plain dotenv files and allows them to be checked into the code repository. To decrypt and use the data on a productive system, simply exchange the private key. This approach is great for providing secure and automated deployment processes (CI/CD, etc.).

To start simply run:

$ composer require ixnode/php-vault

This requires Composer, a dependency manager for PHP.

Command line command vendor/bin/php-vault

The basis of all operations is the command line tool vendor/bin/php-vault. Help can be displayed at any time:

$ vendor/bin/php-vault --help
PHPVault command line interpreter.
PHPVault, version v1.0.7

Commands:
  decrypt-file  df    Decrypts a given file. Requires a private key.
  display       d     Displays the environment variables from given file.
  display-env   de    Displays the environment variables from server.
  encrypt-file  ef    Encrypts a given file. Requires a public key.
  generate-keys gk    Generates and displays a private and public key.
  info          i     Shows information.
  set           s     Sets or updates a new variable. Needs a public key.

Run `<command> --help` for specific help

$ vendor/bin/php-vault --version
v1.0.7

On development system

Usually, you need the public key in this environment. Examples can be found below. There are several ways to pass the public key to the php-vault interpreter. In the following, the key is loaded from the .keys directory (--public-key).

Generate keys

$ vendor/bin/php-vault generate-keys --persist

The key pair is written to folder ".keys"

Never add the private key to the repository!

• Attention!:
  • Keep the private key safe for the productive systems (.keys/private.key).
    • Delete the private key file .keys/private.key if you have saved it and submitted it to the admin for the productive system.
  • Use the public key on development and local systems (.keys/public.key).

Create environment file

• Add key-value pair DB_USER=secret.user with description "DB Configs"
• Add key-value pair DB_PASS=secret.pass
• Add key-value pair DB_HOST=secret.host
• Add key-value pair DB_NAME=secret.name
• Use public key (--public-key → read from .keys/public.key).

# Create file .env.enc
$ vendor/bin/php-vault set .env.enc DB_USER secret.user "DB Configs" --public-key --create
# Adds values to .env.enc
$ vendor/bin/php-vault set .env.enc DB_PASS secret.pass --public-key
$ vendor/bin/php-vault set .env.enc DB_HOST secret.host --public-key
$ vendor/bin/php-vault set .env.enc DB_NAME secret.name --public-key

Display the environment file

• The contents displayed are encrypted.
• Do not need any key.

$ vendor/bin/php-vault display .env.enc --load-encrypted
...

On production system

Usually, you need the private key in this environment. Examples can be found below. There are several ways to pass the private key to the php-vault interpreter. In the following, the key is loaded from the .keys directory (--private-key).

Display an encrypted file

• Use private key (--private-key → read from .keys/private.key).

$ vendor/bin/php-vault display .env.enc --load-encrypted --display-decrypted --private-key
+---------+-------------+-------------+
| Key     | Value       | Description |
+---------+-------------+-------------+
| DB_USER | secret.user | DB Configs  |
| DB_PASS | secret.pass |             |
| DB_HOST | secret.host |             |
| DB_NAME | secret.name |             |
+---------+-------------+-------------+

Decrypt an encrypted file

• Never add the produced decrypted file .env to the repository!
• Use private key (--private-key → load from .keys/private.key).

$ vendor/bin/php-vault decrypt-file .env.enc --private-key

The file was successfully written to ".env".

Display the decrypted file without encryption

• Do not need any key.

$ vendor/bin/php-vault display .env --display-decrypted
+---------+-------------+-------------+
| Key     | Value       | Description |
+---------+-------------+-------------+
| DB_USER | secret.user | DB Configs  |
| DB_PASS | secret.pass |             |
| DB_HOST | secret.host |             |
| DB_NAME | secret.name |             |
+---------+-------------+-------------+

Using the PHPVault class

Load the private key from a given file

<?php

require 'vendor/autoload.php';

use Ixnode\PhpVault\PHPVault;

/* Path to private key and .env.enc */
$pathToPrivateKey = __DIR__.'/.keys/private.key';
$pathToEncryptedEnv = __DIR__.'/.env.enc';

/* - Initiate PHPVault Core.
 * - Load private key.
 * - Load the encrypted env file.
 */
$phpVault = new PHPVault();
$phpVault->loadPrivateKeyFromFile($pathToPrivateKey);
$phpVault->importEncryptedEnvFile($pathToEncryptedEnv);

/* Usage */
$dbUser = getenv('PHPVAULT_DB_USER');
$dbPass = getenv('PHPVAULT_DB_PASS');
$dbHost = getenv('PHPVAULT_DB_HOST');
$dbName = getenv('PHPVAULT_DB_NAME');

Load the private key from the server environment variable PRIVATE_KEY

For options to set the environment variable, see here.

<?php

require 'vendor/autoload.php';

use Ixnode\PhpVault\PHPVault;

/* Path to private key and .env.enc */
$pathToEncryptedEnv = __DIR__.'/.env.enc';

/* - Initiate PHPVault Core and use the PRIVATE_KEY environment variable.
 * - Load the encrypted env file.
 */
$phpVault = new PHPVault();
$phpVault->importEncryptedEnvFile($pathToEncryptedEnv);

/* Usage */
$dbUser = getenv('PHPVAULT_DB_USER');
$dbPass = getenv('PHPVAULT_DB_PASS');
$dbHost = getenv('PHPVAULT_DB_HOST');
$dbName = getenv('PHPVAULT_DB_NAME');

Run tests

The part is only available if the project is checked out directly for development:

$ git clone https://github.com/ixnode/php-vault.git && cd php-vault
$ composer install

PHPUnit tests

$ composer run tests
> phpunit tests
PHPUnit 9.5.4 by Sebastian Bergmann and contributors.

...............................................................  63 / 154 ( 40%)
............................................................... 126 / 154 ( 81%)
............................                                    154 / 154 (100%)

Time: 00:00.136, Memory: 8.00 MB

OK (154 tests, 274 assertions)

Static code analysis (PHPStan)

$ composer run analyse
> phpstan analyse src --level max --no-progress

 [OK] No errors

> phpstan analyse tests --level max --no-progress

 [OK] No errors

Continuous integration

Runs @analyse and @tests:

$ composer run ci

Security

If you discover a security vulnerability within this package, please send an email to Björn Hempel at [e-mail]. All security vulnerabilities will be promptly addressed. You may view our full security policy here.

License

PHPVault is licensed under MIT.