Laravel 12.x ハッシュ

イントロダクションIntroduction

LaravelのHashファサードは、ユーザーパスワードを保存するための安全なBcryptおよびArgon2ハッシュを提供します。Laravelアプリケーションスターターキットのいずれかを使用している場合、デフォルトで登録と認証にBcryptが使用されます。The Laravel Hash facade[/docs/{{version}}/facades] provides secure Bcrypt and Argon2 hashing for storing user passwords. If you are using one of the Laravel application starter kits[/docs/{{version}}/starter-kits], Bcrypt will be used for registration and authentication by default.

Bcryptは、その「作業係数」が調整可能であるため、パスワードのハッシュに最適です。つまり、ハードウェアの能力が上がると、ハッシュの生成にかかる時間が長くなる可能性があります。パスワードをハッシュする場合は、遅いのが利点です。アルゴリズムがパスワードをハッシュするのに時間がかかるほど、悪意のあるユーザーがアプリケーションに対するブルートフォース攻撃で使用される可能性のあるすべての文字列ハッシュ値の「レインボーテーブル」を生成するのにかかる時間が長くなります。Bcrypt is a great choice for hashing passwords because its "work factor" is adjustable, which means that the time it takes to generate a hash can be increased as hardware power increases. When hashing passwords, slow is good. The longer an algorithm takes to hash a password, the longer it takes malicious users to generate "rainbow tables" of all possible string hash values that may be used in brute force attacks against applications.

設定Configuration

Laravelはデフォルトで、データのハッシュ化にbcryptハッシュドライバを使用します。しかし、argonやargon2idなど、他のハッシュドライバもサポートしています。By default, Laravel uses the bcrypt hashing driver when hashing data. However, several other hashing drivers are supported, including argon[https://en.wikipedia.org/wiki/Argon2] and argon2id[https://en.wikipedia.org/wiki/Argon2].

HASH_DRIVER環境変数を浸かり、アプリケーションのハッシュドライバを指定できます。しかし、Laravelのハッシュドライバオプションをすべてカスタマイズしたい場合は、config:publish Artisanコマンドを使用して、完全なhashing設定ファイルをリソース公開する必要があります。You may specify your application's hashing driver using the HASH_DRIVER environment variable. But, if you want to customize all of Laravel's hashing driver options, you should publish the complete hashing configuration file using the config:publish Artisan command:

php artisan config:publish hashing

基本的な使用法Basic Usage

パスワードのハッシュHashing Passwords

Hashファサードでmakeメソッドを呼び出すことにより、パスワードをハッシュすることができます。You may hash a password by calling the make method on the Hash facade:

<?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
    {
        // Validate the new password length...

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

        return redirect('/profile');
    }
}

Bcryptの作業係数の調整Adjusting The Bcrypt Work Factor

Bcryptアルゴリズムを使用している場合、makeメソッドを使用すると、roundsオプションを使用してアルゴリズムの作業係数を管理できます。ただし、Laravelが管理するデフォルトの作業係数は、ほとんどのアプリケーションで適切でしょう。If you are using the Bcrypt algorithm, the make method allows you to manage the work factor of the algorithm using the rounds option; however, the default work factor managed by Laravel is acceptable for most applications:

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

Argon2作業係数の調整Adjusting The Argon2 Work Factor

Argon2アルゴリズムを使用している場合、makeメソッドを使用すると、memory、time、threadsオプションを使用してアルゴリズムの作業要素を管理できます。ただし、Laravelが管理するデフォルト値は、ほとんどのアプリケーションで適切でしょう。If you are using the Argon2 algorithm, the make method allows you to manage the work factor of the algorithm using the memory, time, and threads options; however, the default values managed by Laravel are acceptable for most applications:

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

note Note: これらのオプションの詳細には、Argonハッシュに関するPHP公式ドキュメントを参照してください。[!NOTE] For more information on these options, please refer to the official PHP documentation regarding Argon hashing[https://secure.php.net/manual/en/function.password-hash.php].

パスワードがハッシュと一致するかの確認Verifying That a Password Matches a Hash

Hashファサードが提供するcheckメソッドを使用すると、指定するプレーンテキスト文字列が指定するハッシュに対応することを確認できます。The check method provided by the Hash facade allows you to verify that a given plain-text string corresponds to a given hash:

if (Hash::check('plain-text', $hashedPassword)) {
    // The passwords match...
}

パスワードを再ハッシュする必要があるかの判断Determining if a Password Needs to be Rehashed

Hashファサードが提供するneedsRehashメソッドを使用すると、パスワードがハッシュされてから、ハッシャーによって使用される作業要素が変更されたかどうかを判別できます。一部のアプリケーションは、アプリケーションの認証プロセス中にこのチェックを実行することを選択しています。The needsRehash method provided by the Hash facade allows you to determine if the work factor used by the hasher has changed since the password was hashed. Some applications choose to perform this check during the application's authentication process:

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

ハッシュアルゴリズムの確認Hash Algorithm Verification

ハッシュアルゴリズムの操作を防ぐために、LaravelのHash::checkメソッドは最初に、指定したハッシュがアプリケーションで選択しているハッシュアルゴリズムを使って生成されているかを確認します。アルゴリズムが異なる場合、RuntimeException例外を投げますTo prevent hash algorithm manipulation, Laravel's Hash::check method will first verify the given hash was generated using the application's selected hashing algorithm. If the algorithms are different, a RuntimeException exception will be thrown.

これはほとんどのアプリケーションで期待される動作であり、ハッシュアルゴリズムが変更されることは期待されておらず、異なるアルゴリズムは悪意のある攻撃の兆候となり得ます。しかし、あるアルゴリズムから別のアルゴリズムに移行する場合など、アプリケーション内で複数のハッシュアルゴリズムをサポートする必要がある場合は、HASH_VERIFY環境変数をfalseに設定することで、ハッシュアルゴリズムの検証を無効にできます。This is the expected behavior for most applications, where the hashing algorithm is not expected to change and different algorithms can be an indication of a malicious attack. However, if you need to support multiple hashing algorithms within your application, such as when migrating from one algorithm to another, you can disable hash algorithm verification by setting the HASH_VERIFY environment variable to false:

HASH_VERIFY=false