해싱

업데이트됨

번역일: 2026년 6월 20일

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

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

해싱

소개
설정
기본 사용법
해시 알고리즘 검증

소개

Laravel의 Hash 파사드는 사용자 비밀번호를 안전하게 저장하기 위한 Bcrypt 및 Argon2 해싱 기능을 제공합니다. Laravel 스타터 킷을 사용하고 있다면, 회원가입과 인증 과정에서 기본적으로 Bcrypt가 사용됩니다.

Bcrypt는 비밀번호 해싱에 매우 적합한 알고리즘입니다. 핵심 이유는 워크 팩터(work factor) 를 조절할 수 있다는 점입니다. 하드웨어 성능이 향상될수록 해시 생성에 걸리는 시간을 늘릴 수 있어, 시간이 지나도 보안 수준을 유지할 수 있습니다. 비밀번호 해싱에서는 "느릴수록 안전하다"는 원칙이 적용됩니다. 알고리즘이 느릴수록 공격자가 모든 가능한 문자열의 해시 값을 미리 계산해 둔 "레인보우 테이블"을 생성하는 데 걸리는 시간도 그만큼 길어지기 때문입니다.

설정

Laravel은 기본적으로 bcrypt 해싱 드라이버를 사용합니다. 이 외에도 argon 및 argon2id 드라이버도 지원합니다.

해싱 드라이버는 HASH_DRIVER 환경 변수로 간단히 변경할 수 있습니다. 드라이버 옵션을 더 세부적으로 조정하려면 아래 Artisan 명령어로 해싱 설정 파일을 프로젝트에 게시하세요.

php artisan config:publish hashing

기본 사용법

비밀번호 해싱

Hash 파사드의 make 메서드를 사용해 비밀번호를 해싱할 수 있습니다.

<?php

namespace App\Http\Controllers;

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

class PasswordController extends Controller
{
    /**
     * 사용자 비밀번호를 변경합니다.
     */
    public function update(Request $request): RedirectResponse
    {
        // 새 비밀번호 유효성 검사...

        $request->user()->fill([
            'password' => Hash::make($request->newPassword)
        ])->save();

        return redirect('/profile');
    }
}

Bcrypt 워크 팩터 조정

Bcrypt 알고리즘을 사용하는 경우, make 메서드의 rounds 옵션으로 워크 팩터를 조정할 수 있습니다. Laravel의 기본값은 대부분의 애플리케이션에 적합합니다.

$hashed = Hash::make('password', [
    'rounds' => 12,
]);

Argon2 워크 팩터 조정

Argon2 알고리즘을 사용하는 경우, memory, time, threads 옵션으로 워크 팩터를 조정할 수 있습니다. 마찬가지로 Laravel의 기본값은 대부분의 애플리케이션에 적합합니다.

$hashed = Hash::make('password', [
    'memory' => 1024,
    'time' => 2,
    'threads' => 2,
]);

NOTE

각 옵션에 대한 자세한 내용은 PHP 공식 문서의 Argon 해싱 설명을 참고하세요.

비밀번호와 해시 값 비교

Hash 파사드의 check 메서드를 사용하면 입력된 평문 문자열이 주어진 해시 값과 일치하는지 확인할 수 있습니다.

if (Hash::check('plain-text', $hashedPassword)) {
    // 비밀번호가 일치합니다...
}

재해싱 필요 여부 확인

Hash 파사드의 needsRehash 메서드는 기존에 해싱된 비밀번호의 워크 팩터가 현재 설정과 달라졌는지 확인합니다. 보안 정책이 변경된 경우, 사용자가 로그인할 때마다 이 검사를 수행하는 패턴을 많이 사용합니다.

if (Hash::needsRehash($hashed)) {
    $hashed = Hash::make('plain-text');
}

NOTE

이 방법은 로그인 시점에 평문 비밀번호를 일시적으로 사용할 수 있는 타이밍을 활용합니다. 이후에는 평문 비밀번호를 저장하지 않으므로 안전합니다.

해시 알고리즘 검증

Laravel의 Hash::check 메서드는 비밀번호를 비교하기 전에, 주어진 해시 값이 애플리케이션에서 현재 설정된 알고리즘으로 생성된 것인지 먼저 확인합니다. 알고리즘이 다를 경우 RuntimeException 예외가 발생합니다.

이는 대부분의 애플리케이션에서 의도된 동작입니다. 해싱 알고리즘이 갑자기 달라지는 상황은 악의적인 공격의 징후일 수 있기 때문입니다.

다만, Bcrypt에서 Argon2로 마이그레이션하는 경우처럼 여러 알고리즘을 동시에 지원해야 한다면, HASH_VERIFY 환경 변수를 false로 설정해 이 검증을 비활성화할 수 있습니다.

HASH_VERIFY=false

NOTE

알고리즘 검증을 비활성화한 경우, 마이그레이션이 완료된 후에는 반드시 다시 활성화(true 또는 해당 변수 제거)하는 것을 권장합니다.