# 機能設計書 598-Get-DbaDbEncryption

## 概要

本ドキュメントは、SQL Serverデータベースの包括的な暗号化インベントリを取得するPowerShellコマンドレット `Get-DbaDbEncryption` の機能設計書である。

### 本機能の処理概要

本機能は、SQL Serverデータベースに格納されているすべての種類の暗号化オブジェクト（TDE、証明書、非対称キー、対称キー）を一括で取得し、暗号化監査とコンプライアンスレポート作成を支援するコマンドレットである。

**業務上の目的・背景**：セキュリティ監査やコンプライアンス対応において、データベースで使用されている暗号化技術の全体像を把握する必要がある。個別のコマンド（Get-DbaDbCertificate、Get-DbaDbAsymmetricKey等）を使用する代わりに、本コマンドは一度の実行で全暗号化オブジェクトを取得し、統一されたフォーマットで出力する。これにより、暗号化アルゴリズムの強度確認、キー有効期限の監視、バックアップ状態の確認を効率的に行える。

**機能の利用シーン**：
- 定期的なセキュリティ監査での暗号化インベントリ作成
- コンプライアンス報告書（SOC2、PCI-DSS、HIPAA等）作成
- 暗号化キーのライフサイクル管理
- TDE有効化状態の確認
- 暗号化アルゴリズム強度の環境全体での確認

**主要な処理内容**：
1. Connect-DbaInstance経由で対象インスタンスに接続
2. 各データベースに対して以下の暗号化オブジェクトを取得：
   - TDE暗号化状態（EncryptionEnabled）
   - 証明書（Certificates）
   - 非対称キー（AsymmetricKeys）
   - 対称キー（SymmetricKeys）
3. 各オブジェクトを統一されたPSCustomObject形式で出力
4. TDE有効時はmasterデータベースのサーバー証明書情報も取得

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスに接続し、各種暗号化オブジェクトのコレクションを取得する。

**権限による制御**：対象データベースに対するVIEW DEFINITION権限およびVIEW DATABASE STATE権限が必要。TDE情報取得にはmasterデータベースへのアクセス権限も必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio | 参照画面 | データベースプロパティ、セキュリティフォルダで確認 |
| - | PowerShellコンソール | 主画面 | コマンドの実行および結果表示 |

## 機能種別

データ取得処理 / セキュリティ監査 / レポート生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力対応、Mandatory |
| SqlCredential | PSCredential | No | 接続用の代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | object[] | No | 検索対象データベース名 | データベース名 |
| ExcludeDatabase | object[] | No | 除外するデータベース名 | データベース名 |
| IncludeSystemDBs | switch | No | システムデータベースを含める | - |
| EnableException | switch | No | 例外を直接スローするフラグ | - |

### 入力データソース

- SqlInstanceパラメータ：ユーザー指定のSQL Serverインスタンス名（Mandatory）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| Database | string | 暗号化オブジェクトが格納されているデータベース名 |
| Encryption | string | 暗号化タイプ（EncryptionEnabled (TDE), Certificate, Asymmetric key, Symmetric key） |
| Name | string | 暗号化オブジェクトの名前 |
| Owner | string | 暗号化オブジェクトの所有者 |
| LastBackup | DateTime | 最後のバックアップ日時（証明書、TDEのみ） |
| PrivateKeyEncryptionType | string | 秘密鍵の暗号化タイプ |
| EncryptionAlgorithm | string | 暗号化アルゴリズム（TDE、非対称キーのみ） |
| KeyLength | int | キー長（非対称キー、対称キーのみ） |
| ExpirationDate | DateTime | 有効期限日時（証明書、TDEのみ） |
| Object | object | 元のSMOオブジェクト |

### 出力先

- PowerShellパイプライン：PSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続
   └─ Connect-DbaInstance経由でSMO Serverオブジェクト取得
2. データベース取得
   └─ Database指定時: 指定DBのみ
   └─ IncludeSystemDBs時: 全アクセス可能DB
   └─ デフォルト: ユーザーDBのみ（IsSystemObject=false）
   └─ ExcludeDatabase適用
3. 各データベースに対するループ処理
   └─ TDE暗号化チェック
       └─ 有効時: masterのサーバー証明書情報取得
       └─ PSCustomObject生成
   └─ 証明書ループ
       └─ PSCustomObject生成
   └─ 非対称キーループ
       └─ PSCustomObject生成
   └─ 対称キーループ
       └─ PSCustomObject生成
4. パイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function: 接続失敗]
    C -->|Yes| E[データベース取得]
    E --> F{Database指定?}
    F -->|Yes| G[指定DBフィルタ]
    F -->|No| H{IncludeSystemDBs?}
    H -->|Yes| I[全アクセス可能DB]
    H -->|No| J[ユーザーDBのみ]
    G --> K[ExcludeDatabase適用]
    I --> K
    J --> K
    K --> L{次のDBあり?}
    L -->|No| Z[終了]
    L -->|Yes| M{TDE有効?}
    M -->|Yes| N[サーバー証明書取得]
    N --> O[TDE PSCustomObject出力]
    M -->|No| P[証明書ループ]
    O --> P
    P --> Q[各証明書 PSCustomObject出力]
    Q --> R[非対称キーループ]
    R --> S[各キー PSCustomObject出力]
    S --> T[対称キーループ]
    T --> U[各キー PSCustomObject出力]
    U --> L
    D --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムDB除外 | デフォルトでシステムDBを除外 | IncludeSystemDBs未指定時 |
| BR-002 | TDE証明書取得 | TDE有効時はmasterのサムプリント一致証明書を取得 | EncryptionEnabled=true時 |
| BR-003 | 統一出力形式 | 全暗号化タイプを同一のPSCustomObject形式で出力 | 常時 |
| BR-004 | アクセス可能DBのみ | IsAccessible=trueのDBのみ処理 | 常時 |

### 計算ロジック

TDE証明書の特定ロジック：
```
masterデータベースの証明書のうち、
DatabaseEncryptionKey.Thumbprint と Certificate.Thumbprint が一致するものを取得
（Compare-Object -SyncWindow 0 で比較）
```

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読み取り | sys.dm_database_encryption_keys | SELECT（間接） | TDE暗号化状態取得 |
| 読み取り | sys.certificates | SELECT（間接） | 証明書メタデータ取得 |
| 読み取り | sys.asymmetric_keys | SELECT（間接） | 非対称キーメタデータ取得 |
| 読み取り | sys.symmetric_keys | SELECT（間接） | 対称キーメタデータ取得 |

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

各暗号化オブジェクト種別ごとにSMO経由で対応するシステムカタログから情報取得。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | Stop-Function | インスタンス接続失敗 | 接続情報を確認 |
| - | Stop-Function | TDEサーバー証明書が見つからない | masterデータベースの証明書を確認 |
| - | Stop-Function | データベース取得失敗 | データベース状態を確認 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を中断。

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

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

## パフォーマンス要件

- データベース数と暗号化オブジェクト数に比例した処理時間
- 大規模環境では複数のSMOコレクションアクセスによりオーバーヘッドが発生

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

- VIEW DEFINITION、VIEW DATABASE STATE権限が必要
- masterデータベースへのアクセス権限が必要（TDE証明書取得時）
- 秘密鍵の内容は取得できない（メタデータのみ）

## 備考

- 統一された出力形式により、複数の暗号化タイプを一括で比較・分析可能
- 元のSMOオブジェクトはObjectプロパティから取得可能
- 対称キーの出力にはServer, Instanceプロパティ名が使用されている（他とは異なる）

---

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

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

### 推奨読解順序

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

出力PSCustomObjectの統一フォーマットを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | 135-149行目（TDE用PSCustomObject） |
| 1-2 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | 173-188行目（証明書用PSCustomObject） |
| 1-3 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | 191-206行目（非対称キー用PSCustomObject） |
| 1-4 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | 209-223行目（対称キー用PSCustomObject） |

**読解のコツ**: 4種類の暗号化オブジェクトを同一フォーマットで出力するが、各タイプで有効なプロパティが異なる。nullが設定されるプロパティもある。

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

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

**主要処理フロー**:
1. **92-101行目**: パラメータ定義（SqlInstanceがMandatory）
2. **103-111行目**: インスタンス接続とエラー処理
3. **115-129行目**: データベースフィルタリングロジック

#### Step 3: TDE暗号化チェックとサーバー証明書取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | TDE判定とサーバー証明書マッチング |

**主要処理フロー**:
- **134行目**: EncryptionEnabledプロパティでTDE判定
- **151-154行目**: masterデータベースからサムプリント一致の証明書を検索
- **156-158行目**: 証明書が見つからない場合のStop-Function
- **160-167行目**: サーバー証明書情報をTDE出力に設定

#### Step 4: 各暗号化オブジェクトループを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | 各種暗号化オブジェクトの取得ループ |

**主要処理フロー**:
- **172-189行目**: 証明書ループ（foreach $cert in $db.Certificates）
- **191-208行目**: 非対称キーループ（foreach $ak in $db.AsymmetricKeys）
- **209-224行目**: 対称キーループ（foreach $sk in $db.SymmetricKeys）

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

```
Get-DbaDbEncryption
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続
    │
    └─ foreach ($db in $dbs)
           │
           ├─ TDE判定 ($db.EncryptionEnabled)
           │      │
           │      └─ [TDE有効時]
           │             ├─ masterデータベース証明書検索
           │             │      └─ Compare-Object でサムプリント比較
           │             └─ TDE PSCustomObject出力
           │
           ├─ foreach ($cert in $db.Certificates)
           │      └─ Certificate PSCustomObject出力
           │
           ├─ foreach ($ak in $db.AsymmetricKeys)
           │      └─ Asymmetric key PSCustomObject出力
           │
           └─ foreach ($sk in $db.SymmetricKeys)
                  └─ Symmetric key PSCustomObject出力
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ───▶ SMO Server
                                │
                                ▼
                        データベースフィルタリング
                                │
                                ▼
                        ┌───────┴───────┐
                        │               │
                    TDE有効?        各暗号化オブジェクト
                        │               │
                        ▼               │
                master証明書取得        │
                        │               │
                        ▼               ▼
                    TDE出力        Certificate出力
                                        │
                                        ▼
                                Asymmetric key出力
                                        │
                                        ▼
                                Symmetric key出力
                                        │
                                        ▼
                                パイプライン出力 ───▶ コンソール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbEncryption.ps1 | `public/Get-DbaDbEncryption.ps1` | ソース | メイン機能実装 |
| Get-DbaDbCertificate.ps1 | `public/Get-DbaDbCertificate.ps1` | ソース | 証明書のみの取得機能 |
| Get-DbaDbAsymmetricKey.ps1 | `public/Get-DbaDbAsymmetricKey.ps1` | ソース | 非対称キーのみの取得機能 |
| Get-DbaDbEncryptionKey.ps1 | `public/Get-DbaDbEncryptionKey.ps1` | ソース | TDE DEKのみの取得機能 |
