
# TLS (HTTPS)

`server.ssl.certificate` と `server.ssl.certificate-private-key` に二つの PEM ファイルを設定すると、サーバーは HTTP の代わりに HTTPS を話します。

## 使う理由

TLS がなければ、クライアントとサーバーの間のすべて、つまりパスワード、セッション Cookie、トークンが、途中で読まれたり変更されたりする可能性があります。前段にプロキシを置かず、クライアントがサーバーに直接アクセスする場合は TLS を使ってください。

リバースプロキシやロードバランサー (nginx、Traefik、クラウドのロードバランサー) が TLS を終端してくれる場合は、通常 `server.ssl.*` を空のままにし、代わりに `server.forward-headers-strategy` を設定します。[リバースプロキシの背後で](reverse-proxy.md) を参照してください。

クライアント証明書 (`server.ssl.client-auth`) を使うと、サーバーはどのマシンが呼んでいるかを知ることができます。サービス間の相互 TLS です。

## 例

```yaml
# lib/resources/application.yml
server:
  port: 8443
  ssl:
    certificate: /etc/shop/tls/fullchain.pem
    certificate-private-key: /etc/shop/tls/privkey.pem
```

```properties
server.port=8443
server.ssl.certificate=/etc/shop/tls/fullchain.pem
server.ssl.certificate-private-key=/etc/shop/tls/privkey.pem
```

すると起動時の行は `https` になります。

```text
Web server started on port 8443 (https)
```

開発用の自己署名証明書:

```bash
openssl req -x509 -newkey rsa:2048 -nodes -days 30 -subj /CN=localhost \
  -keyout key.pem -out cert.pem
```

```properties
server.ssl.certificate=cert.pem
server.ssl.certificate-private-key=key.pem
```

相対パスは、プロセスの作業ディレクトリから読まれます。

### 相互 TLS

```yaml
server:
  ssl:
    certificate: /etc/billing/tls/server.pem
    certificate-private-key: /etc/billing/tls/server-key.pem
    key-password: ${TLS_KEY_PASSWORD}
    trust-certificate: /etc/billing/tls/clients-ca.pem
    client-auth: need
```

`clients-ca.pem` の証明書で署名された証明書を持つクライアントだけが応答を受け取ります。それ以外は 403 になります。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `server.ssl.enabled` | `bool` | `true` | `false` は TLS を無効にし、他の `server.ssl.*` キーを無視する。 |
| `server.ssl.certificate` | `String` (ファイルパス) | なし | 証明書チェーン (PEM ファイル)。設定されていれば TLS が有効。 |
| `server.ssl.certificate-private-key` | `String` (ファイルパス) | なし | 秘密鍵 (PEM ファイル)。`certificate` と一緒に必須。 |
| `server.ssl.key-password` | `String` | なし | 暗号化された秘密鍵のパスワード。 |
| `server.ssl.trust-certificate` | `String` (ファイルパス) | なし | クライアント証明書の署名者でなければならない証明書 (PEM ファイル)。 |
| `server.ssl.client-auth` | `none` / `want` / `need` | `none` | クライアントに証明書を求めるかどうか。 |

### `server.ssl.enabled`

- **型:** `bool`。**デフォルト:** `true`。
- **動作:** `false` にすると、`certificate` が設定されていてもサーバーは平文の HTTP を話します。他のキーは無視されます。
- **変更する理由:** 証明書のパスを共有の `application.yml` に置いたまま、あるプロファイル、たとえば `application-dev.yml` で TLS を無効にする。
- **例:** `server.ssl.enabled=false`。
- **注意:** `true` だけでは何も有効になりません。TLS には `certificate` も必要です。

### `server.ssl.certificate`

- **型:** ファイルパス。**デフォルト:** なし (平文の HTTP)。
- **動作:** PEM 形式 (`-----BEGIN CERTIFICATE-----`) のサーバーの証明書チェーン。サーバーの証明書を最初に、続いて中間証明書を置きます。Let's Encrypt の `fullchain.pem` はこの形式です。
- **TLS が有効になる** のは、このキーが (空でなく) 設定され、`server.ssl.enabled` が `false` でない場合です。
- **変更する理由:** HTTPS を提供するため。証明書を更新したら更新後のファイルを指し、アプリケーションを再起動してください。ファイルはサーバーの起動時に読まれます。
- **例:** `server.ssl.certificate=/etc/letsencrypt/live/shop.example/fullchain.pem`。
- **ロケーションではなくパス:** ファイルシステム上のパスです。`resources:` や `classpath:` のロケーションはサポートされず、証明書は実行ファイルに埋め込まれません。
- **誤った値:** 存在しないファイルや有効な PEM 証明書でないファイルは、起動を失敗させます (`Web server failed to start` と `dart:io` のエラー)。

### `server.ssl.certificate-private-key`

- **型:** ファイルパス。**デフォルト:** なし。
- **動作:** PEM 形式の証明書の秘密鍵。
- **`certificate` と一緒に必須です。** ないと、次のメッセージで起動が失敗します。

```text
server.ssl.certificate needs server.ssl.certificate-private-key
```

- **`certificate` なしで鍵だけ:** TLS は無効のままです。エラーにはなりません。
- **変更する理由:** `certificate` と一緒に。
- **例:** `server.ssl.certificate-private-key=/etc/letsencrypt/live/shop.example/privkey.pem`。
- **誤った値:** ファイルがない、鍵が証明書と一致しない、または正しいパスワードのない暗号化された鍵は、`dart:io` のエラーで起動を失敗させます。

### `server.ssl.key-password`

- **型:** `String`。**デフォルト:** なし (鍵は暗号化されていない)。
- **動作:** 暗号化された秘密鍵ファイルを復号するために `dart:io` が使うパスワード。
- **変更する理由:** 鍵ファイルが暗号化されている場合 (`-----BEGIN ENCRYPTED PRIVATE KEY-----`)。
- **例:** `server.ssl.key-password=${TLS_KEY_PASSWORD}`。コミットするファイルにパスワードを書かないでください。プレースホルダーを通して、環境変数やシークレットストアから取得してください。
- **注意:** 空の値はパスワードなしとみなされます。

### `server.ssl.trust-certificate`

- **型:** ファイルパス。**デフォルト:** なし。
- **動作:** クライアント証明書の署名者でなければならない証明書 (通常は独自の認証局一つ) を含む PEM ファイル。`client-auth` と一緒に使います。
- **変更する理由:** `client-auth: want` または `need` を使う場合。その場合は常に設定して、サーバーが選んだ発行者だけを信頼するようにしてください。
- **例:** `server.ssl.trust-certificate=/etc/billing/tls/clients-ca.pem`。
- **`client-auth: none` では** 効果がありません。クライアント証明書は求められません。

### `server.ssl.client-auth`

- **型:** enum。**デフォルト:** `none`。

| 値 | 動作 |
|---|---|
| `none` | クライアント証明書を求めない。 |
| `want` | TLS ハンドシェイク中に証明書を求める。持たないクライアントにもサービスする。 |
| `need` | 証明書を求める。持たないリクエストには `403 Forbidden` (詳細 `A client certificate is required` の `ProblemDetail`) で応答する。 |

- **変更する理由:** 呼び出し側が証明書で自分を証明するサービス間の呼び出し (相互 TLS)。
- **`need` の仕組み:** TLS ハンドシェイクは証明書なしでも完了し、その後サーバーは、どのフィルターやコントローラーよりも前に、その接続上のすべてのリクエストに 403 で応答します。WebSocket ハンドシェイクも同じ 403 を受け取ります。
- **例:** `server.ssl.client-auth=need`。
- **誤った値:** `server.ssl.client-auth=sometimes` は、`server.ssl.client-auth` を名指しするバインディングの失敗で起動を止めます。
- **注意:** クライアント証明書そのものはフィルターやコントローラーに渡されません。スターターは証明書が提示されたことを確認するだけで、それをユーザーに対応付けることはしません。

## TLS を有効にすると変わるもの

- `request.isSecure` が `true` になり、`request.uri` のスキームが `https` になります。
- セッション Cookie に `Secure` が付きます (`server.session.cookie.secure` で別の指定がない限り)。[セッション](../sessions.md) を参照してください。
- WebSocket セッションの URI のスキームが `wss` になります。
- 一つのポートは HTTPS だけを提供します。二つ目の HTTP ポートも、HTTP から HTTPS へのリダイレクトもありません。それはプロキシに任せるか、二つ目のアプリケーションを起動してください。

## ルール

- ファイルはサーバーの起動時に一度だけ読まれます。更新した証明書は再起動後に有効になります (Flutter アプリでは、アプリがバックグラウンドから戻ってサーバーが再び起動した後にも)。
- PEM ファイルだけです。Java のキーストア (`server.ssl.key-store`、`key-store-type`、`key-alias`、`trust-store`) も SSL バンドル (`server.ssl.bundle`) もありません。
- `server.ssl.protocol`、`enabled-protocols`、`ciphers` はありません。`dart:io` (BoringSSL) がそれらを選びます。
- TLS 上でも HTTP/1.1 だけです。HTTP/2 はありません (`server.http2.enabled` は読まれません)。

## Spring (Java) との対応

```properties
server.port=8443
server.ssl.certificate=classpath:tls/fullchain.pem
server.ssl.certificate-private-key=classpath:tls/privkey.pem
server.ssl.trust-certificate=classpath:tls/clients-ca.pem
server.ssl.client-auth=need
```

重要な違い:

- キーは Spring Boot の PEM のキーですが、値はファイルパスだけです。`classpath:` や `resources:` のロケーションは使えません。
- キーストア、SSL バンドル、プロトコルや暗号スイートの設定はありません。
- `need` の場合、Tomcat はクライアント証明書のない TLS ハンドシェイクを拒否します。ここではハンドシェイクは完了し、各リクエストが 403 の `ProblemDetail` を受け取ります。
- クライアント証明書はアプリケーションから使えません (Spring はリクエスト属性 `jakarta.servlet.request.X509Certificate` に入れます)。

## 関連項目

- [組み込みサーバー](index.md)
- [リバースプロキシの背後で](reverse-proxy.md)
- [セッション](../sessions.md)
- [すべてのプロパティ](../properties.md)
- [プレースホルダー](../../spring-core-dart/config/placeholders.md)
- [プロファイル](../../spring-core-dart/config/profiles.md)
