benjaminstout/php-crypt

Barebones Cryptography Library for PHP – libsodium (NaCl), OpenSSL, Mcrypt, and more

v1.0 2019-04-24 18:48 UTC

Requires

• php: >=5.6.0
• paragonie/random_compat: >=2
• paragonie/sodium_compat: 1.x

Requires (Dev)

• phpunit/phpunit: ^5.2
• squizlabs/php_codesniffer: 3.*

MIT

• Benjamin Stout

README

A standalone, extensible, lightweight cryptography interface for PHP. With support for: libsodium (NaCl), OpenSSL, Mcrypt, and more.

PHP-Crypt allows you to quickly integrate a suite of modern cryptographic libraries into your PHP application, without the hassle of implementing advanced custom cryptographic methods by hand. PHP-Crypt prevents common cryptographic pitfalls, while providing the flexibility to choose between a suite of the latest cryptography libraries available for PHP. Usage is straightforward and highly extensible – comprised only of the minimum complexity necessary to ensure optimal security. PHP-Crypt makes swapping or integrating new cryptography libraries a breeze!

• PHP-Crypt features authenticated encryption straight out of the box (with Sodium or OpenSSL)

• PHP-Crypt is easily extensible – just drop an implementation of your favorite cryptography library into src/lib, and call new Crypt('<yourClass>') when instantiating PHP-Crypt. It couldn't be easier! While you're at it, submit a PR!

Prerequisites

• PHP >= 5.6
• If on PHP < 7.2, install libsodium and the sodium PHP extension to enable full support for the Sodium library.
• If on PHP >= 7.2, install the Mcrypt PHP extension through PECL to enable support for Mcrypt. Note: production usage of Mcrypt is highly discouraged, and should only be used for backwards compatability.
• Composer

Installation

PHP-Crypt supports installation in your PHP app through either composer or git submodule.

Composer: composer require benjaminstout/php-crypt
Git: git add submodule [e-mail]:stoutput/php-crypt.git <path/to/folder> && composer update -d <path/to/folder>

use BenjaminStout\PHPCrypt\Crypt;
require_once '<path/to/folder>/src/Crypt.php';

Getting Started

Instantiate a new instance of PHP-Crypt:

$this->Crypt = new Crypt('<library>', '<key>');

Where:
<library> is the cryptography library to use (Sodium [default], Openssl, Mcrypt, ...)
<key> is an optional key string to use for encryption. It must adhere to library's key requirements.

Encrypt a string:

$this->Crypt->encrypt('string');

Decrypt ciphertext:

$this->Crypt->decrypt('eNcRyPtEd');

Encryption Keys

If the encryption key is left unspecified during instantiation, PHP-Crypt will look for an existing key located first at Config::$config['keyPath<library>'] and then Config::$config['keyPath']. If no existing key is found, PHP-Crypt automatically generates and saves a suitable random key for use by the library.

For security purposes, keys are stored in the filesystem well outside of WWW_ROOT by default. Existing key files should be lowercase, with a suffix of .key, and named after the library to which they belong. Ex: keyPathOpenssl => 'openssl.key'.

Examples:

• Allowing PHP-Crypt to generate your keys for you without any pre-existing key file:

  $this->Crypt = new Crypt('Openssl');

  automatically saves the generated random key to openssl.key under Config::$config['keyPath'].

• Whereas, passing a key into the constructor will create an alternate .custom.key file (to avoid overwriting pre-existing keys). For example:

  $this->Crypt = new Crypt('Openssl', 'KeY123');

  Creates a file under Config::$config['keyPath'] named openssl.custom.key with the contents KeY123.

• If you wish to specify a unique path to a key for a library to use, pass in a value for 'keyPath<library>' during instantiation:

  $this->Crypt = new Crypt('Openssl', [
      'keyPathOpenssl' => '/path/to/openssl.key',
  ]);

  or, set it afterwards:

  Crypt::setKeyPath('Openssl', '/path/to/openssl.key');

Testing

Run a composer update --dev to install phpunit in the project, then run vendor/bin/phpunit from the root of the project.

Contributing

All contributions are welcome and encouraged! Start a discussion by opening an issue, then fork this repo, commit your work, and submit a PR!

Important Notes

Use of the Mcrypt library is highly disadvised, and is only included in PHP-Crypt for backwards compatability. The underlying library (libmcrypt) has been abandoned since 2007, and contains a host of undesirable behaviors and possible vulnerabilities. Instead, use Sodium or OpenSSL.

License

This project is licensed under the terms of the MIT license.