README

Cryptex: 2-way Authenticated Encryption Class

Cryptex is a simple PHP class that performs 2-way authenticated encryption using XChaCha20 + Poly1305.

Version 5.0.0 is a modernization and hardening release. It keeps the v4 public API, the v4 hex ciphertext format, and external salt semantics intact.

Requirements

• PHP 8.3 or newer
• ext-sodium

These requirements apply to v5.0.0 and later. Existing v4-style ciphertexts remain decryptable with the same API, but v5 does not introduce a new ciphertext envelope or transport encoding.

Installation

The preferred method of installation is with Packagist and Composer. The following command installs the package and adds it as a requirement to your project's composer.json:

composer require michaelmawhinney/cryptex

You can also download or clone the repo and include the src/Cryptex.php manually if you prefer.

Usage

Always store or transmit your $key and $salt values securely.

<?php
require 'vendor/autoload.php';

use cryptex\Cryptex;

try {

    // Your private data and secret key
    $plaintext = "You're a certified prince.";
    $key = "1-2-3-4-5"; // same combination on my luggage

    // Generate a secure random salt value
    $salt = Cryptex::generateSalt();

    // Encrypt the plaintext using the preserved v4-style API and hex ciphertext output
    $ciphertext = Cryptex::encrypt($plaintext, $key, $salt);
    // example result: 
    // 4c406399a8830dbf670832b298980280d71bfb8cba53246ed45c9b6e6fc753bc100da3d10d4bf0d406d8afd18b8a5a79f44e50424ed0970914490706418c5725258e

    // Decrypt the ciphertext with the same v4-style API
    $result = Cryptex::decrypt($ciphertext, $key, $salt);

} catch (Exception $e) {

    // There was some error during salt generation, encryption, authentication, or decryption
    echo 'Caught exception: ' . $e->getMessage() . "\n";

}

// Verify with a timing attack safe string comparison
if (hash_equals($plaintext, $result)) {

    // Cryptex securely encrypted and decrypted the data
    echo "Pass";

} else {

    // There was some failure that did not generate any exceptions
    echo "Fail";

}

// The above example will output: Pass

Release Notes

See CHANGELOG.md for the v5.0.0 release summary and compatibility notes.

Testing

The PHPUnit test class is in tests/CryptexTest.php.

If you installed Cryptex with Composer, you can run the following commands in the top-level folder of this project:

composer test

composer lint

The PHPUnit command used by composer test is:

./vendor/bin/phpunit --configuration phpunit.xml.dist

Generating Documentation

Cryptex uses phpDocumentor to automatically generate documentation whenever changes are made. The generated documentation is available online here. However if you want to generate the documentation locally, you can run the following command in the top-level folder of this project (requires docker):

docker run --rm -v "$(pwd):/data" "phpdoc/phpdoc:3" -d src,tests -t docs

If you want to use another method of running/installing phpdoc, refer to the phpDocumentor documentation.