# 機能設計書 614-Remove-DbaDbMasterKey

## 概要

本ドキュメントは、SQL Serverデータベースからデータベースマスターキーを削除するdbatools PowerShell関数 `Remove-DbaDbMasterKey` の機能設計書である。

### 本機能の処理概要

**業務上の目的・背景**：データベースマスターキー（DMK）は、SQL Serverの暗号化階層において他のデータベースレベルの暗号化キー（TDE用のDEK、Always Encrypted用のキー、証明書の秘密鍵など）を保護するために使用される。暗号化インフラストラクチャの廃止、異なる暗号化戦略への移行、またはコンプライアンス変更に伴うデータベースメンテナンス時に、未使用のマスターキーを削除する必要がある。本機能はこれらの運用タスクを効率的に実行するためのPowerShellコマンドを提供する。

**機能の利用シーン**：
- TDE廃止時の暗号化インフラストラクチャ削除
- 暗号化戦略の変更に伴うマスターキーの再作成
- インスタンス全体での暗号化クリーンアップ
- データベース移行前のセキュリティオブジェクト整理

**主要な処理内容**：
1. SqlInstanceパラメータが指定された場合、Database/ExcludeDatabase/Allパラメータのいずれかの必須チェック
2. Get-DbaDatabase経由でマスターキーを取得
3. 各マスターキーに対してDROP MASTER KEYコマンドを実行
4. 削除結果をPSCustomObjectとして出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスと連携する。SMOのDatabase.Queryメソッドを使用してT-SQLコマンドを実行する。

**権限による制御**：データベースマスターキーの削除には、対象データベースでのCONTROL権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 32 | マスターキー管理 | 主機能 | データベースマスターキーの削除 |

## 機能種別

データベース操作（DELETE）- セキュリティオブジェクト管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Database | string[] | 条件付き | 対象のデータベース名 | 有効なデータベース名 |
| ExcludeDatabase | string[] | 条件付き | 除外するデータベース名 | 有効なデータベース名 |
| All | switch | 条件付き | 全ユーザーデータベースを対象 | - |
| InputObject | Microsoft.SqlServer.Management.Smo.MasterKey[] | No | パイプライン入力用のマスターキーオブジェクト | 有効なMasterKeyオブジェクト |
| EnableException | switch | No | 例外処理の有効化 | - |
| WhatIf | switch | No | 実行せずに処理内容を表示 | - |
| Confirm | switch | No | 実行前に確認プロンプトを表示 | - |

### 入力データソース

- SqlInstanceパラメータ: コマンドライン引数
- InputObject: Get-DbaDbMasterKeyからのパイプライン入力
- SqlCredential: Get-Credentialコマンドレットまたは事前定義の資格情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | マスターキーが削除されたデータベース名 |
| Status | string | 削除結果（"Master key removed"または失敗メッセージ） |

### 出力先

PowerShellパイプライン - 呼び出し元のスクリプトまたはコンソールに出力

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ SqlInstance指定時にDatabase/ExcludeDatabase/Allのいずれかの必須チェック
2. データベースの取得
   └─ Get-DbaDatabase経由でデータベースとマスターキーを取得
3. マスターキーオブジェクトのループ処理
   └─ 各キーに対して以下を実行
4. ShouldProcess確認
   └─ WhatIfまたはConfirmの処理
5. DROP MASTER KEYコマンド実行
   └─ Database.Queryメソッドを使用してT-SQLを実行
6. 結果オブジェクトの出力
   └─ PSCustomObjectとして結果を出力
7. エラー処理
   └─ 失敗時はStop-Functionで処理を継続
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C{Database/ExcludeDatabase/All指定?}
    B -->|No| G[InputObjectを使用]
    C -->|No| D[エラー: パラメータ必須]
    C -->|Yes| E[Get-DbaDatabase実行]
    D --> Z[終了]
    E --> F[データベースのMasterKeyを取得]
    F --> H[InputObjectに追加]
    G --> I[マスターキーループ開始]
    H --> I
    I --> J{キーが残っている?}
    J -->|No| Z
    J -->|Yes| K{ShouldProcess?}
    K -->|No| L[次のキーへ]
    K -->|Yes| M[DROP MASTER KEY実行]
    M --> N{成功?}
    N -->|Yes| O[結果オブジェクト出力]
    N -->|No| P[Stop-Function呼び出し]
    O --> L
    P --> L
    L --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ必須 | SqlInstance使用時はDatabase、ExcludeDatabase、Allのいずれかが必須 | SqlInstance指定時 |
| BR-002 | All動作 | Allが指定された場合、$databasesが空でも全データベースが対象となる | All指定時 |
| BR-003 | 確認プロンプト | ConfirmImpactがHighのため、デフォルトで確認プロンプトが表示される | Confirm:$false未指定時 |
| BR-004 | 依存オブジェクト確認 | マスターキーが他のオブジェクトで使用されている場合、削除に失敗する可能性がある | 依存関係存在時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| マスターキー削除 | sys.symmetric_keys | DELETE | データベースマスターキーを削除 |

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

#### sys.symmetric_keys

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | DROP MASTER KEY | Database.Queryメソッドで直接実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstance指定時にDatabase/ExcludeDatabase/Allが未指定 | Stop-Functionでエラーメッセージ出力 |
| - | 依存関係エラー | マスターキーが他のオブジェクトで使用中 | 依存オブジェクトを先に削除 |
| - | 権限不足エラー | CONTROL権限がない | 適切な権限を付与 |

### リトライ仕様

リトライ機能なし - エラー発生時は次のキーの処理を継続

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

個々のDROP MASTER KEYコマンドは自動コミットで実行される。

## パフォーマンス要件

特に定義されていない。マスターキー削除は通常高速に完了する。

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

- データベースマスターキーの削除には適切なデータベース権限が必要
- マスターキー削除前にBackup-DbaDbMasterKeyでバックアップを取得することを強く推奨
- Windows認証、SQL Server認証、Active Directory認証をサポート
- MFAサポートにはConnect-DbaInstanceを使用

## 備考

- Get-DbaDbMasterKeyからのパイプライン入力をサポート
- Database.Queryメソッドを使用してT-SQLを直接実行（コレクション変更問題を回避）
- 複数インスタンス、複数データベースの一括処理が可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MasterKey (SMO) | Microsoft.SqlServer.Management.Smo | SQL Serverマスターキーのオブジェクト構造を理解する |

**読解のコツ**: SMOのMasterKeyオブジェクトは、Parentプロパティでデータベースオブジェクトを参照し、そのParent.Parentでサーバーオブジェクトにアクセスできる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaDbMasterKey.ps1 | `public/Remove-DbaDbMasterKey.ps1` | メイン関数の入口とパラメータ定義を確認 |

**主要処理フロー**:
1. **85-95行目**: パラメータブロック定義 - CmdletBinding属性でShouldProcess、ConfirmImpact=Highを設定
2. **98-102行目**: SqlInstance指定時のパラメータ必須チェック
3. **104行目**: Get-DbaDatabase経由でデータベースを取得
4. **105-109行目**: 各データベースのMasterKeyをInputObjectに追加
5. **112-114行目**: マスターキーオブジェクトからサーバーとデータベース情報を取得
6. **115行目**: ShouldProcess確認
7. **118行目**: Database.QueryメソッドでDROP MASTER KEYを実行
8. **119-125行目**: 成功時に結果オブジェクトを出力
9. **126-128行目**: エラー時にStop-Functionで処理を継続

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbMasterKey.ps1 | `public/Get-DbaDbMasterKey.ps1` | マスターキーオブジェクトの取得方法を理解 |
| 3-2 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | データベースオブジェクトの取得方法を理解 |

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

```
Remove-DbaDbMasterKey
    │
    ├─ パラメータ検証
    │      └─ Database/ExcludeDatabase/All必須チェック
    │
    ├─ Get-DbaDatabase
    │      └─ Connect-DbaInstance
    │             └─ SMO Server接続
    │
    ├─ MasterKey取得
    │      └─ Database.MasterKeyプロパティ
    │
    ├─ ShouldProcess (確認処理)
    │
    └─ Database.Query
           └─ DROP MASTER KEY実行
```

### データフロー図

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

SqlInstance     ───┬──▶ 必須チェック ───▶ Get-DbaDatabase ───┐
SqlCredential   ───┤                                          │
Database        ───┤                                          │
ExcludeDatabase ───┤                                          │
All             ───┘                                          │
                                                              ▼
                                                      MasterKey取得
                                                              │
                                                              ▼
InputObject     ────────────────────────────────────────▶ foreach loop
                                                              │
                                                              ▼
                                                       Database.Query
                                                    (DROP MASTER KEY)
                                                              │
                                                              ▼
                                                       [PSCustomObject] ───▶ パイプライン出力
                                                       ComputerName
                                                       InstanceName
                                                       SqlInstance
                                                       Database
                                                       Status
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaDbMasterKey.ps1 | `public/Remove-DbaDbMasterKey.ps1` | ソース | メイン関数 |
| Get-DbaDbMasterKey.ps1 | `public/Get-DbaDbMasterKey.ps1` | ソース | マスターキー取得関数 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得関数 |
| Backup-DbaDbMasterKey.ps1 | `public/Backup-DbaDbMasterKey.ps1` | ソース | マスターキーバックアップ関数 |
| Remove-DbaDbMasterKey.Tests.ps1 | `tests/Remove-DbaDbMasterKey.Tests.ps1` | テスト | 単体テスト |
