AES GCM (Galois Counter Mode) PHP Implementation
Help me out for a couple of :beers:!, (*1)
, (*2)
, (*3)
, (*4)
, (*5)
, (*6)
, (*7)
The Release Process
The release process is described here., (*8)
Prerequisites
This library needs at least 
., (*9)
It has been successfully tested using PHP 5.4 to PHP 7.1, HHVM and nightly branches., (*10)
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., (*11)
Installation
The preferred way to install this library is to rely on Composer:, (*12)
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., (*13)
This library provides an easy way to produce such a ciphertext and read it., (*14)
<?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., (*15)
<?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:, (*16)
<?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);
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, (*17)
Please make sure to follow these best practices., (*18)
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., (*19)
php ./tests/Benchmark.php
Licence
This library is release under MIT licence., (*20)
Wallogit.com
