Encryption Library — CodeIgniter 3.1.3 documentation (2024)

Initializing the Class¶

Like most other classes in CodeIgniter, the Encryption library isinitialized 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 CBCmode, 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 knowthat a HMAC also requires a secret key and using the same key for bothencryption and authentication is a bad practice.

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

Setting your encryption_key¶

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

It must be noted that to ensure maximum security, such key should notonly be as strong as possible, but also often changed. Such behaviorhowever is rarely practical or possible to implement, and that is whyCodeIgniter gives you the ability to configure a single key that is to beused (almost) every time.

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

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

The key should be as random as possible and it must not be a regulartext string, nor the output of a hashing function, etc. In order to createa 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, oryou can design your own storage mechanism and pass the key dynamicallywhen encrypting/decrypting.

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

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

You’ll notice that the create_key() method outputs binary data, whichis hard to deal with (i.e. a copy-paste may damage it), so you may usebin2hex(), hex2bin() or Base64-encoding to work with the key ina 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 usuallylonger than the original, plain-text string (depending on the cipher).

This is influenced by the cipher algorithm itself, the IV prepended to thecipher-text and the HMAC authentication message that is also prepended.Furthermore, the encrypted message is also Base64-encoded so that it is safefor 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 oldEncrypt Class, the Encryption library is designed touse repeatedly the same driver, encryption cipher, mode and key.

As noted in the “Default behavior” section above, this means using anauto-detected driver (OpenSSL has a higher priority), the AES-128 ciperin 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 areoptional:

For example, if you were to change the encryption algorithm andmode 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 isimportant 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 youhave 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 librarysettings is simple. As simple as just passing the string to theencrypt() 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 necessaryfor 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 ));