# 機能設計書 595-Get-DbaComputerCertificate

## 概要

本ドキュメントは、WindowsコンピュータからSQL Server TLS暗号化に使用可能なX.509証明書を取得するPowerShellコマンドレット `Get-DbaComputerCertificate` の機能設計書である。

### 本機能の処理概要

本機能は、Windows証明書ストアからX.509証明書を取得し、SQL Serverネットワーク暗号化の設定に使用できる証明書を特定するコマンドレットである。

**業務上の目的・背景**：SQL ServerのForce Encryption設定やTLS接続には、適切な証明書が必要となる。従来は証明書MMCスナップインを使用して手動で証明書を確認していたが、本コマンドを使用することで、複数サーバーの証明書インベントリの取得、有効期限の確認、SQL Server用途に適した証明書（サーバー認証EKU付き）のフィルタリングを自動化できる。

**機能の利用シーン**：
- SQL Serverネットワーク暗号化設定前の証明書確認
- 証明書有効期限の監視と事前更新計画
- 複数サーバーの証明書インベントリ作成
- 証明書のサムプリント確認（Set-DbaNetworkCertificate用）
- セキュリティ監査での証明書一覧取得

**主要な処理内容**：
1. ローカルまたはリモートコンピュータに接続
2. 指定された証明書ストア（デフォルト: LocalMachine）とフォルダ（デフォルト: My）を検索
3. 証明書を取得し、必要に応じてサーバー認証EKU（1.3.6.1.5.5.7.3.1）でフィルタリング
4. サムプリントによる追加フィルタリング（指定時）
5. 証明書情報を整形して出力

**関連システム・外部連携**：Windows証明書ストアAPI（.NET System.Security.Cryptography.X509Certificates）を使用。PowerShellリモーティングでリモートコンピュータにアクセス。

**権限による制御**：ローカル実行時は通常のユーザー権限で実行可能。リモート実行時はPowerShellリモーティング（WinRM）へのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 証明書MMC (certmgr.msc / certlm.msc) | 参照画面 | 証明書ストアの内容確認 |
| - | PowerShellコンソール | 主画面 | コマンドの実行および結果表示 |

## 機能種別

データ取得処理 / 情報収集

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ（デフォルト: localhost） | 有効なコンピュータ名 |
| Credential | PSCredential | No | リモートコンピュータ接続用の資格情報 | 有効なPSCredentialオブジェクト |
| Store | string[] | No | 証明書ストア場所（デフォルト: LocalMachine） | LocalMachine または CurrentUser |
| Folder | string[] | No | 証明書フォルダ（デフォルト: My） | My, Root, AddressBook等 |
| Type | string | No | 証明書タイプフィルタ（デフォルト: Service） | ValidateSet: "All", "Service" |
| Path | string | No | 証明書ファイルのパス | ファイルシステムパス |
| Thumbprint | string[] | No | フィルタリング用サムプリント | 証明書サムプリント形式 |
| EnableException | switch | No | 例外を直接スローするフラグ | - |

### 入力データソース

- ComputerNameパラメータ：ユーザー指定のコンピュータ名（デフォルトは環境変数$env:COMPUTERNAME）
- Credential：Windows認証用の資格情報
- Path：証明書ファイル（.cer, .crt, .pfx）を直接読み込む場合のパス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 証明書が格納されているコンピュータ名 |
| Store | string | 証明書ストア場所（LocalMachine / CurrentUser） |
| Folder | string | 証明書フォルダ名（My, Root等） |
| Name | string | 証明書のフレンドリー名 |
| DnsNameList | string[] | 証明書に関連付けられたDNS名リスト |
| Thumbprint | string | 証明書のSHA-1サムプリント |
| NotBefore | DateTime | 証明書の有効開始日時 |
| NotAfter | DateTime | 証明書の有効期限日時 |
| Subject | string | 証明書のサブジェクト（発行先） |
| Issuer | string | 証明書の発行者 |
| Algorithm | string | 署名アルゴリズム |

### 出力先

- PowerShellパイプライン：System.Security.Cryptography.X509Certificates.X509Certificate2 オブジェクト（追加プロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. パラメータ処理
   └─ Pathパラメータ指定時: ファイルから証明書を読み込み
   └─ Store/Folder指定時: 証明書ストアを検索
2. 各コンピュータに対するループ処理
   └─ Store="All"の場合: 全ストアを取得
   └─ Folder="All"の場合: 全フォルダを取得
3. 各Store/Folderの組み合わせでループ
   └─ Invoke-Command2でリモート実行
   └─ Get-CoreCertStoreで証明書ストアオープン
   └─ Get-CoreCertificateで証明書取得
4. フィルタリング
   └─ Thumbprint指定時: サムプリントでフィルタ
   └─ Type="Service"時: サーバー認証EKUでフィルタ
5. プロパティ追加と出力
   └─ Algorithm, ComputerName, Name, Store, Folder追加
   └─ Select-DefaultViewで表示プロパティ制限
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path指定?}
    B -->|Yes| C[ファイルから証明書読み込み]
    B -->|No| D[ストア検索モード]
    C --> Z[終了]
    D --> E{Store=All?}
    E -->|Yes| F[全ストア取得]
    E -->|No| G[指定ストア使用]
    F --> H{Folder=All?}
    G --> H
    H -->|Yes| I[全フォルダ取得]
    H -->|No| J[指定フォルダ使用]
    I --> K[Store/Folderループ]
    J --> K
    K --> L[Invoke-Command2実行]
    L --> M{Thumbprint指定?}
    M -->|Yes| N[サムプリントでフィルタ]
    M -->|No| O{Type=Service?}
    N --> P[結果出力]
    O -->|Yes| Q[EKUフィルタ適用]
    O -->|No| R[全証明書取得]
    Q --> P
    R --> P
    P --> S{次のStore/Folder?}
    S -->|Yes| K
    S -->|No| T{次のコンピュータ?}
    T -->|Yes| E
    T -->|No| Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトストア | LocalMachineストアをデフォルトで検索 | Store未指定時 |
| BR-002 | デフォルトフォルダ | Myフォルダ（個人証明書）をデフォルトで検索 | Folder未指定時 |
| BR-003 | サービス証明書フィルタ | Type=ServiceでサーバーAuthentication EKU (1.3.6.1.5.5.7.3.1)付き証明書のみ取得 | デフォルト動作 |
| BR-004 | ファイル読み込み優先 | Path指定時はStore/Folder検索をバイパス | Path指定時 |

### 計算ロジック

該当なし

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

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

本機能はWindows証明書ストアを読み取るため、データベース操作は発生しない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | コンピュータ接続失敗 | ネットワーク接続とWinRM設定を確認 |
| - | 例外（サイレント） | 証明書ストアアクセスエラー | catchブロックでサイレント処理 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を中断し、次のコンピュータに進む。

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

該当なし（読み取り専用処理）

## パフォーマンス要件

- PowerShellリモーティングのレイテンシに依存
- 証明書数に比例した処理時間
- 通常は数秒以内に完了

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

- リモート実行時はPowerShellリモーティング権限が必要
- 証明書の秘密鍵は取得できない（PublicKey情報のみ）
- 証明書のサムプリントは機密情報ではないが、使用中の証明書を特定可能

## 備考

- SQL Serverネットワーク暗号化にはLocalMachine\My内の証明書を使用
- サーバー認証EKU（1.3.6.1.5.5.7.3.1）を持つ証明書のみがSQL Serverで使用可能
- 証明書のサムプリントはSet-DbaNetworkCertificateで使用

---

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

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

### 推奨読解順序

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

X509Certificate2オブジェクトの構造と追加プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | 177-183行目のAdd-Member定義 |

**読解のコツ**: X509Certificate2オブジェクトにAlgorithm, ComputerName, Name, Store, Folderプロパティを追加している。FriendlyNameプロパティはリモート実行時に問題があるためNameプロパティとして追加。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | 関数定義全体の構造 |

**主要処理フロー**:
1. **103-115行目**: パラメータ定義
2. **117-213行目**: begin/processブロック
3. **119-212行目**: ScriptBlock定義（リモート実行用）

#### Step 3: 内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | Get-CoreCertStore関数 |
| 3-2 | Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | Get-CoreCertificate関数 |

**主要処理フロー**:
- **134-152行目**: Get-CoreCertStore - 証明書ストアのオープン
- **154-185行目**: Get-CoreCertificate - 証明書取得とプロパティ追加
- **187-196行目**: Thumbprint指定時のフィルタリング
- **197-211行目**: Type指定に基づくEKUフィルタリング

#### Step 4: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | processブロックのループ処理 |

**主要処理フロー**:
- **216-224行目**: Store="All"時の全ストア取得
- **225-231行目**: Folder="All"時の全フォルダ取得
- **232-240行目**: Store/Folderの組み合わせでInvoke-Command2実行
- **235行目**: Select-DefaultViewで出力プロパティを制限

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

```
Get-DbaComputerCertificate
    │
    ├─ Invoke-Command2 (リモート実行)
    │      │
    │      ├─ [Pathモード] ファイルから証明書読み込み
    │      │      └─ X509Certificate2.Import()
    │      │
    │      └─ [ストアモード]
    │             ├─ Get-CoreCertStore
    │             │      └─ X509Store.Open()
    │             │
    │             └─ Get-CoreCertificate
    │                    ├─ X509Store.Certificates取得
    │                    ├─ Thumbprintフィルタ（オプション）
    │                    ├─ EKUフィルタ（Type=Service時）
    │                    └─ Add-Member でプロパティ追加
    │
    └─ Select-DefaultView
           └─ 表示プロパティの制限
```

### データフロー図

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

ComputerName ───────────▶ Invoke-Command2
                                │
        ┌───────────────────────┴───────────────────────┐
        │                                               │
   [Pathモード]                                    [ストアモード]
        │                                               │
        ▼                                               ▼
   ファイル読み込み                            X509Store.Open()
        │                                               │
        ▼                                               ▼
   X509Certificate2                              Certificates[]
        │                                               │
        │                       ┌───────────────────────┘
        │                       │
        │               Thumbprintフィルタ
        │                       │
        │               EKUフィルタ (Type=Service)
        │                       │
        └───────────┬───────────┘
                    │
                    ▼
              Add-Member
                    │
                    ▼
            Select-DefaultView
                    │
                    ▼
            パイプライン出力 ───▶ コンソール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaComputerCertificate.ps1 | `public/Get-DbaComputerCertificate.ps1` | ソース | メイン機能実装 |
| Add-DbaComputerCertificate.ps1 | `public/Add-DbaComputerCertificate.ps1` | ソース | 証明書インポート機能 |
| Remove-DbaComputerCertificate.ps1 | `public/Remove-DbaComputerCertificate.ps1` | ソース | 証明書削除機能 |
| Set-DbaNetworkCertificate.ps1 | `public/Set-DbaNetworkCertificate.ps1` | ソース | SQL Server証明書設定機能 |
