# 機能設計書 602-Get-DbaNetworkCertificate

## 概要

本ドキュメントは、SQL Serverのネットワーク暗号化に使用されている証明書を取得する`Get-DbaNetworkCertificate`機能の設計書である。

### 本機能の処理概要

`Get-DbaNetworkCertificate`は、SQL Serverインスタンスがネットワーク暗号化とSSL接続のために使用するように構成された特定のコンピュータ証明書を取得する機能である。ローカル証明書ストアからSQL Serverインスタンスが実際に使用している証明書の詳細情報を返す。証明書が構成されていないインスタンスは結果に表示されない。

**業務上の目的・背景**：SSL構成の監査、暗号化接続の問題のトラブルシューティング、および複数のインスタンス間での証明書割り当ての検証に有用である。企業のセキュリティポリシーに従って、適切な証明書がSQL Serverに構成されているかを確認する必要がある。また、証明書の有効期限管理や、証明書更新時の確認作業にも使用される。

**機能の利用シーン**：
- SQL Server SSL構成の監査
- 暗号化された接続に関する問題のトラブルシューティング
- 複数インスタンス間での証明書割り当て状況の検証
- 証明書の有効期限確認と更新計画
- コンプライアンス要件の検証

**主要な処理内容**：
1. Get-DbaNetworkConfigurationを-OutputType Certificateで呼び出し
2. Thumbprintが存在するインスタンスのみをフィルタリング
3. 証明書情報を含むPSCustomObjectを返却

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

**権限による制御**：ターゲットコンピュータへの管理者権限とWinRM接続権限が必要。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- Get-DbaNetworkConfiguration経由で取得される情報
- Windows証明書ストア（Cert:\LocalMachine）
- SQL Server WMI
- Windowsレジストリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverをホストするコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス形式） |
| VSName | String | 仮想サーバー名（クラスタインスタンスの場合） |
| ServiceAccount | String | SQL Serverを実行しているWindowsサービスアカウント |
| ForceEncryption | Boolean | すべての接続に暗号化が強制されているかどうか |
| FriendlyName | String | 証明書ストアでの人間が読める証明書名 |
| DnsNameList | String[] | 証明書のSubject Alternative NamesのDNS名配列 |
| Thumbprint | String | 証明書のSHA-1ハッシュサムプリント |
| Generated | DateTime | 証明書が有効になる日時（NotBefore） |
| Expires | DateTime | 証明書の有効期限（NotAfter） |
| IssuedTo | String | 証明書のサブジェクト（発行先） |
| IssuedBy | String | 証明書の発行者名 |
| Certificate | X509Certificate2 | 完全な証明書情報を含むX509Certificate2オブジェクト |

### 出力先

PowerShellパイプライン（PSCustomObject）- 証明書が構成されていないインスタンスはフィルタリングされる

## 処理フロー

### 処理シーケンス

```
1. PSBoundParametersにOutputType = "Certificate"を追加
   └─ Get-DbaNetworkConfiguration用のパラメータ準備
2. Get-DbaNetworkConfigurationを呼び出し
   └─ 証明書タイプでネットワーク構成情報を取得
3. Where-Object Thumbprintでフィルタリング
   └─ 証明書が構成されているインスタンスのみを抽出
4. 結果を出力
   └─ パイプラインに証明書情報を送出
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[OutputType = Certificate をセット]
    B --> C[Get-DbaNetworkConfiguration 呼び出し]
    C --> D[結果を受信]
    D --> E{Thumbprint が存在?}
    E -->|あり| F[結果を出力]
    E -->|なし| G[結果をフィルタアウト]
    F --> H{次のインスタンス?}
    G --> H
    H -->|あり| D
    H -->|なし| I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-602-01 | 証明書フィルタリング | Thumbprintが存在するインスタンスのみ結果に含める | 常時 |
| BR-602-02 | デフォルトインスタンス | SqlInstanceが指定されない場合はlocalhostを使用 | パラメータ未指定時 |
| BR-602-03 | 証明書未設定 | 証明書が設定されていないインスタンスは結果に表示されない | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | SQLデータベースへの直接アクセスなし |

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続失敗 | ターゲットコンピュータへの接続ができない場合 | Get-DbaNetworkConfigurationからのエラーが伝播 |
| - | 権限不足 | 必要な権限がない場合 | Get-DbaNetworkConfigurationからのエラーが伝播 |
| - | 証明書未設定 | 結果なし | 正常動作（空の結果を返す） |

### リトライ仕様

特になし（Get-DbaNetworkConfigurationに委譲）

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

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

## パフォーマンス要件

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

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

- 管理者権限が必要
- リモートマシンへの接続にはWinRM権限が必要
- 証明書情報の読み取りのみで書き込みは行わない
- X509Certificate2オブジェクトには秘密鍵情報が含まれる可能性があるため取り扱いに注意

## 備考

- 本機能はGet-DbaNetworkConfigurationのラッパーとして実装されている
- クラスタインスタンスの場合は各ノードを個別に指定する必要がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | 31-51行目のコメントで出力プロパティの構造を確認 |
| 1-2 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 101-116行目で-OutputType Certificate時の出力構造を確認 |

**読解のコツ**: 本機能は非常にシンプルなラッパーで、実際の処理はGet-DbaNetworkConfigurationに委譲されている。出力の構造を理解するには委譲先の実装を確認する必要がある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | 70-73行目がprocess ブロック全体 |

**主要処理フロー**:
1. **71行目**: OutputType = "Certificate" をPSBoundParametersに追加
2. **72行目**: Get-DbaNetworkConfigurationを呼び出し、Where-Object Thumbprintでフィルタリング

#### Step 3: 委譲先の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 139-278行目のスクリプトブロックでデータ収集処理 |
| 3-2 | Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | 355-379行目で-OutputType Certificate時の出力生成 |

**主要処理フロー**:
- **199-220行目**: レジストリからサムプリントを取得し、証明書ストアから証明書を検索
- **208-220行目**: outputCertificateオブジェクトの構築（VSName, ServiceAccount, ForceEncryption等）
- **359-374行目**: 最終的なPSCustomObjectの生成とSelect-DefaultViewでの表示プロパティ設定

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

```
Get-DbaNetworkCertificate
    │
    └─ Get-DbaNetworkConfiguration (OutputType = Certificate)
           │
           ├─ Resolve-DbaComputerName
           │      └─ コンピュータ名の解決
           │
           ├─ Test-ElevationRequirement
           │      └─ 管理者権限の確認
           │
           └─ Invoke-Command2 (スクリプトブロック)
                  │
                  ├─ Microsoft.SqlServer.Management.Smo.Wmi.ManagedComputer
                  │      └─ WMI経由でサービス情報取得
                  │
                  ├─ Get-ItemProperty (レジストリ)
                  │      └─ Certificate/ForceEncryption値取得
                  │
                  └─ Get-ChildItem Cert:\LocalMachine
                         └─ サムプリントに一致する証明書を検索
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaNetworkConfiguration
                              │
                              ▼
                    WMI / レジストリ / 証明書ストア
                              │
                              ▼
                    証明書情報収集
                    - Thumbprint
                    - FriendlyName                    Thumbprint存在時のみ
                    - DnsNameList        ───────▶    PSCustomObject
                    - Certificate Object              - ComputerName
                              │                       - InstanceName
                              ▼                       - SqlInstance
                    Where-Object Thumbprint           - 証明書プロパティ
                              │
                              ▼
                    フィルタリング済み結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaNetworkCertificate.ps1 | `public/Get-DbaNetworkCertificate.ps1` | ソース | メイン機能（ラッパー） |
| Get-DbaNetworkConfiguration.ps1 | `public/Get-DbaNetworkConfiguration.ps1` | ソース | 実際の処理を行う委譲先 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | PowerShellリモーティングラッパー |
| Resolve-DbaComputerName.ps1 | `private/functions/Resolve-DbaComputerName.ps1` | ソース | コンピュータ名解決 |
| Test-ElevationRequirement.ps1 | `private/functions/Test-ElevationRequirement.ps1` | ソース | 管理者権限確認 |
