# 画面設計書 136-拡張保護

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Server拡張保護（Extended Protection）設定管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverインスタンスの「Extended Protection」認証設定の取得および設定を行う機能群を提供する。

**業務上の目的・背景**：Extended Protectionは、Windows認証を強化してクレデンシャルリレー攻撃（中間者攻撃）を防ぐセキュリティ機能である。チャネルバインディングとサービスプリンシパル名（SPN）の検証により、クライアントがSQL Serverに接続する際の認証セキュリティを向上させる。本機能は、セキュリティ監査、コンプライアンス対応、複数インスタンスへの設定一括適用において重要な役割を果たす。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaExtendedProtection` - 拡張保護設定の取得
- `Set-DbaExtendedProtection` - 拡張保護設定の変更

**主要な操作・処理内容**：
1. 現在のExtended Protection設定状態の確認
2. 設定値を「Off」「Allowed」「Required」から選択して設定
3. 設定変更は即座に新しい接続に反映（サービス再起動不要）

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：Windows管理者権限が必要。対象サーバーへのリモートPowerShell接続権限およびレジストリ変更権限が必要となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 123 | Get-DbaExtendedProtection | 主機能 | 拡張保護の取得 |
| 226 | Set-DbaExtendedProtection | 主機能 | 拡張保護の設定 |
| - | Resolve-DbaNetworkName | 補助機能 | ネットワーク名の解決 |
| - | Invoke-ManagedComputerCommand | 補助機能 | WMI経由のサービス情報取得 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Get-DbaExtendedProtection

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

### Set-DbaExtendedProtection

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| Value | object | いいえ | 設定値（0/Off、1/Allowed、2/Required）デフォルト: Off |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |
| WhatIf | switch | いいえ | 実行予定の操作を表示 |
| Confirm | switch | いいえ | 実行前に確認を求める |

## 表示項目

### 共通出力プロパティ

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| ExtendedProtection | string | 拡張保護の設定値と説明（例: "0 - Off"、"1 - Allowed"、"2 - Required"） |

## イベント仕様

### 1-Get-DbaExtendedProtection実行

1. localhostの場合、Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリからExtendedProtection値を読み取り
5. 数値と説明文を組み合わせた形式で結果を返却

### 2-Set-DbaExtendedProtection実行

1. beginブロックでValue値を数値に変換（Off=0、Allowed=1、Required=2）
2. localhostの場合、Test-ElevationRequirementで管理者権限を確認
3. Resolve-DbaNetworkNameでコンピュータ名を解決
4. Invoke-ManagedComputerCommandでWMIサービス情報を取得
5. Test-ShouldProcess確認後、ExtendedProtection値を設定
6. 変更後の値を読み取って結果を返却
7. 設定変更が即座に有効になる旨のCriticalメッセージを出力

## データベース更新仕様

### 操作別データベース影響一覧

本機能はWindowsレジストリを更新するため、データベースへの直接的な更新は発生しない。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaExtendedProtection | Windowsレジストリ | READ | SuperSocketNetLib\ExtendedProtection値の読み取り |
| Set-DbaExtendedProtection | Windowsレジストリ | UPDATE | ExtendedProtection値の設定 |

### レジストリ更新詳細

#### HKLM\{REGROOT}\MSSQLServer\SuperSocketNetLib

| 操作 | 項目（レジストリ値） | 更新値 | 備考 |
|-----|---------------------|--------|------|
| Set | ExtendedProtection | 0 / 1 / 2 | Off / Allowed / Required |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Critical | ExtendedProtection was successfully set on {computer} for the {instance} instance. The change takes effect immediately for new connections. | Set成功時 |
| - | Error | Issue resolving {instance} | 名前解決失敗時 |
| - | Error | Failed to access {instance} | WMI接続失敗時 |
| - | Error | Can't find instance {vsname} on {instance} | インスタンス検出失敗時 |
| - | Error | Failed to connect to {computer} using PowerShell remoting | リモート接続失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 管理者権限不足（localhost） | Test-ElevationRequirementで検出、処理継続 |
| インスタンス名解決失敗 | Turboモードでの解決を試行、失敗時は処理中止 |
| WMI接続失敗 | エラー記録して次のインスタンスへ継続 |
| レジストリルート特定失敗 | 処理中止 |
| PowerShellリモーティング失敗 | エラー記録して次のインスタンスへ継続 |

## 備考

- Extended Protectionの設定値：
  - **0 (Off)**: 拡張保護無効
  - **1 (Allowed)**: 保護された接続と非保護接続の両方を許可
  - **2 (Required)**: すべての接続で拡張保護を強制（古いクライアントは接続不可）
- 設定変更はサービス再起動なしで新しい接続に即座に反映
- 「Required」に設定すると、Extended Protectionに対応していない古いアプリケーションからの接続が拒否される
- SQL Server Configuration Managerのネットワーク構成プロトコルプロパティと同等の設定

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、コマンドが返すオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaExtendedProtection.ps1 | `public/Get-DbaExtendedProtection.ps1` | .OUTPUTSセクションで出力プロパティ定義（行43-52） |
| 1-2 | Set-DbaExtendedProtection.ps1 | `public/Set-DbaExtendedProtection.ps1` | 出力プロパティ定義（行47-56） |

**読解のコツ**: ExtendedProtectionプロパティは数値と説明を組み合わせた文字列（例: "0 - Off"）で出力される。

#### Step 2: 値の変換ロジックを理解する

処理の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaExtendedProtection.ps1 | `public/Set-DbaExtendedProtection.ps1` | beginブロックでの値変換ロジック（行93-96） |

**主要処理フロー**:
1. **行88**: ValidateSetで0/Off/1/Allowed/2/Requiredを許可
2. **行94-95**: 文字列値を数値に変換（Off=0, Allowed=1, Required=2）

#### Step 3: レジストリ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaExtendedProtection.ps1 | `public/Get-DbaExtendedProtection.ps1` | スクリプトブロック内のレジストリ操作（行124-133） |
| 3-2 | Set-DbaExtendedProtection.ps1 | `public/Set-DbaExtendedProtection.ps1` | レジストリ設定操作（行151-161） |

**主要処理フロー**:
- **Get行125-126**: レジストリパス構築とExtendedProtection値読み取り
- **Get行132**: switch文で数値を説明文に変換
- **Set行153**: Set-ItemPropertyでレジストリ値を設定
- **Set行160**: switch文で設定後の値を説明文付きで出力

### プログラム呼び出し階層図

```
Get-DbaExtendedProtection
    |
    +-- Test-ElevationRequirement (localhost時)
    |
    +-- Resolve-DbaNetworkName
    |       +-- FullComputerName取得
    |
    +-- Invoke-ManagedComputerCommand
    |       +-- $wmi.Services（SQL Serverサービス情報）
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Get-ItemProperty (レジストリ読み取り)
            +-- switch ($extendedProtection) で説明付与
            +-- PSCustomObject結果返却

Set-DbaExtendedProtection
    |
    +-- beginブロック: Value値を数値変換
    |
    +-- Test-ElevationRequirement (localhost時)
    |
    +-- Resolve-DbaNetworkName
    |
    +-- Invoke-ManagedComputerCommand
    |
    +-- Test-ShouldProcess確認
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Set-ItemProperty (ExtendedProtection設定)
            +-- Get-ItemProperty (設定確認)
            +-- switch文で説明付与
            +-- PSCustomObject結果返却
```

### データフロー図

```
[入力]                    [処理]                           [出力]

SqlInstance ────────▶ Resolve-DbaNetworkName ────────▶ FullComputerName
    |                        |
Credential ─────────────────▶ |
    |                        v
Value ──────────────▶ 数値変換 (beginブロック)
(Off/Allowed/Required)   │
    │                    v
    │           Invoke-ManagedComputerCommand
    │                    │
    │                    v
    │           WMI Services情報取得
    │                    │
    │                    v
    │           レジストリパス特定
    │           (REGROOT\MSSQLServer\
    │            SuperSocketNetLib)
    │                    │
    │                    v
    │           ┌─────────────────────────┐
    │           │   Invoke-Command2       │
    │           │   (リモートスクリプト)   │
    │           │                         │
    │  [Get] ──▶│  Get-ItemProperty      │────▶ PSCustomObject
    │           │  ExtendedProtection    │       (数値 - 説明 形式)
    │           │  + switch説明付与      │
    │           │                         │
    └─▶[Set] ──▶│  Set-ItemProperty      │────▶ PSCustomObject
                │  ExtendedProtection=$Value│    + Criticalメッセージ
                │  + Get確認 + switch説明 │
                └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaExtendedProtection.ps1 | `public/Get-DbaExtendedProtection.ps1` | ソース | 拡張保護設定取得コマンド |
| Set-DbaExtendedProtection.ps1 | `public/Set-DbaExtendedProtection.ps1` | ソース | 拡張保護設定変更コマンド |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決ユーティリティ |
