This PHP7 extension provides a simplified interface to the Argon2 algorithm, the winner of the Password Hashing Competition. Argon2 is considered the successor to bcrypt/scrypt/pbkdf methods of securely hasing passwords. This project is in no way associated with or endorsed by the PHC team.
Note this is extension is only compatible with PHP7+. Support for lower versions of PHP will not be considered.
# Clone the extension and the Argon2 Submodule
git clone --recursive https://github.com/charlesportwoodii/php-argon2-ext
cd php-argon2-ext
# Build the Argon2 library
cd ext/argon2
CFLAGS="-fPIC" make -j1 OPTTARGET=i686
make test
# Remove the argon2 shared library to force Argon2 to be compiled statically into the extension
rm libargon2.so
cd ../..
# Build the extension
phpize
./configure --with-argon2
make
Once you have compiled the extension, you can install it via make install
, adding the extension to your php.ini
file or to a file in your loaded extensions directory,
$ make install
# Load the extension to your php.ini/php conf.d
# echo "extension=argon2.so" > /path/to/php.ini
Extension is tested through make test
. You are strongly encouraged to run the tests to make sure everything was built correctly. A summary of the tests will be outlined
$ make test
If make test
encounters an error, please provide a copy of the error report as a Github issue.
The following constants are exposed for determining which Argon2 algorithm you wish to use:
HASH_ARGON2ID
HASH_ARGON2I
HASH_ARGON2D
The constant HASH_ARGON2ID
can also be aliased by HASH_ARGON2
.
These constants are named to avoid conflicts with php/php-src#1997, which would implement Argon2 in PHP Core.
argon2_hash(string $string [, const $algorithm = HASH_ARGON2ID] [, array $options ] [, bool $raw = false ]);
Hashes can be generated by running argon2_hash()
with the string you want to see hashed. Without any additional arguements, the hash generated will have the following options. These defaults are based upon the Argon2 specification as good minimums. You are encouraged to run make bench
against the ext/argon2
to determine what are good defaults for your system.
algorithm = HASH_ARGON2ID
options = [
m_cost: 1<<16
t_cost: 3
threads: 1
]
This function follows the same design principles of
password_hash()
, in that a salt will be generated on your behalf. This method does not provide you with a way to provide your own salt. The salt generated uses the native PHP functionphp_password_make_salt
, which is the same method used to generate salts forpassword_hash()
.
The $algorithm
can be changed by passing in either HASH_ARGON2ID
, HASH_ARGON2I
or HASH_ARGON2D
. If the algorithm is invalid, an InvalidArguementException
will be raised.
This library allows you to specify an array of options to tune Argon2 to your system. The available options for the $options
array, and their defaults are defined above. Argon2 has several tolerances in place for each of these values. If the value falls outside those tolerances, and InvalidArguementException
will be raised.
In the event an error occurs with the argon2 library, or a salt cannot be securely generated, an E_WARNING
will be raised, and this will return false
.
If no errors occur, an argon2 encoded hash string will be returned.
This function operates against version 1.3 of the Argon2 library and above.
$argon2i$v=19$m=65536,t=3,p=1$aUEvQlU2NTRwcHhVS0hqMg$+5h0P5YlWCJDKyZknJ0sAyqQtZjhuP1Bkw/E2It4IcE
If
$raw
is set totrue
, then this function will return binary output instead. This is useful for Key Derivation Functions (KDF).
argon2_verify(string $string, string $hash);
Hashes can be verified by running argon2_verify()
with the string string and string hash generated by argon2_hash
. This function will return either true
or false
depending upon if the hash is valid or not. If the hash
provided isn't a valid argon2 hash, false
will be returned, an an E_WARNING
will be raised.
argon2_get_info(string $hash);
To retrieve information about an existing Argon2 hash, run argon2_get_info()
. This function will return an array containing the algorithm name, and the options used for hash generation.
array(2) {
["algorithm"]=>
string(7) "argon2i"
["options"]=>
array(3) {
["m_cost"]=>
int(65536)
["t_cost"]=>
int(3)
["threads"]=>
int(1)
}
}
BSD-3-Clause. See LICENSE for more details.
PHP functions php_password_make_salt
and salt_to_base64
are licensed under the PHP License. See http://www.php.net/license/3_01.txt.
This product includes PHP software, freely available from http://www.php.net/software/