Encryption/Decryption

Phalcon provides encryption facilities via the Phalcon\Crypt component. This class offers simple object-oriented wrappers to the openssl PHP’s encryption library.

By default, this component provides secure encryption using AES-256-CFB.

The cipher AES-256 is used among other places in SSL/TLS across the Internet. It’s considered among the top ciphers. In theory it’s not crackable since the combinations of keys are massive. Although NSA has categorized this in Suite B, they have also recommended using higher than 128-bit keys for encryption.

You must use a key length corresponding to the current algorithm. For the algorithm used by default it is 32 bytes.

Basic Usage

This component is designed be very simple to use:

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. /**
  9.  * Set the cipher algorithm.
  10.  *
  11.  * The `aes-256-gcm' is the preferable cipher, but it is not usable until the
  12.  * openssl library is upgraded, which is available in PHP 7.1.
  13.  *
  14.  * The `aes-256-ctr' is arguably the best choice for cipher
  15.  * algorithm in these days.
  16.  */
  17. $crypt->setCipher('aes-256-ctr');
  19. /**
  20.  * Set the encryption key.
  21.  *
  22.  * The `$key' should have been previously generated in a cryptographically safe way.
  23.  *
  24.  * Bad key:
  25.  * "le password"
  26.  *
  27.  * Better (but still unsafe):
  28.  * "#1dj8$=dp?.ak//j1V$~%*0X"
  29.  *
  30.  * Good key:
  31.  * "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
  32.  *
  33.  * Use your own key. Do not copy and paste this example key.
  34.  */
  35. $key = "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3";
  37. $text = 'This is the text that you want to encrypt.';
  39. $encrypted = $crypt->encrypt($text, $key);
  41. echo $crypt->decrypt($encrypted, $key);

You can also set the algorithm and whether to calculate a digest of the message (signing) during the object construction. This removes the need to call setCipher() and useSigning():

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt('aes-256-ctr', true);
  8. $key = "T4\xb1\x8d\xa9\x98\x05\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3";
  10. $text = 'This is the text that you want to encrypt.';
  12. $encrypted = $crypt->encrypt($text, $key);
  14. echo $crypt->decrypt($encrypted, $key);

You can use the same instance to encrypt/decrypt several times:

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. $crypt->setCipher('aes-256-ctr');
  10. // Use your own keys!
  11. $texts = [
  12.     "T4\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\\x5c" => 'This is a secret text',
  13.     "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3" => 'This is a very secret',
  14. ];
  16. foreach ($texts as $key => $text) {
  17.     // Perform the encryption
  18.     $encrypted = $crypt->encrypt($text, $key);
  20.     // Now decrypt
  21.     echo $crypt->decrypt($encrypted, $key);
  22. }

For better security, you can instruct the component to calculate a message digest based on one of the supported algorithms returned by getAvailableHashAlgos. As seen above this algorithm can be set during the object instantiation but can also be set afterwards.

NOTE Calculating the message digest (signing) will be enabled by default in Phalcon 4.0.0 or greater.

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. $crypt->setCipher('aes-256-ctr');
  9. $crypt->setHashAlgo('aes-256-cfb');
  11. // Force calculation of a digest of the message based on the Hash algorithm
  12. $crypt->useSigning(true);
  14. $key  = "T4\xb1\x8d\xa9\x98\x054t7w!z%C*F-Jk\x98\x05\\x5c";
  15. $text = 'This is a secret text';
  17. // Perform the encryption
  18. $encrypted = $crypt->encrypt($text, $key);
  20. // Now decrypt
  21. echo $crypt->decrypt($encrypted, $key);

Encryption Options

The following options are available to change the encryption behavior:

NameDescription
CipherThe cipher is one of the encryption algorithms supported by openssl. You can see a list here

Example:

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. // Use blowfish
  9. $crypt->setCipher('bf-cbc');
  11. // Use your own key!
  12. $key  = "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3";
  13. $text = 'This is a secret text';
  15. echo $crypt->encrypt($text, $key);

If you wish to check the available algorithms that your system supports you can call the getAvailableHashAlgos() method.

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. // Get the supported algorithms
  9. $algorithms = $crypt->getAvailableHashAlgos();
  11. var_dump($algorithms);

Base64 Support

In order for encryption to be properly transmitted (emails) or displayed (browsers) base64 encoding is usually applied to encrypted texts:

  1. <?php
  3. use Phalcon\Crypt;
  5. // Create an instance
  6. $crypt = new Crypt();
  8. // Use your own key!
  9. $key  = "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3";
  10. $text = 'This is a secret text';
  12. $encrypt = $crypt->encryptBase64($text, $key);
  14. echo $crypt->decryptBase64($encrypt, $key);

Setting up an Encryption service

You can set up the encryption component in the services container in order to use it from any part of the application:

  1. <?php
  3. use Phalcon\Crypt;
  5. $di->set(
  6.     'crypt',
  7.     function () {
  8.         $crypt = new Crypt();
  10.         // Set a global encryption key
  11.         $crypt->setKey(
  12.             "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
  13.         );
  15.         return $crypt;
  16.     },
  17.     true
  18. );

Then, for example, in a controller you can use it as follows:

  1. <?php
  3. use Phalcon\Mvc\Controller;
  5. class SecretsController extends Controller
  6. {
  7.     public function saveAction()
  8.     {
  9.         $secret = new Secrets();
  11.         $text = $this->request->getPost('text');
  13.         $secret->content = $this->crypt->encrypt($text);
  15.         if ($secret->save()) {
  16.             $this->flash->success(
  17.                 'Secret was successfully created!'
  18.             );
  19.         }
  20.     }
  21. }