해싱

번역일: 2026년 6월 20일

해싱

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

소개

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

Bcrypt는 비밀번호 해싱에 매우 적합한 알고리즘입니다. 핵심 이유는 "작업 인수(work factor)"를 조절할 수 있다는 점인데, 이를 통해 하드웨어 성능이 향상될수록 해시 생성에 걸리는 시간을 늘릴 수 있습니다. 비밀번호 해싱에서는 느릴수록 좋습니다. 알고리즘이 해시를 생성하는 데 오래 걸릴수록, 공격자가 브루트 포스 공격에 사용하는 "레인보우 테이블"을 만드는 데도 그만큼 더 많은 시간이 필요하기 때문입니다.

설정

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

해싱 드라이버는 HASH_DRIVER 환경 변수로 간단히 변경할 수 있습니다. 드라이버 옵션을 세부적으로 커스터마이징하고 싶다면, 아래 Artisan 명령어로 hashing 설정 파일을 프로젝트에 게시하세요:

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('비밀번호', [
    'rounds' => 12,
]);

Argon2 작업 인수 조정

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

$hashed = Hash::make('비밀번호', [
    'memory' => 1024,
    'time' => 2,
    'threads' => 2,
]);

NOTE

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

비밀번호와 해시 일치 검증

Hash 파사드의 check 메서드를 사용하면, 입력된 평문 문자열이 특정 해시와 일치하는지 확인할 수 있습니다:

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

비밀번호 재해싱 필요 여부 확인

Hash 파사드의 needsRehash 메서드는 비밀번호가 해싱된 이후 작업 인수가 변경되었는지 확인합니다. 일부 애플리케이션에서는 인증 과정 중 이 검사를 수행하기도 합니다:

if (Hash::needsRehash($hashed)) {
    $hashed = Hash::make('평문-비밀번호');
}

NOTE

이 패턴은 로그인 시 사용자가 입력한 평문 비밀번호에 접근할 수 있는 타이밍에 활용하면 효과적입니다. 로그인에 성공한 직후 needsRehash로 확인하고, 필요하면 즉시 재해싱하여 저장하는 방식을 권장합니다.

해시 알고리즘 검증

해시 알고리즘 조작을 방지하기 위해, Laravel의 Hash::check 메서드는 주어진 해시가 애플리케이션에 설정된 해싱 알고리즘으로 생성된 것인지 먼저 확인합니다. 알고리즘이 다를 경우 RuntimeException 예외가 발생합니다.

이는 대부분의 애플리케이션에서 기대하는 동작입니다. 일반적으로 해싱 알고리즘은 변경되지 않으며, 서로 다른 알고리즘이 감지된다면 악의적인 공격의 징후일 수 있기 때문입니다.

단, 한 알고리즘에서 다른 알고리즘으로 마이그레이션하는 등 여러 해싱 알고리즘을 동시에 지원해야 하는 상황이라면, HASH_VERIFY 환경 변수를 false로 설정하여 알고리즘 검증을 비활성화할 수 있습니다:

HASH_VERIFY=false