Encryption

• Configuration
• Basic Usage

Configuration

Before using Maravel’s encrypter, you should set the APP_KEY option of your .env file to a 32 character, random string. If this value is not properly set, all values encrypted by Maravel will be insecure.

Gracefully Rotating Encryption Keys

If you change your application’s encryption key, all authenticated user sessions will be logged out of your application. This is because every cookie, including session cookies, are encrypted by Maravel. In addition, it will no longer be possible to decrypt any data that was encrypted with your previous encryption key.

To mitigate this issue, Maravel allows you to configure your previous encryption keys and ciphers in your application’s APP_PREVIOUS_KEYS_CIPHERS_MAP_JSON environment variable as json. This variable may contain a json map with previous key mapped to its cipher:

APP_KEY=”base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY=” APP_PREVIOUS_KEYS_CIPHERS_MAP_JSON={“base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w=”:”AES-256-CBC”, …}

When you set this environment variable, Maravel will always use the “current” encryption key when encrypting values. However, when decrypting values, Maravel will first try the current key, and if decryption fails using the current key, Maravel will try all previous keys until one of the keys is able to decrypt the value.

This approach to graceful decryption allows users to keep using your application uninterrupted even if your encryption key is rotated.

Basic Usage

Encrypting A Value

You may encrypt a value using the Crypt facade. All encrypted values are encrypted using OpenSSL and the AES-256-CBC cipher. Furthermore, all encrypted values are signed with a message authentication code (MAC) to detect any modifications to the encrypted string.

For example, we may use the encrypt method to encrypt a secret and store it on an Eloquent model:

<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Crypt;

class UserController extends Controller
{
	/**
	 * Store a secret message for the user.
	 *
	 * @param  Request  $request
	 * @param  int  $id
	 * @return Response
	 */
	public function storeSecret(Request $request, $id)
	{
		$user = User::findOrFail($id);

		$user->fill([
			'secret' => Crypt::encrypt($request->secret)
		])->save();
	}
}

Decrypting A Value

Of course, you may decrypt values using the decrypt method on the Crypt facade. If the value can not be properly decrypted, such as when the MAC is invalid, an Illuminate\Contracts\Encryption\DecryptException will be thrown:

use Illuminate\Contracts\Encryption\DecryptException;

try {
	$decrypted = Crypt::decrypt($encryptedValue);
} catch (DecryptException $e) {
	//
}