> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Hachage (Hashing)

> Comment hacher et vérifier les mots de passe en toute sécurité avec la façade Hash de Laravel. Configuration et utilisation des algorithmes bcrypt et Argon2.

## Qu'est-ce que le hachage

Le hachage (hashing) est le processus qui transforme des données en clair, comme un mot de passe, en une chaîne de longueur fixe via une conversion à sens unique.
La même entrée produit toujours le même hachage, mais il est impossible de reconstituer le texte clair à partir d'un hachage.

La façade `Hash` de Laravel prend en charge les algorithmes **bcrypt** et **Argon2** pour stocker les mots de passe en toute sécurité.

### Comparaison des algorithmes

| Algorithme   | Caractéristiques                                                                    | Usage recommandé                            |
| ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------- |
| **bcrypt**   | Coût de calcul ajustable via le work factor (rounds). Par défaut                    | Applications web classiques                 |
| **argon2i**  | Mémoire, temps et threads ajustables. Résistant aux attaques par canaux auxiliaires | Contextes à haute sécurité                  |
| **argon2id** | Hybride argon2i/argon2d. Recommandé par PHC                                         | Utilisation d'Argon2 dans un nouveau projet |

<Info>
  Le « work factor » de bcrypt contrôle le temps de calcul du hachage. Plus le hachage est lent, plus il résiste aux attaques par force brute. À mesure que le matériel s'améliore, augmentez le work factor pour maintenir la sécurité.
</Info>

### Flux de hachage et vérification

```mermaid theme={null}
flowchart LR
    A[Mot de passe en clair] -->|Hash::make| B["Valeur hachée<br>enregistrée en DB"]
    C[Saisie lors de la connexion] -->|Hash::check| D{Correspond ?}
    B --> D
    D -->|true| E[Authentification réussie]
    D -->|false| F[Authentification échouée]
```

***

## Configuration

Par défaut, Laravel utilise le driver `bcrypt`. Modifiez-le via la variable d'environnement `HASH_DRIVER`.

```ini theme={null}
# .env
HASH_DRIVER=bcrypt  # bcrypt / argon / argon2id
```

Pour personnaliser la configuration de hachage, publiez le fichier de configuration avec `config:publish`.

```shell theme={null}
php artisan config:publish hashing
```

Après publication, modifiez le work factor par défaut et autres options dans `config/hashing.php`.

***

## Utilisation de base

### Hacher un mot de passe

Passez le mot de passe en clair à `Hash::make()` pour obtenir un hachage. Stockez cette valeur en base de données.

```php theme={null}
<?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->validate([
            'password' => ['required', 'min:8', 'confirmed'],
        ]);

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

        return redirect('/profile');
    }
}
```

<Warning>
  Stockez la valeur hachée en base, mais ne stockez jamais le mot de passe en clair.
</Warning>

### Ajuster le work factor de bcrypt

L'option `rounds` ajuste le coût de calcul. Une valeur élevée est plus sûre, mais plus lente.
La valeur par défaut (12) convient à la plupart des applications.

```php theme={null}
$hashed = Hash::make('plain-text-password', [
    'rounds' => 14,
]);
```

### Ajuster le work factor d'Argon2

Avec Argon2, ajustez le coût via `memory`, `time` et `threads`.

```php theme={null}
$hashed = Hash::make('plain-text-password', [
    'memory'  => 65536, // en KiB
    'time'    => 4,
    'threads' => 2,
]);
```

| Option    | Description            | Défaut |
| --------- | ---------------------- | ------ |
| `memory`  | Mémoire utilisée (KiB) | 65536  |
| `time`    | Nombre d'itérations    | 4      |
| `threads` | Nombre de threads      | 1      |

<Tip>
  Consultez la [documentation officielle PHP](https://secure.php.net/manual/fr/function.password-hash.php) pour le détail des options d'Argon2.
</Tip>

***

## Vérification du mot de passe

`Hash::check()` permet de vérifier qu'un mot de passe en clair correspond à un hachage stocké.
Exemple typique lors du processus de connexion.

```php theme={null}
use Illuminate\Support\Facades\Hash;

if (Hash::check($request->password, $user->password)) {
    // Le mot de passe correspond
} else {
    // Le mot de passe ne correspond pas
}
```

Lors de l'utilisation de `Auth::attempt()`, cette vérification est automatique et vous n'avez pas besoin de l'appeler directement.
`Hash::check()` est utile lorsque vous devez vérifier manuellement le mot de passe courant.

```php theme={null}
// Exemple : vérification du mot de passe actuel dans un formulaire de changement
if (! Hash::check($request->current_password, $request->user()->password)) {
    return back()->withErrors(['current_password' => 'Le mot de passe actuel est incorrect.']);
}
```

***

## Détermination du besoin de re-hachage

`Hash::needsRehash()` indique si le work factor utilisé lors de la génération du hachage diffère de la configuration actuelle.
Cela sert à mettre à jour les hachages existants après un changement de work factor.

```php theme={null}
use Illuminate\Support\Facades\Hash;

if (Hash::needsRehash($user->password)) {
    $user->update([
        'password' => Hash::make($plainTextPassword),
    ]);
}
```

Exemple de re-hachage lors d'une connexion réussie.

```mermaid theme={null}
flowchart TD
    A[Connexion réussie] --> B{needsRehash ?}
    B -->|true| C[Re-hache avec le nouveau<br>work factor et sauvegarde]
    B -->|false| D[Poursuit normalement]
    C --> D
```

```php theme={null}
// Re-hachage dans le traitement de connexion
if (Auth::attempt($credentials)) {
    if (Hash::needsRehash(Auth::user()->password)) {
        Auth::user()->update([
            'password' => Hash::make($credentials['password']),
        ]);
    }

    return redirect()->intended('/dashboard');
}
```

<Tip>
  Réévaluez régulièrement le work factor pour suivre l'évolution du matériel et maintenir votre niveau de sécurité. Grâce à `needsRehash()`, vous pouvez profiter des connexions utilisateur pour mettre à jour naturellement les mots de passe.
</Tip>

***

## Vérification de l'algorithme de hachage

Par défaut, `Hash::check()` vérifie que le hachage a été généré avec l'algorithme actuellement configuré.
Si l'algorithme diffère, une `RuntimeException` est lancée.

Cela protège contre des attaques par altération de l'algorithme.

Si vous devez prendre en charge plusieurs algorithmes simultanément (migration en cours), vous pouvez désactiver cette vérification en réglant `HASH_VERIFY` sur `false`.

```ini theme={null}
# .env
HASH_VERIFY=false
```

<Warning>
  Régler `HASH_VERIFY=false` désactive la vérification d'algorithme. Ne l'utilisez que durant la période de migration et remettez `true` (valeur par défaut) une fois la migration terminée.
</Warning>

***

## Récapitulatif

| Objectif                                 | Méthode                                |
| ---------------------------------------- | -------------------------------------- |
| Hacher un mot de passe                   | `Hash::make($password)`                |
| Vérifier un hachage                      | `Hash::check($plain, $hash)`           |
| Vérifier si un re-hachage est nécessaire | `Hash::needsRehash($hash)`             |
| Changer le driver de hachage             | Variable d'environnement `HASH_DRIVER` |
| Désactiver la vérification d'algorithme  | `HASH_VERIFY=false`                    |

## Prochaines étapes

<Card title="Introduction à l'authentification" icon="lock" href="/fr/authentication">
  Découvrez la vue d'ensemble de l'authentification, notamment l'implémentation de la connexion avec `Hash::check()`.
</Card>


## Related topics

- [Core — opérations AT Protocol de base](/fr/packages/laravel-bluesky/core.md)
- [Chiffrement (Encryption)](/fr/encryption.md)
- [Génération d'URL](/fr/urls.md)
- [Laravel Fortify et les starter kits](/fr/advanced/fortify.md)
- [Casts personnalisés Eloquent](/fr/advanced/eloquent-casts.md)