michaelmawhinney / cryptex
A simple PHP class for 2-way authenticated encryption using XChaCha20 + Poly1305 (libsodium)
Requires
- php: >=8.1
Requires (Dev)
- phpunit/phpunit: ^9
This package is auto-updated.
Last update: 2024-10-06 15:49:16 UTC
README
Cryptex: 2-way Authenticated Encryption Class
Cryptex is a simple PHP class that performs 2-way authenticated encryption using XChaCha20 + Poly1305.
Requirements
- PHP 8.1 or newer
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 $ciphertext = Cryptex::encrypt($plaintext, $key, $salt); // example result: // 4c406399a8830dbf670832b298980280d71bfb8cba53246ed45c9b6e6fc753bc100da3d10d4bf0d406d8afd18b8a5a79f44e50424ed0970914490706418c5725258e // Decrypt the ciphertext $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
Testing
The PHPUnit test class is in tests/CryptexTest.php
.
If you installed Cryptex with Composer, you can run the following command in the top-level folder of this project to perform the unit tests:
./vendor/bin/phpunit --bootstrap vendor/autoload.php tests
If phpunit
is already installed on your local system, you can run this command instead:
phpunit tests
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.