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

# Chiffrement (Encryption)

> Comment chiffrer et déchiffrer des valeurs en AES-256-CBC avec la façade Crypt de Laravel. Génération d'APP_KEY, casts de modèles et stockage sécurisé d'informations personnelles.

## Qu'est-ce que la façade Crypt

Le service de chiffrement de Laravel utilise **OpenSSL** avec AES-256-CBC (ou AES-128-CBC) et propose une interface simple pour chiffrer et déchiffrer des valeurs.

Toutes les valeurs chiffrées par Laravel sont signées par un **Message Authentication Code (MAC)**.
Le déchiffrement échoue donc si la valeur a été altérée.

```mermaid theme={null}
flowchart LR
    A["Données en clair"] -->|"Crypt::encryptString()"| B["Valeur chiffrée<br>(signée par MAC)"]
    B -->|"Crypt::decryptString()"| A
    B -->|Altération détectée| C["DecryptException"]
```

***

## Configuration

### Génération d'APP\_KEY

Avant d'utiliser le chiffrement, la clé `key` de `config/app.php` doit être définie.
Sa valeur provient de la variable d'environnement `APP_KEY`.

Générez une clé sûre avec `php artisan key:generate`.
Une clé cryptographiquement sûre est produite via le générateur d'aléa sécurisé de PHP.

```shell theme={null}
php artisan key:generate
```

À l'installation de Laravel, la clé est généralement générée automatiquement et stockée dans `.env`.

```ini theme={null}
APP_KEY=base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY=
```

<Warning>
  Ne divulguez jamais `APP_KEY`. Si elle fuit, toutes vos données chiffrées peuvent être déchiffrées.
</Warning>

### Rotation de la clé de chiffrement

Changer la clé déconnecte toutes les sessions utilisateur authentifiées, car Laravel chiffre l'ensemble des cookies, y compris ceux de session.

De plus, les données chiffrées avec l'ancienne clé ne peuvent plus être déchiffrées.

Pour atténuer cela, listez les anciennes clés séparées par une virgule dans `APP_PREVIOUS_KEYS`.

```ini theme={null}
APP_KEY="base64:J63qRTDLub5NuZvP+kb8YIorGS6qFYHKVo6u7179stY="
APP_PREVIOUS_KEYS="base64:2nLsGFGzyoae2ax3EF2Lyq/hH6QghBGLIq5uL+Gp8/w="
```

Laravel chiffre toujours avec la clé actuelle mais, lors du déchiffrement, essaie les anciennes clés en cas d'échec.
Cela permet une rotation sans interruption pour les utilisateurs.

***

## Chiffrement

Utilisez `encryptString` de la façade `Crypt` pour chiffrer une valeur.
La valeur chiffrée est produite avec OpenSSL et AES-256-CBC, et signée par MAC.

```php theme={null}
<?php

namespace App\Http\Controllers;

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

class DigitalOceanTokenController extends Controller
{
    /**
     * Stocke le token API de l'utilisateur.
     */
    public function store(Request $request): RedirectResponse
    {
        $request->user()->fill([
            'token' => Crypt::encryptString($request->token),
        ])->save();

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

<Tip>
  `encryptString` chiffre la chaîne **sans** sérialisation. Pour chiffrer un objet ou un tableau, utilisez `encrypt`.
</Tip>

| Méthode                        | Usage                                     |
| ------------------------------ | ----------------------------------------- |
| `Crypt::encryptString($value)` | Chiffre une chaîne telle quelle           |
| `Crypt::encrypt($value)`       | Sérialise puis chiffre (tableaux, objets) |

***

## Déchiffrement

Utilisez `decryptString` pour déchiffrer une valeur.
Si le MAC est invalide (ou en cas d'échec), une `DecryptException` est levée.

```php theme={null}
use Illuminate\Contracts\Encryption\DecryptException;
use Illuminate\Support\Facades\Crypt;

try {
    $decrypted = Crypt::decryptString($encryptedValue);
} catch (DecryptException $e) {
    // Traitement en cas d'échec
    abort(400, 'Données invalides.');
}
```

| Méthode                        | Usage                                       |
| ------------------------------ | ------------------------------------------- |
| `Crypt::decryptString($value)` | Déchiffre en chaîne                         |
| `Crypt::decrypt($value)`       | Déchiffre et désérialise (tableaux, objets) |

***

## Cast de modèle

Sur un modèle Eloquent, le cast `encrypted` automatise le chiffrement/déchiffrement d'un attribut.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected function casts(): array
    {
        return [
            'secret_note'    => 'encrypted',           // Chiffrement d'une chaîne
            'profile_data'   => 'encrypted:array',     // Tableau chiffré
            'preferences'    => 'encrypted:collection',// Collection chiffrée
            'metadata'       => 'encrypted:object',    // Objet chiffré
            'settings'       => 'encrypted:json',      // JSON chiffré
        ];
    }
}
```

Avec ce cast, les valeurs sont automatiquement chiffrées/déchiffrées à l'assignation et à la lecture.

```php theme={null}
// Chiffré automatiquement avant enregistrement
$user->secret_note = 'Note secrète';
$user->save();

// Déchiffré automatiquement à la lecture
echo $user->secret_note; // 'Note secrète'
```

<Info>
  Les casts `encrypted:*` utilisent en interne `Crypt::encrypt` et `Crypt::decrypt`.
  Utilisez le type de colonne `text` ou `longText` en base.
</Info>

***

## Exemple : stockage chiffré d'informations personnelles

Modèle typique de stockage sécurisé d'informations personnelles (numéro national, numéro de carte…).

### Migration

```php theme={null}
Schema::create('profiles', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained();
    $table->text('my_number')->nullable();     // Chiffré stocké en text
    $table->text('bank_account')->nullable();
    $table->timestamps();
});
```

### Modèle

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Profile extends Model
{
    protected $fillable = ['user_id', 'my_number', 'bank_account'];

    protected function casts(): array
    {
        return [
            'my_number'    => 'encrypted',
            'bank_account' => 'encrypted',
        ];
    }
}
```

### Contrôleur

```php theme={null}
use App\Models\Profile;
use Illuminate\Http\Request;

class ProfileController extends Controller
{
    public function store(Request $request)
    {
        $request->validate([
            'my_number'    => ['required', 'string'],
            'bank_account' => ['required', 'string'],
        ]);

        // Le modèle chiffre automatiquement lors de la sauvegarde
        Profile::create([
            'user_id'      => $request->user()->id,
            'my_number'    => $request->my_number,
            'bank_account' => $request->bank_account,
        ]);

        return redirect('/profile');
    }

    public function show(Request $request)
    {
        $profile = $request->user()->profile;

        // Le modèle déchiffre automatiquement à la lecture
        return view('profile.show', ['profile' => $profile]);
    }
}
```

***

## Récapitulatif

| Objectif                       | Méthode                                  |
| ------------------------------ | ---------------------------------------- |
| Générer APP\_KEY               | `php artisan key:generate`               |
| Chiffrer une chaîne            | `Crypt::encryptString($value)`           |
| Déchiffrer une chaîne          | `Crypt::decryptString($value)`           |
| Chiffrer un tableau/objet      | `Crypt::encrypt($value)`                 |
| Cast automatique d'un attribut | `'column' => 'encrypted'`                |
| Rotation de clé                | Ajouter l'ancienne à `APP_PREVIOUS_KEYS` |

## Prochaines étapes

<Columns cols={2}>
  <Card title="Hachage" icon="lock" href="/fr/hashing">
    Apprenez à hacher et vérifier les mots de passe en toute sécurité.
  </Card>

  <Card title="Autorisation" icon="shield" href="/fr/authorization">
    Contrôlez l'accès à l'aide des policies et des gates.
  </Card>
</Columns>


## Related topics

- [Crypto — chiffrement AT Protocol](/fr/packages/laravel-bluesky/crypto.md)
- [Authentification OAuth 2.0 - Google Sheets API for Laravel](/fr/packages/laravel-google-sheets/oauth.md)
- [Configuration](/fr/configuration.md)
- [Routage](/fr/routing.md)
- [Structure des répertoires](/fr/directory-structure.md)