
# パスワードエンコーダー

`PasswordEncoder` は、パスワードを保存用のハッシュに変え (`encode`)、入力されたパスワードを保存されたハッシュに対してチェックします (`matches`)。推奨されるのは `PasswordEncoderFactories.createDelegatingPasswordEncoder()` のデリゲーティングエンコーダーです。`{argon2}` ハッシュを書き、サポートされるすべての形式を読むため、既存のパスワードを壊さずにアルゴリズムを変えられます。

## 使う理由

パスワードは、そのままでも高速なハッシュでも、決して保存してはいけません。漏洩した SHA-256 ハッシュのテーブルは数時間で解読されます。パスワードハッシュは意図的に遅く、ソルト付きで (同じパスワードを持つ二人のユーザーが異なるハッシュを得ます)、調整可能です。形式は Spring Security のものなので、Dart のサービスと Java のサービスでユーザーテーブルを共有できます。一方で作ったハッシュは他方で検証できます。

## 例

```dart
// 登録: パスワードではなくハッシュを保存する。
final encoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();
final stored = encoder.encode(form.password); // {argon2}$argon2id$v=19$m=16384,t=2,p=1$...

// ログインのチェック (DaoAuthenticationProvider が代わりに行う)。
final ok = encoder.matches(typed, stored);
```

どこでも使うには Bean として宣言します。なくても、自動構成は同じデリゲーティングエンコーダーを使います。

```dart
@Bean()
PasswordEncoder passwordEncoder() => PasswordEncoderFactories.createDelegatingPasswordEncoder();
```

## インターフェース

| メソッド | 意味 |
|---|---|
| `encode(raw)` | 新しいランダムなソルトによるハッシュ。二回呼ぶと、どちらも一致する異なるテキストを返す。遅いので、リクエストの経路のループの中で使ってはいけない。 |
| `matches(raw, encoded)` | `raw` がパスワードかどうか。Spring Security 7 と同じく、空の `raw` (空のパスワードでは決してログインできない) と、存在しない、空の、または不正な形式のハッシュでは `false`。比較は、ハッシュのどこが異なっても同じ時間がかかる。 |
| `upgradeEncoding(encoded)` | ハッシュがより弱い設定で作られており、置き換えるべきかどうか。 |

## エンコーダー

| エンコーダー | ID | デフォルト (`defaultsForSpringSecurity()`) |
|---|---|---|
| `Argon2PasswordEncoder` | `{argon2}` | Argon2id、16 MiB のメモリ、2 パス、1 レーン、16 バイトのソルト、32 バイトのハッシュ |
| `Pbkdf2PasswordEncoder` | `{pbkdf2}` | HMAC-SHA256、310 000 回の反復、16 バイトのソルト、256 ビットのハッシュ、シークレットなし |
| `SCryptPasswordEncoder` | `{scrypt}` | N = 65 536、r = 8、p = 1、32 バイトのハッシュ、16 バイトのソルト |
| `NoOpPasswordEncoder` | `{noop}` | パスワードそのまま。開発専用 |
| `DelegatingPasswordEncoder` | | 各ハッシュに `{id}` を前置し、その ID のエンコーダーでチェックする |

デフォルトは、各アルゴリズムについての Spring Security の `defaultsForSpringSecurity_v5_8` です。

### 独自の設定

```dart
final argon2 = Argon2PasswordEncoder(
  saltLength: 16,
  hashLength: 32,
  parallelism: 1,
  memory: 65536,       // KiB: 主なコストの調整つまみ
  iterations: 3,
);

final pbkdf2 = Pbkdf2PasswordEncoder(
  saltLength: 16,
  iterations: 600000,
  secret: pepper,                                 // ユーザーテーブルの外に保持する値
  algorithm: Pbkdf2Algorithm.pbkdf2WithHmacSha512,
);

final scrypt = SCryptPasswordEncoder(
  cpuCost: 32768,      // 65 536 までの 2 のべき乗
  memoryCost: 8,
  parallelization: 1,
  keyLength: 32,
  saltLength: 16,
);
```

- Argon2 は、8 バイト未満のソルト、16 バイト未満のハッシュ、1 未満の並列度や反復回数、レーンあたり 8 KiB 未満のメモリを拒否します。
- PBKDF2 のハッシュは、どの設定で作られたかを示しません。エンコーダーは自身の設定で作られたハッシュしかチェックできず、`upgradeEncoding` は弱いものを検出できません。`secret` は、Spring と同じくソルトに付け加えるペッパーです。
- scrypt は、コストが 65 536 を超えるか、256 バイトより長いハッシュの保存値を拒否します。そのため、壊れたハッシュが一つのログインを長時間実行させることはできません。

## デリゲーティングエンコーダー

`PasswordEncoderFactories.createDelegatingPasswordEncoder()` は Spring のデフォルトで `{argon2}` ハッシュを書き、`{argon2}`、`{pbkdf2}`、`{scrypt}`、その `@SpringSecurity_v5_8` 版 (`{pbkdf2@SpringSecurity_v5_8}`)、`{noop}` をチェックします。

ID を自分で選ぶには、組み立てます。

```dart
final encoder = DelegatingPasswordEncoder('argon2', {
  'argon2': Argon2PasswordEncoder.defaultsForSpringSecurity(),
  'noop': const NoOpPasswordEncoder(),
});
```

- `{id}` のない保存されたハッシュ、またはどのエンコーダーも持たない ID のハッシュでは、`defaultPasswordEncoderForMatches` が設定されていない限り、`matches` が `ArgumentError` を投げます。これは誤ったパスワードではなく、設定の誤りです。`DaoAuthenticationProvider` はログインを拒否します。
- `{bcrypt}` ハッシュには専用のエラーメッセージがあります。BCrypt は使えません。
- `upgradeEncoding` は別の ID のハッシュをすべて報告するため、ログイン時に再ハッシュされます。

## ログイン時のハッシュのアップグレード

ログインに成功した後、`DaoAuthenticationProvider` は `upgradeEncoding` に問い合わせます。保存されたハッシュが別の `{id}` やより弱いパラメーターで作られていた場合、入力されたパスワードを現在の設定で再ハッシュし、`UserDetailsPasswordService` Bean (または `UserDetailsService` 自体がそれである場合はそれ) を通じて保存します。年月とともにコストを上げれば、ユーザーはログインするにつれてそれに移行します。

## Java と共有するハッシュ

Argon2、PBKDF2、scrypt は、Spring の Java のエンコーダーと同じく、Bouncy Castle の Dart への移植 (`pointycastle`) を使い、そのハッシュは双方向で検証できます (Spring Security 7.1 に対して確認済み)。例外が一つあります。デリゲーティングエンコーダーでは、`{pbkdf2}` はここでは `@SpringSecurity_v5_8` の設定を意味しますが、Spring 6 以降はより古い v5_5 の設定で読みます。そのため `{pbkdf2}` として保存された Java のハッシュは、ここでは検証できないことがあります。`{pbkdf2@SpringSecurity_v5_8}` のハッシュは検証できます。

## Spring (Java) との対応

```java
PasswordEncoder encoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();
```

Spring のデフォルトの ID は `bcrypt` です。BCrypt はここにはありません。検証済みの Dart 実装がなく、このプロジェクトでは暗号を手書きしないためです。新しいハッシュは `{argon2}` で、Spring もこれをチェックできます。

## 関連項目

- [認証](authentication.md)
- [Spring との違い](differences.md)
