APP_KEY And You
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 cookies serialization and encryption. On one hand, the fix is simple and most applications probably weren't affected. On the other hand, it's serious security risk, and reveals the need for our community to better understand how
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: Upgrade Guide - Laravel - The PHP Framework For Web Artisans
- Security update (5.5.42) release notes: Upgrade Guide - Laravel - The PHP Framework For Web Artisans
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
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
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.
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.
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.
Our example for 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
QjCE1tCu8HjMpWhmCS89J0EcSW0XELuthe 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 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.
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
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
[jbathman ~/my_app]# php artisan key:generate --show base64:c3SzeMQZZHPT+eLQH6BnpDhw/uKH2N5zgM2x2a8qpcA=
APP_KEYdoes 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
- You should have a strategy to regularly rotate
APP_KEYalong 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.