암호화

번역일: 2026년 6월 20일

암호화

소개
설정
- 암호화 키 안전하게 교체하기
Encrypter 사용하기

소개

Laravel의 암호화 서비스는 OpenSSL을 기반으로 AES-256 및 AES-128 알고리즘을 사용하여 값을 암호화하고 복호화할 수 있는 간결한 인터페이스를 제공합니다. 암호화된 모든 값에는 메시지 인증 코드(MAC)가 서명되어 있어, 한 번 암호화된 값은 외부에서 임의로 변조할 수 없습니다.

설정

Encrypter를 사용하기 전에 반드시 config/app.php의 key 설정 값을 지정해야 합니다. 이 값은 .env 파일의 APP_KEY 환경 변수로 관리됩니다. 암호학적으로 안전한 키를 생성하려면 다음 Artisan 명령어를 사용하세요.

php artisan key:generate

이 명령어는 PHP의 안전한 난수 생성기를 사용해 키를 만들고 .env 파일에 자동으로 기록합니다. 일반적으로 Laravel 설치 과정에서 이 키가 자동으로 생성됩니다.

NOTE

APP_KEY 값이 설정되지 않은 상태에서 암호화를 시도하면 오류가 발생합니다. 배포 환경에서도 반드시 이 값이 설정되어 있는지 확인하세요.

암호화 키 안전하게 교체하기

암호화 키를 변경하면 기존에 암호화된 모든 데이터를 더 이상 복호화할 수 없게 됩니다. 세션 쿠키도 Laravel에 의해 암호화되기 때문에, 키를 변경하는 순간 로그인 중인 모든 사용자의 세션이 강제로 만료됩니다.

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

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

이 환경 변수를 설정하면 Laravel은 값을 암호화할 때는 항상 현재 키(APP_KEY)를 사용하고, 복호화할 때는 현재 키를 먼저 시도한 뒤 실패하면 이전 키들을 순서대로 시도합니다.

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

Encrypter 사용하기

값 암호화

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이 발생합니다. 반드시 예외 처리를 함께 작성하세요.

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

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