spomky-labs / php-aes-gcm
AES GCM (Galois Counter Mode) PHP implementation.
Installs: 4 367 589
Dependents: 25
Suggesters: 1
Security: 0
Stars: 70
Watchers: 7
Forks: 23
Open Issues: 2
Requires
- php: >=5.4
- lib-openssl: *
- beberlei/assert: ^2.4
- symfony/polyfill-mbstring: ^1.1
Requires (Dev)
- phpunit/phpunit: ^4.5|^5.0
- satooshi/php-coveralls: ^1.0
Suggests
- ext-crypto: Highly recommended for better performance.
README
The Release Process
The release process is described here.
Prerequisites
It has been successfully tested using PHP 5.4
to PHP 7.1
, HHVM
and nightly branches.
If you use PHP 7.1+, this library has very good performance. If you do not use PHP 7.1+, we highly recommend you to install the PHP Crypto extension. This extension drastically increase the performance of this library. With our pure PHP method, you will have low performance.
Installation
The preferred way to install this library is to rely on Composer:
composer require "spomky-labs/php-aes-gcm"
How to use
<?php use AESGCM\AESGCM; // The Key Encryption Key $K = hex2bin('feffe9928665731c6d6a8f9467308308feffe9928665731c'); // The data to encrypt (can be null for authentication) $P = hex2bin('d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a721c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b39'); // Additional Authenticated Data $A = hex2bin('feedfacedeadbeeffeedfacedeadbeefabaddad2'); // Initialization Vector $IV = hex2bin('cafebabefacedbaddecaf888'); // $C is the encrypted data ($C is null if $P is null) // $T is the associated tag list($C, $T) = AESGCM::encrypt($K, $IV, $P, $A); // The value of $C should be hex2bin('3980ca0b3c00e841eb06fac4872a2757859e1ceaa6efd984628593b40ca1e19c7d773d00c144c525ac619d18c84a3f4718e2448b2fe324d9ccda2710') // The value of $T should be hex2bin('2519498e80f1478f37ba55bd6d27618c') $P = AESGCM::decrypt($K, $IV, $C, $A, $T); // The value of $P should be hex2bin('d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a721c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b39')
Appended Tag
Some implementations of this cypher may append the tag at the end of the ciphertext. This is commonly used by the Java implementation for example.
This library provides an easy way to produce such a ciphertext and read it.
<?php use AESGCM\AESGCM; // The values $K, $P, $A, $IV hereafter have the same meaning as above // $C is the encrypted data with the appended tag $C = AESGCM::encryptAndAppendTag($K, $IV, $P, $A); // The value of $C should be hex2bin('3980ca0b3c00e841eb06fac4872a2757859e1ceaa6efd984628593b40ca1e19c7d773d00c144c525ac619d18c84a3f4718e2448b2fe324d9ccda27102519498e80f1478f37ba55bd6d27618c') $P = AESGCM::decryptWithAppendedTag($K, $IV, $C, $A); // The value of $P should be hex2bin('d9313225f88406e5a55909c5aff5269a86a7a9531534f7da2e4c303d8a318a721c3c0c95956809532fcf0e2449a6b525b16aedf5aa0de657ba637b392519498e80f1478f37ba55bd6d27618c')
Tag Length
By default the tag length is 128 bits. This value is highly recommended, however you may need to use another tag length. As per the cypher specification, the tag length could be 128, 120, 112, 104 or 96 bits.
<?php use AESGCM\AESGCM; // The values $K, $P, $A, $IV hereafter have the same meaning as above $TL = 96; // In this example the tag length will be 96 bits list($C, $T) = AESGCM::encrypt($K, $IV, $P, $A, $TL); // The value of $C should be hex2bin('3980ca0b3c00e841eb06fac4872a2757859e1ceaa6efd984628593b40ca1e19c7d773d00c144c525ac619d18c84a3f4718e2448b2fe324d9ccda2710') // The value of $T should be hex2bin('2519498e80f1478f37ba55bd')
The tag length is automatically calculated during the decryption operation with the method AESGCM::decrypt
.
However, if the tag is appended at the end of the ciphertext and if it is not 128 bits, then it must be set:
<?php // The values $K, $IV, $C, $A hereafter have the same meaning as above $TL = 96; // In this example the tag length will be 96 bits $P = AESGCM::decryptWithAppendedTag($K, $IV, $C, $A, $TL);
Support
I bring solutions to your problems and answer your questions.
If you really love that project and the work I have done or if you want I prioritize your issues, then you can help me out for a couple of 🍻 or more!
Contributing
Requests for new features, bug fixed and all other ideas to make this library useful are welcome. The best contribution you could provide is by fixing the opened issues where help is wanted
Please make sure to follow these best practices.
Benchmark
In the test
folder, a little script to run encryption and decryption benchmarks is available.
You can run it on your environment to check how many time the encryption/decryption operations take.
php ./tests/Benchmark.php
Licence
This library is release under MIT licence.