APP_KEY And You

Sep 17, 2018

Every time Laravel developers start or clone a Laravel app, generating the application key or APP_KEY is one of the most important first steps.

A recent Laravel security update fixed an issue with how APP_KEY is used. For someone to exploit this issue, they'd need to have access to the production APP_KEY. The simplest fix for the exploit is to rotate (change) your APP_KEY. That led some of us at Tighten to ask the question: What does the app key do? What is involved in rotating it? What are best practices for managing these keys for our Laravel applications?

In this post, we'll talk about what APP_KEY does and doesn't do, some common misconceptions about its relationship to user password hashing, and the simple steps to changing your APP_KEY safely without losing access to your data.

Laravel Security Fix

In early August, Laravel 5.5 and 5.6 received a security fix related to cookie serialization and encryption. On one hand, the fix is simple and most applications probably weren't affected. On the other hand, it's a serious security risk and reveals the need for our community to better understand how APP_KEYs work.

Exploiting this security issue requires someone to know your APP_KEY, which is why I’m going to walk you through the details of your key, why it’s important, and how to change it.

For information about the security fixes, see these resources:

Security update (5.6.30) release notes: https://laravel.com/docs/5.6/upgrade#upgrade-5.6.30
Security update (5.5.42) release notes: https://laravel.com/docs/5.5/upgrade#upgrade-5.5.42

What is `APP_KEY`?

The application key is a random, 32-character string stored in the APP_KEY key in your .env file. The Laravel installer generates one for you, so you'll only notice it missing when you clone an existing app.

You've probably seen this error before:

To create a new key, you could generate one yourself and paste it into your .env, or you can run php artisan key:generate to have Laravel create and insert one automatically for you.

Once your app is running, there's one place it uses the APP_KEY: cookies. Laravel uses the key for all encrypted cookies, including the session cookie, before handing them off to the user's browser, and it uses it to decrypt cookies read from the browser. This prevents the client from making changes to their cookies and granting themselves admin privileges or impersonating another user in your application. Encrypted cookies are an important security feature in Laravel.

All of this encryption and decryption is handled in Laravel by the Encrypter using PHP's built-in security tools, including OpenSSL. We won’t be looking closely at how that encryption works here, but if you want to learn more I’d encourage you to read more on the PHP implementation of OpenSSL and the openssl_encrypt function.

Common misconceptions about password hashing

One very common misconception in the Laravel community—one I held myself until recently—is that the APP_KEY is used to hash passwords. Thankfully, this isn't the case! I think this leads many people to assume that the APP_KEY is un-rotatable without breaking all of your users' logins.

Passwords are not encrypted, they are hashed.

Laravel's passwords are hashed using Hash::make() or bcrypt(), neither of which use APP_KEY. Let’s take a look at encryption and hashing in Laravel.

Encrypting vs. Hashing

There are two main cryptographic facades in Laravel: Crypt (symmetric encryption) and Hash (one-way cryptographic hashing). Passwords are hashed, and cookies are (optionally) encrypted. Let’s look at the differences.

Symmetric Encryption

Let’s say I want to send a secret message to my friend Arthur. We both agreed on a secret key the last time we were together:

$key = "dont-panic";

I want to send him a short message that only that key can decrypt. I’ll use my favorite industry standard, open source encryption function openssl_encrypt() (used by Laravel's Crypt) with our shared $key and have a plain-text encrypted string to send him:

$message = "So long and thanks for all the fish";
$key = "dont-panic";
$cipher = "AES-256-CBC";
echo openssl_encrypt($message, $cipher, $key);
 
// JJEK8L4G3BCfY0evXDRxUke2zqAzq6i7wL/Px4SjaEHXqt3x7hsj4+PhVQaH4ujX

I’ll send this secret to Arthur any way I want; since we’re the only two with the key, I’m not worried about anyone else reading the message.

fake tweet with encrypted string

When Arthur gets it, he’ll reverse the process using our secret key. This is the symmetric part of it: we’re able to encrypt and decrypt without losing information.

$secret = "JJEK8L4G3BCfY0evXDRxUke2zqAzq6i7wL/Px4SjaEHXqt3x7hsj4+PhVQaH4ujX";
$key = "dont-panic";
$cipher = "AES-256-CBC";
echo openssl_decrypt($secret, $cipher, $key);
 
// So long and thanks for all the fish

Laravel uses this same method for cookies, both the sender and receiver, using APP_KEY as the encryption key. Response cookies are encrypted, sent to the user, read back in a future request, and decrypted, all using the same application key.

One-Way Hash

Our example of symmetric encryption has lots of potential uses, but all of them involve needing to eventually decrypt the scrambled message.

But when it comes to something like user passwords, you should never have a way to decrypt them. Ever.

This means our Crypt methods won’t work, and therefore can’t be based on a key that we have. Instead, we need a hashing function, which should be:

Speedy: A computer should be able to generate a hash quickly
Deterministic: Hashing the same input always gives the same output
Seemingly random: Changing a single letter of the input should drastically change the output
Unique: The collision rate (different inputs hashing to the same output) should be very small
Hard to brute force: It should be difficult to hash all possible inputs to guess our original input

You’re likely already familiar with many one-way hashing algorithms: MD5 and SHA-1 are quick to compute, but not the most secure (they’re weak on items 4 and 5 above).

Laravel hashing implements the native PHP password_hash() function, defaulting to a hashing algorithm called bcrypt. For one-way hashing, it’s a great default, and you shouldn’t need to change it (though Laravel now offers a few other hashing methods, too).

use Illuminate\Support\Facades\Hash;
 
$password = "dont-panic";
echo Hash::make($password);
 
// $2y$10$hEEF0lv4spxnvw5O4XyLZ.QjCE1tCu8HjMpWhmCS89J0EcSW0XELu

If you’ve ever looked in the users table, this might look familiar to you. Here’s what it means:

$2y$ hashed using the blowfish algorithm (bcrypt)
10$ the “cost” factor (higher means the hash takes longer to compute)
hEEF0lv4spxnvw5O4XyLZ. a random “salt” of 22 characters
QjCE1tCu8HjMpWhmCS89J0EcSW0XELu the hash output

Since this is a one-way hash, we cannot decrypt it. All that we can do is test against it.

When the user with this password attempts to log in, Laravel hashes their password input and uses PHP’s password_verify() function to compare the new hash with the database hash:

use Illuminate\Support\Facades\Hash;
 
$input = request()->get('password'); // "dont-panic"
$hash = '$2y$10$hEEF0lv4spxnvw5O4XyLZ.QjCE1tCu8HjMpWhmCS89J0EcSW0XELu';
return Hash::check($input, $hash);
 
// true

You’ll notice that Laravel only needs a key (in this case, APP_KEY) when symmetric (reversible) encryption is needed. User password storage should never be reversible, and therefore doesn’t need APP_KEY at all.

But that doesn’t mean your key should be treated carelessly. Instead, treat it like any other production credential: use the same care and security as your MySQL password or MailChimp API key.

Rotating your key

Any good credential management strategy should include rotation: changing keys and passwords on a regular basis (e.g. every 6 months) or in specific situations (e.g. an employee leaves the company).

Thankfully, it is possible to rotate your APP_KEY; you just need to keep a few things in mind.

Multiple Servers

If you serve the same application from multiple servers, you’ll need to update the key on each server.

Existing user sessions (cookies)

Any users currently logged in to your application will have their sessions invalidated as soon as you change your APP_KEY. Schedule your key rotation at an optimal time to minimize inconvenience for your users.

Other data you’ve encrypted

Although the security of your cookies is the only place Laravel uses the APP_KEY as a framework, you may have custom code in your application that encrypts your data. If you have any uses of Laravel's encrypting features, make and test a plan to decrypt that data with your old key and re-encrypt it with the new key.

Setting a new `APP_KEY`

First, copy your existing APP_KEY somewhere else, just in case changing your key has unintended side effects.

Before you try rotating your APP_KEY on your production server, try rotating it on your local machine to make sure everything goes smoothly. When you're ready, run php artisan key:generate:

[jbathman my_app]# php artisan key:generate
**************************************
*     Application In Production!     *
**************************************
 
Do you really wish to run this command? (yes/no) [no]:
> yes
 
Application key [base64:x2SHH01+2R+vwv09YcrvXqdFJ+bbqgT9gW4njcYLjDE=] set successfully.

And that’s it! If you want to generate a key without modifying your .env file, include the --show flag:

[jbathman ~/my_app]# php artisan key:generate --show
base64:c3SzeMQZZHPT+eLQH6BnpDhw/uKH2N5zgM2x2a8qpcA=

Key Takeaways

Changing APP_KEY does not affect user passwords
Sessions (via cookies) will be invalidated if you change APP_KEY, logging out any current users
Don’t be afraid of your APP_KEY
You should have a strategy to regularly rotate APP_KEY along with your other credentials and keys
If your code has manually used Laravel's encrypter, you'll need to make a plan to decrypt its encrypted data with the old key and re-encrypt it with the new one.