encryption.md

Encryption

• Introduction
• Configuration
  • Gracefully Rotating Encryption Keys
• Using the Encrypter
• Credits

Introduction

Hypervel's encryption services provide a simple, convenient interface for encrypting and decrypting text via OpenSSL using AES-256 and AES-128 encryption. All of Hypervel's encrypted values are authenticated so that their underlying value cannot be modified or tampered with once encrypted. CBC encrypted values are signed using a message authentication code (MAC), while GCM encrypted values use an authentication tag.

Configuration

Before using Hypervel's encrypter, you must set the key configuration option in your config/app.php configuration file. This configuration value is driven by the APP_KEY environment variable. You should use the php artisan key:generate command to generate this variable's value since the key:generate command will use PHP's secure random bytes generator to build a cryptographically secure key for your application. Typically, the value of the APP_KEY environment variable will be generated for you during Hypervel's installation.

Hypervel supports AES-128-CBC, AES-256-CBC, AES-128-GCM, and AES-256-GCM. By default, Hypervel uses the AES-256-CBC cipher.

To prevent key:generate from running in production, call the command's prohibit method from your AppServiceProvider's boot method. This also prevents using --force or --show:

use Hypervel\Encryption\Commands\KeyGenerateCommand;

KeyGenerateCommand::prohibit($this->app->isProduction());

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, is encrypted by Hypervel. In addition, it will no longer be possible to decrypt any data that was encrypted with your previous encryption key.

To mitigate this issue, Hypervel allows you to list your previous encryption keys in your application's APP_PREVIOUS_KEYS environment variable. This variable may contain a comma-delimited list of all of your previous encryption keys:

APP_KEY="base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY="
APP_PREVIOUS_KEYS="base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w="

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

Previous keys allow existing encrypted data and cookies to remain readable after key rotation. However, users who rely on remember cookies, or whose sessions are validated by the AuthenticateSession middleware, will need to log in again.

Using the Encrypter

Encrypting a Value

You may encrypt a value using the encryptString method provided by the Crypt facade. All encrypted values are encrypted using OpenSSL and the configured cipher. Furthermore, encrypted values are authenticated to prevent the decryption of any values that have been tampered with by malicious users:

<?php

namespace App\Http\Controllers;

use Hypervel\Http\RedirectResponse;
use Hypervel\Http\Request;
use Hypervel\Support\Facades\Crypt;

class DigitalOceanTokenController extends Controller
{
    /**
     * Store a DigitalOcean API token for the user.
     */
    public function store(Request $request): RedirectResponse
    {
        $request->user()->fill([
            'token' => Crypt::encryptString($request->token),
        ])->save();

        return redirect('/secrets');
    }
}

Decrypting a Value

You may decrypt values using the decryptString method provided by the Crypt facade. If the value cannot be properly decrypted, such as when the encrypted payload cannot be authenticated, a Hypervel\Contracts\Encryption\DecryptException will be thrown:

use Hypervel\Contracts\Encryption\DecryptException;
use Hypervel\Support\Facades\Crypt;

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

Credits

Hypervel Encryption began as a port of Laravel Encryption and has been adapted for Hypervel's framework architecture and coroutine runtime.