# 画面設計書 135-ネットワーク暗号化

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverネットワーク暗号化（Force Network Encryption）設定管理機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverインスタンスの「Force Network Encryption」設定の取得、有効化、無効化を行う機能群を提供する。

**業務上の目的・背景**：SQL Serverへのクライアント接続を暗号化することは、ネットワーク盗聴や中間者攻撃からデータを保護するための重要なセキュリティ対策である。Force Network Encryptionを有効にすると、クライアントの暗号化設定に関係なく、すべての接続が強制的に暗号化される。本機能は、セキュリティ監査、コンプライアンス対応、暗号化ポリシーの一括適用において重要な役割を果たす。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaForceNetworkEncryption` - 強制暗号化設定の取得
- `Enable-DbaForceNetworkEncryption` - 強制暗号化の有効化
- `Disable-DbaForceNetworkEncryption` - 強制暗号化の無効化

**主要な操作・処理内容**：
1. 現在のForce Encryption設定状態の確認
2. 設定されている証明書のサムプリント取得
3. 強制暗号化の有効化（レジストリ値を$trueに設定）
4. 強制暗号化の無効化（レジストリ値を$falseに設定）
5. 設定変更後のサービス再起動警告

**画面遷移**：CLIベースのため画面遷移は存在しない。Set-DbaNetworkCertificateと組み合わせて使用することが多い。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 601 | Get-DbaForceNetworkEncryption | 主機能 | ネットワーク暗号化設定の取得 |
| 594 | Enable-DbaForceNetworkEncryption | 主機能 | ネットワーク暗号化の有効化 |
| 592 | Disable-DbaForceNetworkEncryption | 主機能 | ネットワーク暗号化の無効化 |
| - | Resolve-DbaNetworkName | 補助機能 | ネットワーク名の解決 |
| - | Invoke-ManagedComputerCommand | 補助機能 | WMI経由のサービス情報取得 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

### Get-DbaForceNetworkEncryption

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

### Enable-DbaForceNetworkEncryption

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

### Disable-DbaForceNetworkEncryption

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

## 表示項目

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

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| ForceEncryption | bool | 強制暗号化の有効/無効状態 |
| CertificateThumbprint | string | 設定されている証明書のサムプリント（または$null） |

## イベント仕様

### 1-Get-DbaForceNetworkEncryption実行

1. Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリからForceEncryptionとCertificate値を読み取り
5. 結果をハッシュテーブルで返却し、PSCustomObjectに変換

### 2-Enable-DbaForceNetworkEncryption実行

1. Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリパスを特定
5. ShouldProcess確認後、ForceEncryption値を$trueに設定
6. 変更後の値を読み取って結果を返却
7. サービス再起動が必要な旨のCriticalメッセージを出力

### 3-Disable-DbaForceNetworkEncryption実行

1. Test-ElevationRequirementで管理者権限を確認
2. Resolve-DbaNetworkNameでコンピュータ名を解決
3. Invoke-ManagedComputerCommandでWMIサービス情報を取得
4. レジストリパスを特定
5. ShouldProcess確認後、ForceEncryption値を$falseに設定
6. 変更後の値を読み取って結果を返却
7. サービス再起動が必要な旨のCriticalメッセージを出力

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

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaForceNetworkEncryption | Windowsレジストリ | READ | SuperSocketNetLib\ForceEncryption値の読み取り |
| Enable-DbaForceNetworkEncryption | Windowsレジストリ | UPDATE | ForceEncryption値を$trueに設定 |
| Disable-DbaForceNetworkEncryption | Windowsレジストリ | UPDATE | ForceEncryption値を$falseに設定 |

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

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

| 操作 | 項目（レジストリ値） | 更新値 | 備考 |
|-----|---------------------|--------|------|
| Enable | ForceEncryption | $true | 暗号化を強制 |
| Disable | ForceEncryption | $false | 暗号化を非強制 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Critical | Force encryption was successfully set on {computer} for the {instance} instance. You must now restart the SQL Server for changes to take effect. | Enable/Disable成功時 |
| - | Error | Can't resolve {instance} | 名前解決失敗時 |
| - | Error | Failed to access {instance} | WMI接続失敗時 |
| - | Error | Can't find instance {vsname} on {instance} | インスタンス検出失敗時 |
| - | Error | Failed to connect to {computer} using PowerShell remoting | リモート接続失敗時 |

## 例外処理

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

## 備考

- ForceEncryptionの変更はSQL Serverサービスの再起動後に有効となる
- 暗号化を有効にする前に、適切な証明書がSet-DbaNetworkCertificateで設定されている必要がある
- CertificateThumbprintが$nullの場合でもForceEncryptionを有効にできるが、自己署名証明書が使用される
- SQL Server Configuration Managerで同等の設定が可能だが、本コマンドは複数インスタンスの一括設定に適している

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | .OUTPUTSセクションで出力プロパティ定義（行34-44） |
| 1-2 | Enable-DbaForceNetworkEncryption.ps1 | `public/Enable-DbaForceNetworkEncryption.ps1` | 出力プロパティ定義（行44-50） |

**読解のコツ**: 3つのコマンドはほぼ同じ出力構造を持つ。Get/Enable/Disableで共通のロジックが多い。

#### Step 2: エントリーポイントを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | processブロックの構造と名前解決 |

**主要処理フロー**:
1. **行66**: 管理者権限確認
2. **行70-74**: Resolve-DbaNetworkNameによる名前解決（エラー時Turboフォールバック）
3. **行80-86**: Invoke-ManagedComputerCommandでWMIサービス情報取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | スクリプトブロック内のレジストリ操作（行124-136） |
| 3-2 | Enable-DbaForceNetworkEncryption.ps1 | `public/Enable-DbaForceNetworkEncryption.ps1` | ForceEncryption値の設定（行137） |

**主要処理フロー**:
- **行125**: レジストリパス構築（$regPath）
- **行126-127**: Certificate、ForceEncryption値の読み取り
- **行130-136**: ハッシュテーブルで結果構築

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

```
Get-DbaForceNetworkEncryption
    |
    +-- Test-ElevationRequirement
    |
    +-- Resolve-DbaNetworkName
    |       +-- FullComputerName取得
    |
    +-- Invoke-ManagedComputerCommand
    |       +-- $wmi.Services（SQL Serverサービス情報）
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Get-ItemProperty (レジストリ読み取り)
            +-- ハッシュテーブル結果返却

Enable/Disable-DbaForceNetworkEncryption
    |
    +-- Test-ElevationRequirement
    |
    +-- Resolve-DbaNetworkName
    |
    +-- Invoke-ManagedComputerCommand
    |
    +-- ShouldProcess確認
    |
    +-- Invoke-Command2 (スクリプトブロック)
            +-- Set-ItemProperty (ForceEncryption設定)
            +-- Get-ItemProperty (設定確認)
            +-- PSCustomObject結果返却
```

### データフロー図

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

SqlInstance ────────▶ Resolve-DbaNetworkName ────────▶ FullComputerName
    |                        |
Credential ─────────────────▶ |
                              v
                     Invoke-ManagedComputerCommand
                              |
                              v
                     WMI Services情報取得
                              |
                              v
                     レジストリパス特定
                     (REGROOT\MSSQLServer\
                      SuperSocketNetLib)
                              |
                              v
                    ┌─────────────────────────┐
                    │   Invoke-Command2       │
                    │   (リモートスクリプト)   │
                    │                         │
       [Get] ──────▶│  Get-ItemProperty      │────▶ ハッシュテーブル
                    │  ForceEncryption       │       (PSCustomObject変換)
                    │  Certificate           │
                    │                         │
    [Enable] ──────▶│  Set-ItemProperty      │────▶ PSCustomObject
                    │  ForceEncryption=$true │       + Criticalメッセージ
                    │                         │
   [Disable] ──────▶│  Set-ItemProperty      │────▶ PSCustomObject
                    │  ForceEncryption=$false│       + Criticalメッセージ
                    └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | ソース | 暗号化設定取得コマンド |
| Enable-DbaForceNetworkEncryption.ps1 | `public/Enable-DbaForceNetworkEncryption.ps1` | ソース | 暗号化有効化コマンド |
| Disable-DbaForceNetworkEncryption.ps1 | `public/Disable-DbaForceNetworkEncryption.ps1` | ソース | 暗号化無効化コマンド |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決ユーティリティ |
