# 画面設計書 131-ネットワーク証明書

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverネットワーク証明書管理機能の設計仕様を定義する。SSL/TLS通信に使用される証明書の取得、設定、削除を行うコマンド群について記述する。

### 本画面の処理概要

SQL Serverインスタンスのネットワーク暗号化に使用される証明書を管理するための機能群を提供する。

**業務上の目的・背景**：SQL Serverクライアント接続のSSL/TLS暗号化を実現するためには、適切な証明書の設定が必要である。本機能は、証明書の現在の設定状況を確認し、新しい証明書を設定、不要になった証明書設定を削除するという一連の証明書ライフサイクル管理を支援する。セキュリティ監査、コンプライアンス対応、SSL接続のトラブルシューティングにおいて重要な役割を果たす。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaNetworkCertificate` - 証明書設定の取得
- `Set-DbaNetworkCertificate` - 証明書の設定
- `Remove-DbaNetworkCertificate` - 証明書設定の削除

**主要な操作・処理内容**：
1. 現在設定されているネットワーク証明書の取得と表示
2. 新しい証明書のサムプリントを指定した設定
3. X509Certificate2オブジェクトを直接パイプラインで渡しての設定
4. 証明書の秘密鍵へのSQL Serverサービスアカウントの読み取り権限付与
5. 証明書設定のクリア（削除）
6. サービス再起動オプションによる設定の即座の反映

**画面遷移**：CLIベースのため画面遷移は存在しない。ただし、`New-DbaComputerCertificate`で作成した証明書を`Set-DbaNetworkCertificate`にパイプラインで渡すワークフローが一般的である。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 602 | Get-DbaNetworkCertificate | 主機能 | ネットワーク証明書の取得 |
| 616 | Set-DbaNetworkCertificate | 主機能 | ネットワーク証明書の設定 |
| 615 | Remove-DbaNetworkCertificate | 主機能 | ネットワーク証明書の削除 |
| - | Get-DbaNetworkConfiguration | 補助機能 | 証明書情報を含むネットワーク設定の取得 |
| - | New-DbaComputerCertificate | 遷移元機能 | 新規証明書の作成とパイプライン連携 |
| - | Restart-DbaService | 補助機能 | 証明書変更後のサービス再起動 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

### Get-DbaNetworkCertificate

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

### Set-DbaNetworkCertificate

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス（デフォルト: localhost） |
| Credential | PSCredential | いいえ | 接続に使用するWindows資格情報 |
| Certificate | X509Certificate2 | はい（パラメータセット: Certificate） | 設定する証明書オブジェクト |
| Thumbprint | string | はい（パラメータセット: Thumbprint） | 設定する証明書のサムプリント |
| RestartService | switch | いいえ | 設定後にSQLサービスを再起動 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

### Remove-DbaNetworkCertificate

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

## 表示項目

### Get-DbaNetworkCertificate 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| VSName | string | 仮想サーバー名（クラスター環境） |
| ServiceAccount | string | SQLサービスアカウント |
| ForceEncryption | bool | 強制暗号化の有効/無効 |
| FriendlyName | string | 証明書のフレンドリー名 |
| DnsNameList | array | DNSサブジェクト代替名 |
| Thumbprint | string | 証明書のサムプリント |
| Generated | DateTime | 証明書の有効開始日 |
| Expires | DateTime | 証明書の有効期限 |
| IssuedTo | string | 発行先 |
| IssuedBy | string | 発行者 |
| Certificate | X509Certificate2 | 完全な証明書オブジェクト |

### Set-DbaNetworkCertificate 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| ServiceAccount | string | SQLサービスアカウント |
| CertificateThumbprint | string | 設定した証明書のサムプリント |
| Notes | string | 実行されたアクションの概要 |

### Remove-DbaNetworkCertificate 出力

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| ServiceAccount | string | SQLサービスアカウント |
| RemovedThumbprint | string | 削除された証明書のサムプリント |

## イベント仕様

### 1-Get-DbaNetworkCertificate実行

1. SqlInstanceパラメータを処理
2. Get-DbaNetworkConfigurationを内部で呼び出し（OutputType = "Certificate"）
3. Thumbprintが存在するインスタンスのみフィルタリングして返却

### 2-Set-DbaNetworkCertificate実行

1. 対象インスタンスへの管理者権限確認（Test-ElevationRequirement）
2. WMI経由でSQL Serverサービス情報を取得
3. レジストリルートパスの特定
4. 証明書の存在確認（LocalMachine証明書ストア）
5. 証明書秘密鍵へのサービスアカウント読み取り権限付与
6. レジストリへの証明書サムプリント設定
7. RestartServiceスイッチが有効な場合、SQL Serverサービスを再起動

### 3-Remove-DbaNetworkCertificate実行

1. ネットワーク名の解決（Resolve-DbaNetworkName）
2. WMI経由でSQL Serverサービス情報を取得
3. レジストリのCertificate値をnullに設定
4. 削除された証明書のサムプリントを含む結果を返却

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

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Set-DbaNetworkCertificate | Windowsレジストリ | UPDATE | SuperSocketNetLib\Certificate値の更新 |
| Set-DbaNetworkCertificate | ファイルシステム | UPDATE | 証明書秘密鍵のACL更新 |
| Remove-DbaNetworkCertificate | Windowsレジストリ | UPDATE | SuperSocketNetLib\Certificate値のクリア |

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

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

| 操作 | 項目（レジストリ値） | 更新値 | 備考 |
|-----|---------------------|--------|------|
| Set | Certificate | サムプリント（小文字） | 設定する証明書のサムプリント |
| Remove | Certificate | $null | 証明書設定のクリア |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Warning | New certificate will not take effect until SQL Server services are restarted | RestartServiceなしでSet実行時 |
| - | Error | Certificate does not exist on {ComputerName} | 指定されたサムプリントの証明書が存在しない |
| - | Error | Read-only permissions could not be granted to certificate | 秘密鍵への権限付与失敗 |
| - | Error | Failed to access {instance} | WMI接続失敗 |
| - | Error | Can't resolve {instance} | 名前解決失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| 管理者権限不足 | Test-ElevationRequirementで検出、警告表示して処理継続 |
| インスタンス名解決失敗 | Turboモードでの解決を試行、失敗時は処理中止 |
| WMI接続失敗 | エラー記録して次のインスタンスへ継続 |
| 証明書が存在しない | 警告メッセージ表示して終了 |
| 秘密鍵パス特定失敗 | 警告メッセージ表示して終了 |
| PowerShellリモーティング失敗 | エラー記録して次のインスタンスへ継続 |

## 備考

- 証明書の変更はSQL Serverサービスの再起動後に有効となる
- クラスター環境では各ノードで個別に設定が必要
- 証明書にはLocalMachine証明書ストアに配置された秘密鍵付きの証明書が必要
- サポートされるキーアルゴリズム: RSA、ECDSA、DSA

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | 出力オブジェクトのプロパティ定義（.OUTPUTSセクション） |
| 1-2 | Set-DbaNetworkCertificate.ps1 | `public/Set-DbaNetworkCertificate.ps1` | 出力PSCustomObjectの構造（行241-248） |

**読解のコツ**: PowerShellの`[PSCustomObject]@{}`構文で定義されているハッシュテーブルが出力オブジェクトの構造を示している。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | Get-DbaNetworkConfigurationの呼び出しとフィルタリング |

**主要処理フロー**:
1. **行71**: OutputTypeパラメータを"Certificate"に設定
2. **行72**: Get-DbaNetworkConfigurationを呼び出し、Thumbprintでフィルタリング

#### Step 3: Set-DbaNetworkCertificateの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaNetworkCertificate.ps1 | `public/Set-DbaNetworkCertificate.ps1` | パラメータセット定義とメイン処理フロー |

**主要処理フロー**:
- **行100-105**: 証明書またはサムプリントの検証
- **行121-147**: WMI経由でのSQL Serverサービス情報取得とレジストリパス特定
- **行156-248**: リモート実行用スクリプトブロック（証明書権限設定、レジストリ更新）
- **行167-174**: 証明書の存在確認
- **行181-184**: サービスアカウントへの読み取り権限付与
- **行186-212**: 秘密鍵パスの特定（RSA/ECDSA/DSA対応）
- **行220-223**: ACL設定
- **行226**: レジストリへのサムプリント書き込み
- **行254-255**: RestartServiceオプション時のサービス再起動

#### Step 4: Remove-DbaNetworkCertificateの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaNetworkCertificate.ps1 | `public/Remove-DbaNetworkCertificate.ps1` | 証明書設定削除のフロー |

**主要処理フロー**:
- **行82-98**: ネットワーク名解決とWMI接続
- **行124-141**: リモート実行用スクリプトブロック（レジストリ値のクリア）
- **行131-132**: サムプリントの取得とnull設定

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

```
Get-DbaNetworkCertificate
    |
    +-- Get-DbaNetworkConfiguration (OutputType="Certificate")
           |
           +-- Invoke-ManagedComputerCommand
           +-- Invoke-Command2
           +-- Get-ChildItem Cert:\LocalMachine

Set-DbaNetworkCertificate
    |
    +-- Test-ElevationRequirement
    +-- Invoke-ManagedComputerCommand
    |       +-- $wmi.Services
    |
    +-- Invoke-Command2 (リモートスクリプトブロック)
    |       +-- Get-ChildItem Cert:\LocalMachine
    |       +-- Get-Acl / Set-Acl
    |       +-- Set-ItemProperty (レジストリ)
    |
    +-- Restart-DbaService (オプション)

Remove-DbaNetworkCertificate
    |
    +-- Test-ElevationRequirement
    +-- Resolve-DbaNetworkName
    +-- Invoke-ManagedComputerCommand
    +-- Invoke-Command2 (リモートスクリプトブロック)
            +-- Get-ItemProperty
            +-- Set-ItemProperty (Certificate = $null)
```

### データフロー図

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

SqlInstance ────────▶ Resolve-DbaNetworkName ────────▶ FullComputerName
                              |
Credential ─────────────────▶ |
                              v
                     Invoke-ManagedComputerCommand
                              |
                              v
                     WMI Services情報取得
                              |
                              v
                     レジストリパス特定
                              |
                              v
Certificate/        Invoke-Command2 (リモート) ────────▶ PSCustomObject
Thumbprint ─────────────────▶ |                           (結果)
                              |
                              +-- 証明書存在確認
                              +-- 秘密鍵ACL設定
                              +-- レジストリ更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | ソース | 証明書取得コマンド |
| Set-DbaNetworkCertificate.ps1 | `public/Set-DbaNetworkCertificate.ps1` | ソース | 証明書設定コマンド |
| Remove-DbaNetworkCertificate.ps1 | `public/Remove-DbaNetworkCertificate.ps1` | ソース | 証明書削除コマンド |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | ネットワーク設定取得（証明書含む） |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決ユーティリティ |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動コマンド |
