README

Simple crypt/decrypt utility

Not for real secrets. The ciphers are a repeating-key XOR, hex-encoded. They obfuscate a value; they do not protect it against an attacker. Use sodium_crypto_secretbox() or openssl_encrypt() for anything that must stay confidential.

Installation

To install the package, you can use Composer:

composer require jdz/crypt

Requirements

PHP 8.2 or higher
Composer for dependency management

Usage

Basic Example

use JDZ\Crypt\Crypt;
use JDZ\Crypt\SimpleCipher;
use JDZ\Crypt\Key;

// Create a key
$key = new Key('my-secret-passphrase');

// Create cipher and crypt instances
$cipher = new SimpleCipher();
$crypt = new Crypt($cipher, $key);

// Encrypt
$originalText = 'Secret message';
$encrypted = $crypt->encrypt($originalText);

// Decrypt
$decrypted = $crypt->decrypt($encrypted);

echo $decrypted; // Output: Secret message

Available Ciphers

The library provides three cipher implementations:

SimpleCipher - Uses the passphrase directly as the encryption key
Md5Cipher - deprecated since 3.1.0: an alias of SimpleCipher, nothing is hashed
Sha1Cipher - deprecated since 3.1.0: an alias of SimpleCipher, nothing is hashed

All ciphers use XOR-based encryption and extend from SimpleCipher. The two hash-named ciphers never hashed anything; they are kept so that whatever was stored with them decodes the same, and will go with 4.0 — use SimpleCipher (or hash the key yourself with a generator).

decrypt() is strict about its input: two hex digits per byte, upper or lower case (the high nibble of a byte below 16 may be a space, which is what encrypt() writes). Anything else — an odd length, a non-hex character, a tampered cookie — throws an \InvalidArgumentException; it used to decode to garbage. Catch it where the ciphertext comes from a visitor.

Key Generation

You can generate keys automatically using the generator classes:

use JDZ\Crypt\SimpleGenerator;
use JDZ\Crypt\Md5Generator;
use JDZ\Crypt\Sha1Generator;

// Simple generator
$generator = new SimpleGenerator();
$key = $generator->generateKey();

// MD5 generator
$md5Generator = new Md5Generator();
$md5Key = $md5Generator->generateKey();

// SHA1 generator
$sha1Generator = new Sha1Generator();
$sha1Key = $sha1Generator->generateKey();

Manual Key Creation

use JDZ\Crypt\Key;

// Single key (public and private are the same)
$key = new Key('my-passphrase');

// Separate public and private keys
$key = new Key('public-key', 'private-key');

Examples

The examples/ directory contains:

simple.php - Basic usage with SimpleCipher and key generation
md5.php - MD5-based encryption with auto-generated and manual keys
sha1.php - SHA1-based encryption with auto-generated and manual keys
comparison.php - Comparison of all cipher types
benchmark.php - Performance comparison and timing benchmarks

Run an example:

php examples/simple.php
php examples/md5.php
php examples/sha1.php

Compare and benchmark:

php examples/comparison.php
php examples/benchmark.php

Testing

Run Tests

Run all tests:

composer test
# or
vendor/bin/phpunit

Run tests with coverage report (HTML):

composer test-coverage
# Coverage report will be generated in the coverage/ directory

Test Structure

Tests are located in the tests/ directory and follow the PSR-4 autoloading standard under the JDZ\Crypt\Tests namespace.

KeyTest.php - Tests for the Key class
SimpleCipherTest.php - Tests for the SimpleCipher implementation
CryptTest.php - Tests for the main Crypt class
SimpleGeneratorTest.php, Md5GeneratorTest.php, Sha1GeneratorTest.php - Tests for the key generators

Changelog

3.1.0 - Security: decrypt() refuses what is not its hex (odd length, non-hex characters) with an \InvalidArgumentException — a lowercase digit was read as 0, any other character as 0 and an odd input gained a byte, so a tampered value decoded to garbage; lowercase hex is accepted. The generators draw from random_int() instead of mt_rand(). Md5Cipher / Sha1Cipher are deprecated (aliases of SimpleCipher, behaviour kept).
3.0.3 - An empty key, or a generator length below 1, throws an InvalidArgumentException instead of hanging encrypt() / decrypt(); known-answer tests pin the ciphertext format.
3.0.2 - PHPUnit 11.
3.0.1 - composer test runs with testdox output.
3.0.0 - Breaking rewrite: CryptCipher, CryptKey and the Crypt*Interface classes are replaced by SimpleCipher / Md5Cipher / Sha1Cipher, Key, the matching generators and CipherInterface / GeneratorInterface; tests and examples added.

License

This project is licensed under the MIT License - see the LICENSE file for details.

jdz / crypt

Package info

Security

Statistics