# 機能設計書 601-Get-DbaForceNetworkEncryption

## 概要

本ドキュメントは、SQL ServerのネットワークセキュリティにおけるForce Network Encryption設定を取得する`Get-DbaForceNetworkEncryption`機能の設計書である。

### 本機能の処理概要

`Get-DbaForceNetworkEncryption`は、SQL Serverインスタンスのネットワーク暗号化強制設定と、関連するSSL証明書情報をWindowsレジストリから取得する機能である。この設定は、SQL Serverがすべてのクライアント接続に対して暗号化を要求するかどうかを決定する重要なセキュリティ設定である。

**業務上の目的・背景**：企業のセキュリティポリシーやコンプライアンス要件（PCI-DSS、HIPAA等）において、データベース接続の暗号化が義務付けられることが多い。本機能は、複数のSQL Serverインスタンスにわたってネットワーク暗号化ポリシーが適切に構成されているかを監査・検証するために使用される。暗号化されていない通信は中間者攻撃や盗聴のリスクにさらされるため、本設定の確認は定期的なセキュリティレビューにおいて不可欠である。

**機能の利用シーン**：
- セキュリティ監査時にすべてのSQL Serverインスタンスの暗号化設定を一括確認
- 新規サーバー構築後のセキュリティ設定検証
- コンプライアンスレポート作成のための設定情報収集
- 暗号化に使用されている証明書のサムプリント確認

**主要な処理内容**：
1. ターゲットコンピュータの名前解決を実行
2. SQL Server WMIを介してインスタンスのレジストリルートパスを取得
3. SuperSocketNetLibレジストリキーからForceEncryption設定値を読み取り
4. 同じレジストリキーから設定されている証明書のサムプリントを取得
5. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：Windows WMI、Windowsレジストリ、PowerShellリモーティング

**権限による制御**：ローカルマシンでは管理者権限が必要。リモートマシンへのアクセスには、対象コンピュータへのWinRM接続権限とレジストリ読み取り権限が必要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | CLIベースの機能のため関連画面なし |

## 機能種別

データ取得（SELECT相当） / セキュリティ監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス（デフォルト: localhost） | 有効なインスタンス名形式 |
| Credential | PSCredential | No | リモートコンピュータ接続用の代替資格情報 | なし |
| EnableException | switch | No | 例外処理の有効化フラグ | なし |

### 入力データソース

- SQL Server WMI（ManagedComputer経由）
- Windowsレジストリ（HKEY_LOCAL_MACHINE\{REGROOT}\MSSQLServer\SuperSocketNetLib）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverをホストするコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス形式） |
| ForceEncryption | Boolean | ネットワーク暗号化強制が有効かどうか |
| CertificateThumbprint | String | 暗号化に使用される証明書のSHA-1サムプリント（設定されていない場合はnull） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceパラメータの各インスタンスをループ処理
   └─ インスタンスごとに処理を実行
2. Test-ElevationRequirementで管理者権限を確認
   └─ 権限不足の場合は処理をスキップ
3. Resolve-DbaNetworkNameでホスト名を解決
   └─ 解決失敗時はTurboモードで再試行
4. Invoke-ManagedComputerCommandでWMIサービス情報を取得
   └─ SQL Serverサービスの詳細プロパティを取得
5. WMIからREGROOTとVSNAMEを抽出
   └─ インスタンスのレジストリパスを特定
6. リモートスクリプトブロックでレジストリを読み取り
   └─ ForceEncryptionとCertificate値を取得
7. 結果をPSCustomObjectとして出力
   └─ パイプラインに結果を送出
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ開始]
    B --> C{管理者権限確認}
    C -->|権限なし| D[警告出力してスキップ]
    C -->|権限あり| E[ホスト名解決]
    E --> F{解決成功?}
    F -->|失敗| G[Turboモードで再試行]
    G --> H{解決成功?}
    H -->|失敗| I[エラー出力してスキップ]
    F -->|成功| J[WMIサービス情報取得]
    H -->|成功| J
    J --> K{取得成功?}
    K -->|失敗| L[エラー出力してスキップ]
    K -->|成功| M[REGROOT/VSNAME抽出]
    M --> N{値が空?}
    N -->|空| O[代替方法で抽出]
    N -->|値あり| P[レジストリ読み取りスクリプト実行]
    O --> P
    P --> Q[PSCustomObject作成]
    Q --> R[結果出力]
    R --> S{次のインスタンス?}
    S -->|あり| B
    S -->|なし| T[終了]
    D --> S
    I --> S
    L --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-601-01 | 管理者権限要件 | ローカルマシンでの実行には管理者権限が必要 | 常時 |
| BR-601-02 | デフォルトインスタンス | SqlInstanceが指定されない場合はlocalhostを使用 | パラメータ未指定時 |
| BR-601-03 | ForceEncryption解釈 | レジストリ値1はTrue、0はFalseとして解釈 | 常時 |

### 計算ロジック

特になし

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | SQLデータベースへの直接アクセスなし（WMI/レジストリのみ） |

### テーブル別操作詳細

本機能はSQLデータベースに直接アクセスせず、Windows WMIとレジストリから情報を取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 名前解決失敗 | ホスト名が解決できない場合 | エラーメッセージを出力し次のインスタンスへ |
| - | WMIアクセス失敗 | WMIへの接続ができない場合 | エラーメッセージを出力し次のインスタンスへ |
| - | リモート接続失敗 | PowerShellリモーティング失敗時 | エラーメッセージを出力し次のインスタンスへ |
| - | インスタンス未検出 | 指定インスタンスが見つからない場合 | エラーメッセージを出力し次のインスタンスへ |

### リトライ仕様

- ホスト名解決失敗時のみTurboモードで1回リトライ

## トランザクション仕様

読み取り専用操作のためトランザクション制御なし

## パフォーマンス要件

特に規定なし（リモート接続のレイテンシに依存）

## セキュリティ考慮事項

- 管理者権限（RunAs Admin）が必要
- リモートマシンへの接続にはWinRM権限が必要
- 資格情報はSecureStringとして安全に取り扱われる
- レジストリの読み取りのみで書き込みは行わない

## 備考

- 本機能は英語版OSロケールで動作確認されている
- SQL Server Configuration Managerで表示される情報と同等の内容を取得可能

---

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

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

### 推奨読解順序

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

本機能は比較的シンプルな構造で、出力されるPSCustomObjectの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | 130-136行目のハッシュテーブル構造が出力オブジェクトの形式を定義 |

**読解のコツ**: リモートで実行されるスクリプトブロック内では`[PSCustomObject]`が正常に動作しない場合があるため、ハッシュテーブルで返してからローカルでPSCustomObjectに変換している点に注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | process ブロック（63-148行目）がメイン処理のエントリーポイント |

**主要処理フロー**:
1. **64行目**: foreachループでSqlInstanceの各要素を処理開始
2. **66行目**: Test-ElevationRequirementで管理者権限を確認
3. **68-74行目**: Resolve-DbaNetworkNameでホスト名解決（失敗時Turboモード再試行）
4. **80-86行目**: Invoke-ManagedComputerCommandでWMI経由のサービス情報取得
5. **88-112行目**: REGROOTとVSNAMEの抽出（複数のフォールバック処理あり）
6. **124-137行目**: リモートスクリプトブロック内でレジストリ読み取り

#### Step 3: WMI操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | 81-83行目のInvoke-ManagedComputerCommandでWMI操作を実行 |

**主要処理フロー**:
- **81-83行目**: ManagedComputerのServicesコレクションからSQL Serverサービス情報を取得
- **88-89行目**: AdvancedPropertiesからREGROOT（レジストリパス）とVSNAME（仮想サーバー名）を抽出

#### Step 4: レジストリ読み取り処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | 124-137行目のスクリプトブロックがレジストリ読み取りの核心部分 |

**主要処理フロー**:
- **125行目**: レジストリパス構築（SuperSocketNetLibキー）
- **126-127行目**: Get-ItemPropertyでCertificateとForceEncryption値を取得
- **130-136行目**: 結果をハッシュテーブルとして構築

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

```
Get-DbaForceNetworkEncryption
    │
    ├─ Test-ElevationRequirement
    │      └─ 管理者権限の確認
    │
    ├─ Resolve-DbaNetworkName
    │      └─ ホスト名からFQDNへの解決
    │
    ├─ Invoke-ManagedComputerCommand
    │      └─ WMI経由でSQL Serverサービス情報取得
    │
    └─ Invoke-Command2
           └─ レジストリ読み取りスクリプトブロック実行
                  └─ Get-ItemProperty（Certificate, ForceEncryption）
```

### データフロー図

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

SqlInstance ───────▶ Resolve-DbaNetworkName ───────▶ 解決済みホスト名
                              │
                              ▼
                    Invoke-ManagedComputerCommand
                              │
                              ▼
                    WMI Services情報 ───────────────▶ REGROOT/VSNAME
                              │
                              ▼
                    Invoke-Command2（レジストリ読み取り）
                              │
                              ▼
                    レジストリ値 ──────────────────▶ PSCustomObject
                    - ForceEncryption                 - ComputerName
                    - Certificate                     - InstanceName
                                                      - SqlInstance
                                                      - ForceEncryption
                                                      - CertificateThumbprint
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaForceNetworkEncryption.ps1 | `public/Get-DbaForceNetworkEncryption.ps1` | ソース | メイン機能実装 |
| Invoke-ManagedComputerCommand.ps1 | `private/functions/Invoke-ManagedComputerCommand.ps1` | ソース | WMIアクセス用ヘルパー関数 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ホスト名解決ユーティリティ |
| Test-ElevationRequirement.ps1 | `private/functions/Test-ElevationRequirement.ps1` | ソース | 管理者権限確認 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | PowerShellリモーティングラッパー |
