Crypt Component

Overview

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

By default, this component utilizes the AES-256-CFB cipher.

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 is not crackable since the combinations of keys are massive. Although the NSA has categorized this in Suite B, they have also recommended using higher than 128-bit keys for encryption.

Basic Usage

This component is designed to be very simple to use:

<?php

use Phalcon\Encryption\Crypt;

$key       = random_bytes(32);
$crypt     = new Crypt();
$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

If no parameters are passed in the constructor, the component will use the aes-256-cfb cipher with signing by default. You can always change the cipher as well as disable signing.

<?php

use Phalcon\Encryption\Crypt;
use Phalcon\Encryption\Crypt\PadFactory;

$key        = random_bytes(32);
$padFactory = new PadFactory();
$crypt      = new Crypt("aes-256-cfb", true, $padFactory);

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

<?php

use Phalcon\Encryption\Crypt;

$key   = random_bytes(32);
$crypt = new Crypt();

$crypt
    ->setCipher('aes256')
    ->useSigning(false)
;

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

Encrypt

The encrypt() method encrypts a string. The component will use the previously set cipher, which has been set in the constructor or explicitly. If no key is passed in the parameter, the previously set key will be used.

<?php

use Phalcon\Encryption\Crypt;

$key   = random_bytes(32); 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text);

or using the key as the second parameter

<?php

use Phalcon\Encryption\Crypt;

$key       = random_bytes(32); 
$crypt     = new Crypt();
$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

The method will also internally use signing by default. You can always use useSigning(false) prior to the method call to disable it.

Decrypt

The decrypt() method decrypts a string. Similar to encrypt() the component will use the previously set cipher, which has been set in the constructor or explicitly. If no key is passed in the parameter, the previously set key will be used.

<?php

use Phalcon\Encryption\Crypt;

$key   = random_bytes(32); 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3';
$encrypted = $crypt->decrypt($text);

or using the key as the second parameter

<?php

use Phalcon\Encryption\Crypt;

$key   = random_bytes(32); 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3';
$encrypted = $crypt->decrypt($text, $key);

The method will also internally use signing by default. You can always use useSigning(false) prior to the method call to disable it.

Base64 Encrypt

The encryptBase64() can be used to encrypt a string in a URL-friendly way. It uses encrypt() internally and accepts the text and optionally the key of the element to encrypt. There is also a third parameter safe (defaults to false) which will perform string replacements for non URL friendly characters such as + or /.

Base64 Decrypt

The decryptBase64() can be used to decrypt a string in a URL-friendly way. Similar to encryptBase64() it uses decrypt() internally and accepts the text and optionally the key of the element to encrypt. There is also a third parameter safe (defaults to false) which will perform string replacements for previously replaced non URL friendly characters such as + or /.

Exceptions

Exceptions thrown in the Phalcon\Encryption\Crypt component will be of type Phalcon\Encryption\Crypt\Exception. If however, you are using signing and the calculated hash for decrypt() does not match, Phalcon\Encryption\Crypt\Mismatch will be thrown. You can use these exceptions to selectively catch exceptions thrown only from this component.

<?php

use Phalcon\Encryption\Crypt\Mismatch;
use Phalcon\Mvc\Controller;

class IndexController extends Controller
{
    public function index()
    {
        try {
            // Get some configuration values
            $this->crypt->decrypt('hello');
        } catch (Mismatch $ex) {
            echo $ex->getMessage();
        }
    }
}

Functionality

Ciphers

The getter getCipher() returns the currently selected cipher. If none has been explicitly defined either by the setter setCipher() or the constructor of the object the aes-256-cfb is selected by default. The aes-256-gcm is the preferable cipher.

You can always get an array of all the available ciphers for your system by calling getAvailableCiphers().

Hash Algorithm

The getter getHashAlgo() returns the hashing algorithm used by the component. If none has been explicitly defined by the setter setHashAlgo() the sha256 will be used. If the hash algorithm defined is not available in the system or is wrong, a Phalcon\Encryption\Crypt\Exception will be thrown.

You can always get an array of all the available hashing algorithms for your system by calling getAvailableHashAlgos().

Keys

The component offers a getter and a setter for the key to be used. Once the key is set, it will be used for any encrypting or decrypting operation (provided that the key parameter is not defined when using these methods).

getKey(): Returns the encryption key.
setKey() Sets the encryption key.

Signing

To instruct the component to use signing or not, useSigning is available. It accepts a boolean which sets a flag internally, specifying whether signing will be used or not.

Auth Data

If the cipher selected is of type gcm or ccm (what the cipher name ends with), auth data is required for the component to correctly encrypt or decrypt data. The methods available for this operation are:

setAuthTag()
setAuthData()
setAuthTagLength() - (16)

Padding

You can also set the padding used by the component by using setPadding(). By default, the component will use PADDING_DEFAULT. The available padding constants are:

PADDING_ANSI_X_923
PADDING_DEFAULT
PADDING_ISO_10126
PADDING_ISO_IEC_7816_4
PADDING_PKCS7
PADDING_SPACE
PADDING_ZERO

Dependency Injection

As with most Phalcon components, you can store the Phalcon\Encryption\Crypt object in your Phalcon\Di container. By doing so, you will be able to access your configuration object from controllers, models, views, and any component that implements Injectable.

An example of the registration of the service as well as accessing it is below:

<?php

use Phalcon\Di\FactoryDefault;
use Phalcon\Encryption\Crypt;

// Create a container
$container = new FactoryDefault();

$container->set(
    'crypt',
    function () {
        $crypt = new Crypt();

        // Set a global encryption key
        $crypt->setKey(
            "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
        );

        return $crypt;
    },
    true
);

The component is now available in your controllers using the crypt key

<?php

use MyApp\Models\Secrets;
use Phalcon\Encryption\Crypt;
use Phalcon\Http\Request;
use Phalcon\Mvc\Controller;

/**
 * @property Crypt   $crypt
 * @property Request $request
 */
class SecretsController extends Controller
{
    public function saveAction()
    {
        $secret = new Secrets();

        $text = $this->request->getPost('text');

        $secret->content = $this->crypt->encrypt($text);

        if ($secret->save()) {
            $this->flash->success(
                'Secret was successfully created!'
            );
        }
    }
}

Constants

Two constants are available:

DEFAULT_ALGORITHM = "sha256"
DEFAULT_CIPHER = "aes-256-cfb"
PADDING_ANSI_X_923 = 1
PADDING_DEFAULT = 0
PADDING_ISO_10126 = 3
PADDING_ISO_IEC_7816_4 = 4
PADDING_PKCS7 = 2
PADDING_SPACE = 6
PADDING_ZERO = 5

You can use them in your project or override them if you want to implement your own class.

Methods

public function __construct(
    string $cipher = self::DEFAULT_CIPHER, 
    bool $useSigning = true, 
    PadFactory $padFactory = null
)

Constructor

public function decrypt(string $input, string $key = null): string

Decrypt an encrypted text

public function decryptBase64(
    string $input, 
    string $key = null, 
    bool $safe = false
): string

Decrypt a text that is coded as a base64 string

public function encrypt(string $input, string $key = null): string

Encrypt a text

public function encryptBase64(
    string $input, 
    string $key = null, 
    bool $safe = false
): string

Encrypts a text returning the result as a base64 string

public function getAvailableCiphers(): array

Return a list of available ciphers

public function getAuthData(): string

Return the auth data

public function getAuthTag(): string

Return the auth tag

public function getAuthTagLength(): int

Return the auth tag length

public function getAvailableHashAlgorithms(): array

Return a list of registered hashing algorithms suitable for hash_hmac

public function getHashAlgorithm(): string

Get the name of the hashing algorithm.

public function getCipher(): string

Returns the current cipher

public function getKey(): string

Returns the encryption key

public function isValidDecryptLength(string $input): bool

Returns if the input length for decryption is valid or not (number of bytes required by the cipher)

public function setAuthData(string $data): CryptInterface

Set the auth data

public function setAuthTag(string $tag): CryptInterface

Set the auth tag

public function setAuthTagLength(int $length): CryptInterface

Set the auth tag length

public function setCipher(string $cipher): CryptInterface

Set the cipher algorithm for data encryption and decryption

public function setKey(string $key): CryptInterface

public function setHashAlgorithm(string $hashAlgorithm): CryptInterface

Set the name of the hashing algorithm.

public function setPadding(int $scheme): CryptInterface

Set the padding scheme

public function useSigning(bool $useSigning): CryptInterface

Use a message digest (signing) to be used or not

PadFactory

The Phalcon\Encryption\Crypt\PadFactory is an object that instantiates classes to be used for padding and unpadding data during encryption or decryption.

Name	Class
`ansi`	`Phalcon\Encryption\Crypt\Padding\Ansi`
`iso10126`	`Phalcon\Encryption\Crypt\Padding\Iso10126`
`isoiek`	`Phalcon\Encryption\Crypt\Padding\IsoIek`
`noop`	`Phalcon\Encryption\Crypt\Padding\Noop`
`pjcs7`	`Phalcon\Encryption\Crypt\Padding\Pkcs7`
`space`	`Phalcon\Encryption\Crypt\Padding\Space`
`zero`	`Phalcon\Encryption\Crypt\Padding\Zero`

Phalcon\Encryption\Crypt\Padding\PadInterface is also available, should you need to create your own padding strategy. Note that you will need to register the new padding class in the Phalcon\Encryption\Crypt\PadFactory and inject it into the constructor of the Phalcon\Encryption\Crypt component.