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 git@github.com: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.

benjaminstout / php-crypt

Maintainers

Details