Encrypt/decrypt using block ciphers
Zend\Crypt\BlockCipher implements encrypt-then-authenticate mode using
HMAC to provide authentication.
The symmetric cipher can be chosen with a specific adapter that implements
Zend\Crypt\Symmetric\SymmetricInterface. We support the symmmetric encryption
algorithms offered by OpenSSL and
In the following code, we detail an example of using the
BlockCipher class to
encrypt-then-authenticate a string using the
AES-256 block cipher
and the HMAC algorithm (using the SHA-256
The Mcrypt extension is based on the libmcrypt library. Unfortunately, at the time of writing, the project is dead, having been unmaintained for around 8 years, with the last release (version 2.5.8) having occurred in February 2007.
Starting with PHP 7.1, the Mcrypt extension will be considered deprecated. For these reasons, we strongly suggest using only the Openssl adapter.
Starting with zend-crypt 3.0, the Openssl adapter is the default (for example, by
Zend\Crypt\FileCipher), and all examples now only demonstrate that adapter.
use Zend\Crypt\BlockCipher; $blockCipher = BlockCipher::factory('openssl', array('algo' => 'aes')); $blockCipher->setKey('encryption key'); $result = $blockCipher->encrypt('this is a secret message'); echo "Encrypted text: $result\n";
BlockCipher instance is initialized using a factory method with the name
of the cipher adapter to use (e.g.,
openssl) and the parameters to pass to the adapter
(the AES algorithm). In order to encrypt a string, we need to specify an
encryption key, which we do via the
setKey() method. Encryption is performed
The output of encryption is a string, encoded in Base64 (default), containing
the HMAC value, the IV vector, and the encrypted text. The encryption mode used
(with a random IV by
default), with the default HMAC hash algorithm of SHA256. The Openssl adapter
encrypts using the PKCS#7 padding
mechanism by default. You can specify a different padding method using a special
Zend\Crypt\Symmetric\Padding). The encryption and authentication keys
BlockCipher are generated with the PBKDF2
algorithm, used as the key derivation function from the user's key specified
BlockCipher always attempts to use the longest key size for the specified cipher. For instance, for the AES algorithm it uses 256 bits, and for the Blowfish algorithm it uses 448 bits.
You can change all the default settings by passing the values to the factory parameters. For instance, if you want to use the Blowfish algorithm, with the CFB mode and the HMAC SHA512 hash function, initialize the class as follows:
use Zend\Crypt\BlockCipher; $blockCipher = BlockCipher::factory( 'openssl', [ 'algo' => 'blowfish', 'mode' => 'cfb', 'hash' => 'sha512' ] );
If you are not familiar with symmetric encryption techniques, we strongly suggest using the default values of the
BlockCipherclass. The default values are: AES algorithm, CBC mode, HMAC with SHA256, PKCS#7 padding.
To decrypt a string we can use the
decrypt() method. In order to successfully
decrypt a string, we must configure the
BlockCipher with the same parameters
used during encryption.
We can also initialize the
BlockCipher manually without using the factory method;
we can inject the symmetric cipher adapter directly via the constructor.
For instance, we can rewrite the previous example as follows:
use Zend\Crypt\BlockCipher; use Zend\Crypt\Symmetric\Openssl; $blockCipher = new BlockCipher(new Openssl(['algo' => 'aes'])); $blockCipher->setKey('encryption key'); $result = $blockCipher->encrypt('this is a secret message'); echo "Encrypted text: $result \n";
Using GCM or CCM mode from PHP 7.1+
If you are using PHP 7.1+ you can choose the GCM or CCM mode for authenticated encryption with OpenSSL. These modes provide authenticated encryption by itself, without the usage of HMAC as described in the previous section.
If you want to use the GCM or CCM mode with
BlockCipher you can just specify
the mode in the factory. For instance, the following is an example of
aes-256-gcm encryption with OpenSSL:
use Zend\Crypt\BlockCipher; $blockCipher = BlockCipher::factory( 'openssl', [ 'algo' => 'aes', 'mode' => 'gcm' ] );
And below is an example demonstrating the factory for
use Zend\Crypt\BlockCipher; $blockCipher = BlockCipher::factory( 'openssl', [ 'algo' => 'aes', 'mode' => 'ccm' ] );
GCM mode is about 3x faster than CCM, we recommend using GCM unless you have requirements that dictate CCM.
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!