Encryption Library¶

Initializing the Class¶

Like most other classes in CodeIgniter, the Encryption library is initialized in your controller using the $this->load->library() method:

$this->load->library('encryption');

Once loaded, the Encryption library object will be available using:

$this->encryption

Default behavior¶

By default, the Encryption Library will use the AES-128 cipher in CBC mode, using your configured encryption_key and SHA512 HMAC authentication.

However, the encryption_key is not used as is.

If you are somewhat familiar with cryptography, you should already know that a HMAC also requires a secret key and using the same key for both encryption and authentication is a bad practice.

Because of that, two separate keys are derived from your already configured encryption_key: one for encryption and one for authentication. This is done via a technique called HMAC-based Key Derivation Function (HKDF).

Setting your encryption_key¶

An encryption key is a piece of information that controls the cryptographic process and permits a plain-text string to be encrypted, and afterwards - decrypted. It is the secret “ingredient” in the whole process that allows you to be the only one who is able to decrypt data that you’ve decided to hide from the eyes of the public. After one key is used to encrypt data, that same key provides the only means to decrypt it, so not only must you chose one carefully, but you must not lose it or you will also lose access to the data.

It must be noted that to ensure maximum security, such key should not only be as strong as possible, but also often changed. Such behavior however is rarely practical or possible to implement, and that is why CodeIgniter gives you the ability to configure a single key that is to be used (almost) every time.

It goes without saying that you should guard your key carefully. Should someone gain access to your key, the data will be easily decrypted. If your server is not totally under your control it’s impossible to ensure key security so you may want to think carefully before using it for anything that requires high security, like storing credit card numbers.

Your encryption key must be as long as the encyption algorithm in use allows. For AES-128, that’s 128 bits or 16 bytes (charcters) long. You will find a table below that shows the supported key lengths of different ciphers.

The key should be as random as possible and it must not be a regular text string, nor the output of a hashing function, etc. In order to create a proper key, you must use the Encryption library’s create_key() method

// $key will be assigned a 16-byte (128-bit) random key
$key = $this->encryption->create_key(16);

The key can be either stored in your application/config/config.php, or you can design your own storage mechanism and pass the key dynamically when encrypting/decrypting.

To save your key to your application/config/config.php, open the file and set:

$config['encryption_key'] = 'YOUR KEY';

You’ll notice that the create_key() method outputs binary data, which is hard to deal with (i.e. a copy-paste may damage it), so you may use bin2hex(), hex2bin() or Base64-encoding to work with the key in a more friendly manner. For example:

// Get a hex-encoded representation of the key:
$key = bin2hex($this->encryption->create_key(16));

// Put the same value in your config with hex2bin(),
// so that it is still passed as binary to the library:
$config['encryption_key'] = hex2bin(<your hex-encoded key>);

Supported encryption ciphers and modes¶

Message Length¶

It’s probably important for you to know that an encrypted string is usually longer than the original, plain-text string (depending on the cipher).

This is influenced by the cipher algorithm itself, the IV prepended to the cipher-text and the HMAC authentication message that is also prepended. Furthermore, the encrypted message is also Base64-encoded so that it is safe for storage and transmission, regardless of a possible character set in use.

Keep this information in mind when selecting your data storage mechanism. Cookies, for example, can only hold 4K of information.

Configuring the library¶

For usability, performance, but also historical reasons tied to our old Encrypt Class, the Encryption library is designed to use repeatedly the same driver, encryption cipher, mode and key.

As noted in the “Default behavior” section above, this means using an auto-detected driver (OpenSSL has a higher priority), the AES-128 ciper in CBC mode, and your $config['encryption_key'] value.

If you wish to change that however, you need to use the initialize() method. It accepts an associative array of parameters, all of which are optional:

For example, if you were to change the encryption algorithm and mode to AES-256 in CTR mode, this is what you should do:

$this->encryption->initialize(
        array(
                'cipher' => 'aes-256',
                'mode' => 'ctr',
                'key' => '<a 32-character random string>'
        )
);

Note that we only mentioned that you want to change the ciper and mode, but we also included a key in the example. As previously noted, it is important that you choose a key with a proper size for the used algorithm.

There’s also the ability to change the driver, if for some reason you have both, but want to use MCrypt instead of OpenSSL:

// Switch to the MCrypt driver
$this->encryption->initialize(array('driver' => 'mcrypt'));

// Switch back to the OpenSSL driver
$this->encryption->initialize(array('driver' => 'openssl'));

Encrypting and decrypting data¶

Encrypting and decrypting data with the already configured library settings is simple. As simple as just passing the string to the encrypt() and/or decrypt() methods:

$plain_text = 'This is a plain-text message!';
$ciphertext = $this->encryption->encrypt($plain_text);

// Outputs: This is a plain-text message!
echo $this->encryption->decrypt($ciphertext);

And that’s it! The Encryption library will do everything necessary for the whole process to be cryptographically secure out-of-the-box. You don’t need to worry about it.

// Assume that we have $ciphertext, $key and $hmac_key
// from on outside source

$message = $this->encryption->decrypt(
        $ciphertext,
        array(
                'cipher' => 'blowfish',
                'mode' => 'cbc',
                'key' => $key,
                'hmac_digest' => 'sha256',
                'hmac_key' => $hmac_key
        )
);