# 機能設計書 600-Get-DbaDbMasterKey

## 概要

本ドキュメントは、SQL Serverデータベースからデータベースマスターキー（Database Master Key）情報を取得するPowerShellコマンドレット `Get-DbaDbMasterKey` の機能設計書である。

### 本機能の処理概要

本機能は、SQL Serverデータベースに格納されているデータベースマスターキー（DMK）の情報を取得し、暗号化階層の管理やセキュリティ監査に使用するコマンドレットである。

**業務上の目的・背景**：データベースマスターキーは、SQL Serverの暗号化階層において重要な役割を果たす。DMKは証明書、非対称キー、対称キーを保護するために使用され、TDE、列レベル暗号化、Service Brokerなどの機能で必要となる。本コマンドは、複数データベースのDMK存在確認、作成日・更新日の監視、サーバーマスターキーによる暗号化状態の確認を一括で行える。

**機能の利用シーン**：
- 暗号化階層のセキュリティ監査
- DMK存在確認（暗号化機能使用前の前提条件確認）
- DMKのライフサイクル管理（作成日、更新日確認）
- サーバーマスターキー暗号化状態の確認
- 複数データベース間でのDMK構成比較

**主要な処理内容**：
1. SqlInstanceパラメータ使用時はGet-DbaDatabase経由で対象データベースを取得
2. 各データベースのMasterKeyプロパティにアクセス
3. DMKが存在しない場合はスキップ（Verboseログ出力）
4. SMO MasterKeyオブジェクトに追加プロパティを付与
5. 結果をパイプラインに出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスに接続し、MasterKeyプロパティを取得する。

**権限による制御**：対象データベースに対するVIEW DEFINITION権限が必要。DMKのメタデータを読み取るためには適切な権限が必要。

## 関連画面

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

## 機能種別

データ取得処理 / セキュリティ監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 接続用の代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | string[] | No | 検索対象データベース名（ワイルドカード対応） | データベース名 |
| ExcludeDatabase | string[] | No | 除外するデータベース名（ワイルドカード対応） | データベース名 |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力用データベースオブジェクト | SMO Databaseオブジェクト |
| EnableException | switch | No | 例外を直接スローするフラグ | - |

### 入力データソース

- SqlInstanceパラメータ：ユーザー指定のSQL Serverインスタンス名
- InputObject：Get-DbaDatabase等の他のdbatoolsコマンドからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| Database | string | DMKが格納されているデータベース名 |
| CreateDate | DateTime | DMKの作成日時 |
| DateLastModified | DateTime | DMKの最終更新日時 |
| IsEncryptedByServer | bool | サーバーマスターキーで暗号化されているかどうか |

### 出力先

- PowerShellパイプライン：Microsoft.SqlServer.Management.Smo.MasterKey オブジェクト（追加プロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. 対象データベース取得
   └─ SqlInstance使用時: Get-DbaDatabase経由で取得
   └─ InputObject使用時: パイプライン入力をそのまま使用
2. 各データベースに対するループ処理
   └─ アクセシビリティチェック（IsAccessible）
   └─ MasterKeyプロパティ取得
   └─ DMKが存在しない場合はスキップ（Verboseログ出力）
3. プロパティ追加と出力
   └─ ComputerName, InstanceName, SqlInstance, Database追加
   └─ Select-DefaultViewで表示プロパティ制限
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDatabase実行]
    B -->|No| D[InputObjectを使用]
    C --> E[対象DB取得完了]
    D --> E
    E --> F{次のDBあり?}
    F -->|No| Z[終了]
    F -->|Yes| G{IsAccessible?}
    G -->|No| H[警告出力してスキップ]
    H --> F
    G -->|Yes| I[MasterKey取得]
    I --> J{DMKあり?}
    J -->|No| K[Verboseログ出力]
    K --> F
    J -->|Yes| L[プロパティ追加]
    L --> M[Select-DefaultView]
    M --> N[パイプライン出力]
    N --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクセシビリティチェック | IsAccessible=falseのデータベースはスキップ | 各データベース処理時 |
| BR-002 | DMK存在判定 | MasterKeyプロパティの真偽でDMK存在を判定 | 各データベース処理時 |
| BR-003 | 空コレクション処理 | DMKが存在しない場合はVerboseログのみ | DMK未存在時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読み取り | sys.symmetric_keys | SELECT（間接） | SMO経由でDMK情報取得（symmetric_key_id = 101） |

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

#### sys.symmetric_keys（DMK専用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | create_date, modify_date | symmetric_key_id = 101 | SMO MasterKeyオブジェクト経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Warning | データベースにアクセス不可 | データベース状態を確認 |
| - | Verbose | DMKが存在しない | 情報メッセージのみ（正常動作） |

### リトライ仕様

リトライ処理は実装されていない。アクセス不可データベースはスキップして処理を継続。

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

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

## パフォーマンス要件

- データベース数に比例した処理時間
- DMKが存在するデータベースのみ出力

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

- VIEW DEFINITION権限が必要
- DMKの秘密情報は取得できない（メタデータのみ）
- IsEncryptedByServerでサーバーマスターキー依存性を確認可能

## 備考

- DMKはTDE、列レベル暗号化、Service Brokerなどの前提条件
- IsEncryptedByServer=trueの場合、サーバーマスターキーのバックアップも必要
- DMKのパスワードバックアップは別途必要

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: SMO MasterKeyオブジェクトにComputerName, InstanceName, SqlInstance, Databaseプロパティを追加している。$db.Parent（Serverオブジェクト）からインスタンス情報を取得。

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

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

**主要処理フロー**:
1. **80-89行目**: パラメータ定義
2. **91-94行目**: SqlInstance指定時のGet-DbaDatabase呼び出し
3. **96-115行目**: データベースループとDMK取得

#### Step 3: DMK取得と存在チェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbMasterKey.ps1 | `public/Get-DbaDbMasterKey.ps1` | DMK取得と存在判定 |

**主要処理フロー**:
- **96-100行目**: IsAccessibleチェックとスキップ処理
- **101-102行目**: インスタンス名とMasterKeyプロパティ取得
- **104-107行目**: DMK未存在時のVerboseログ出力
- **109-114行目**: プロパティ追加とSelect-DefaultView

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

```
Get-DbaDbMasterKey
    │
    ├─ Get-DbaDatabase (SqlInstance使用時)
    │      └─ Connect-DbaInstance
    │
    └─ foreach ($db in $InputObject)
           │
           ├─ IsAccessibleチェック
           │
           ├─ $db.MasterKey
           │      └─ SMO経由でsys.symmetric_keys (key_id=101)から取得
           │
           ├─ 存在チェック (!$masterkey)
           │
           ├─ Add-Member (プロパティ追加)
           │      └─ $db.Parent.ComputerName
           │      └─ $db.Parent.ServiceName
           │      └─ $db.Parent.DomainInstanceName
           │
           └─ Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance ───────────▶ Get-DbaDatabase ───▶ SMO Database[]
        or
InputObject ─────────────────────────────────▶ SMO Database[]
                                                    │
                                                    ▼
                                            IsAccessibleチェック
                                                    │
                                                    ▼
                                            MasterKey取得
                                                    │
                                                    ▼
                                            DMK存在チェック
                                                    │
                                                    ▼
                                            Add-Member
                                                    │
                                                    ▼
                                            Select-DefaultView
                                                    │
                                                    ▼
                                            パイプライン出力 ───▶ コンソール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbMasterKey.ps1 | `public/Get-DbaDbMasterKey.ps1` | ソース | メイン機能実装 |
| New-DbaDbMasterKey.ps1 | `public/New-DbaDbMasterKey.ps1` | ソース | DMK作成機能 |
| Remove-DbaDbMasterKey.ps1 | `public/Remove-DbaDbMasterKey.ps1` | ソース | DMK削除機能 |
| Backup-DbaDbMasterKey.ps1 | `public/Backup-DbaDbMasterKey.ps1` | ソース | DMKバックアップ機能 |
| Restore-DbaDbMasterKey.ps1 | `public/Restore-DbaDbMasterKey.ps1` | ソース | DMKリストア機能 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得機能 |
