해싱

번역일: 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 알고리즘을 사용하는 경우, memory, time, threads 옵션으로 작업 비용을 세부 조정할 수 있습니다. 마찬가지로, 대부분의 애플리케이션에서는 기본값으로 충분합니다.

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

NOTE

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

비밀번호와 해시 값 비교

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

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

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

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

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

NOTE

이 기능은 서버 사양이 업그레이드되어 rounds 값을 높였거나, 보안 정책이 바뀐 경우에 유용합니다. 로그인 시점에 이 검사를 수행하고, 재해싱이 필요하면 갱신된 해시를 저장하는 방식으로 활용할 수 있습니다.

해시 알고리즘 검증

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

대부분의 애플리케이션에서는 이 동작이 올바른 보안 기본값입니다. 해싱 알고리즘이 달라지는 상황은 악의적인 공격의 징후일 수 있기 때문입니다.

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

HASH_VERIFY=false

NOTE

알고리즘 마이그레이션이 완료된 후에는 반드시 HASH_VERIFY를 다시 true(기본값)로 되돌리는 것을 권장합니다.