암호화

번역일: 2026년 6월 20일

암호화

소개
설정
- 암호화 키 교체 (무중단)
암호화 사용법

소개

Laravel의 암호화 서비스는 OpenSSL을 기반으로 AES-256 및 AES-128 알고리즘을 사용해 값을 안전하게 암호화하고 복호화할 수 있는 간편한 인터페이스를 제공합니다. 암호화된 모든 값에는 MAC(Message Authentication Code)이 서명으로 포함되기 때문에, 암호화 이후에 값이 변조되더라도 복호화 시 이를 감지할 수 있습니다.

설정

암호화 기능을 사용하려면 먼저 config/app.php의 key 설정값이 올바르게 지정되어 있어야 합니다. 이 값은 .env 파일의 APP_KEY 환경 변수로 제어됩니다. 키 생성에는 반드시 php artisan key:generate 명령어를 사용하세요. 이 명령어는 PHP의 안전한 난수 생성기를 활용해 암호학적으로 안전한 키를 만들어 줍니다. 일반적으로 APP_KEY는 Laravel 설치 과정에서 자동으로 생성됩니다.

암호화 키 교체 (무중단)

애플리케이션의 암호화 키(APP_KEY)를 변경하면, 세션 쿠키를 포함한 모든 암호화된 쿠키가 무효화되어 기존에 로그인한 사용자가 모두 로그아웃됩니다. 또한 이전 키로 암호화된 데이터는 더 이상 복호화할 수 없게 됩니다.

이 문제를 완화하기 위해 Laravel은 APP_PREVIOUS_KEYS 환경 변수를 통해 이전 키 목록을 보관할 수 있는 기능을 제공합니다. 여러 개의 이전 키는 쉼표(,)로 구분해 나열합니다.

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

이 환경 변수가 설정되면 Laravel은 새 값을 암호화할 때 항상 현재 키(APP_KEY)를 사용합니다. 복호화 시에는 현재 키를 먼저 시도하고, 실패하면 APP_PREVIOUS_KEYS에 나열된 이전 키들을 순서대로 시도해 복호화에 성공할 때까지 반복합니다.

이 방식 덕분에 암호화 키를 교체하더라도 사용자가 서비스 중단 없이 애플리케이션을 계속 사용할 수 있습니다.

암호화 사용법

값 암호화

Crypt 파사드의 encryptString 메서드로 값을 암호화할 수 있습니다. 암호화에는 OpenSSL의 AES-256-CBC 방식이 사용되며, 결과값에는 MAC 서명이 포함됩니다. 이 서명 덕분에 악의적인 사용자가 암호화된 값을 변조할 경우 복호화가 차단됩니다.

<?php

namespace App\Http\Controllers;

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

class DigitalOceanTokenController extends Controller
{
    /**
     * 사용자의 DigitalOcean API 토큰을 저장합니다.
     */
    public function store(Request $request): RedirectResponse
    {
        $request->user()->fill([
            'token' => Crypt::encryptString($request->token),
        ])->save();

        return redirect('/secrets');
    }
}

값 복호화

Crypt 파사드의 decryptString 메서드로 암호화된 값을 복호화할 수 있습니다. MAC 서명이 유효하지 않거나 어떤 이유로든 복호화에 실패하면 Illuminate\Contracts\Encryption\DecryptException 예외가 발생하므로, 반드시 try-catch로 처리하세요.

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

try {
    $decrypted = Crypt::decryptString($encryptedValue);
} catch (DecryptException $e) {
    // 복호화 실패 처리
}

NOTE

복호화 예외는 키가 잘못되었거나 데이터가 변조된 경우 모두 발생할 수 있습니다. 사용자에게 노출되는 오류 메시지에 예외의 세부 내용을 그대로 포함하지 않도록 주의하세요.