암호화

업데이트됨

번역일: 2026년 6월 20일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 20일

암호화

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

소개

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

설정

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

NOTE

키를 직접 임의로 작성하지 마세요. 반드시 php artisan key:generate 명령을 사용하여 올바른 형식과 충분한 엔트로피를 가진 키를 생성해야 합니다.

암호화 키 교체 (무중단)

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

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

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

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

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

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) {
    // 복호화 실패 시 처리 로직
}