# 機能設計書 593-Enable-DbaDbEncryption

## 概要

本ドキュメントは、SQL ServerデータベースでTransparent Data Encryption (TDE) を有効化するPowerShellコマンドレット `Enable-DbaDbEncryption` の機能設計書である。

### 本機能の処理概要

本機能は、SQL ServerデータベースでTransparent Data Encryption (TDE) を有効化し、保存データを暗号化するコマンドレットである。

**業務上の目的・背景**：HIPAA、PCI-DSS、GDPR等のコンプライアンス要件や組織のセキュリティポリシーにより、データベースの保存データ（Data at Rest）の暗号化が求められる場面が増加している。TDEはSQL Serverのエンタープライズ機能として、アプリケーション変更なしでデータファイル、ログファイル、バックアップファイルを暗号化できる。本コマンドはTDE有効化に必要な複数の手順（Database Encryption Key作成、証明書指定、暗号化有効化）を自動化する。

**機能の利用シーン**：
- 新規データベースへのセキュリティ標準適用
- 既存データベースのコンプライアンス対応
- 本番環境移行前のセキュリティ設定
- 証明書ローテーション後のTDE再設定

**主要な処理内容**：
1. SqlInstanceパラメータ使用時はGet-DbaDatabase経由で対象データベースを取得
2. DatabaseEncryptionKey (DEK) が存在しない場合、New-DbaDbEncryptionKeyで自動作成
3. EncryptorNameで指定された証明書を使用（未指定時は既存証明書を検索）
4. EncryptionEnabledプロパティをtrueに設定
5. Alter()メソッドで変更を適用
6. 処理結果をパイプラインに出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスに接続。masterデータベースの証明書を使用してDEKを暗号化する。

**権限による制御**：対象データベースに対するCONTROL DATABASE権限が必要。masterデータベースの証明書へのアクセス権限も必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio | 参照画面 | データベースプロパティのオプションページでTDE状態を確認 |
| - | PowerShellコンソール | 主画面 | コマンドの実行および結果表示 |

## 機能種別

データ更新処理 / セキュリティ設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 接続用の代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | string[] | No* | TDEを有効化するデータベース名 | SqlInstance使用時は必須 |
| EncryptorName | string | No | DEK暗号化に使用するmasterデータベースの証明書名 | エイリアス: Certificate, CertificateName |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | Get-DbaDatabase等からのパイプライン入力 | SMO Databaseオブジェクト |
| Force | switch | No | 証明書バックアップ確認をスキップ | - |
| EnableException | switch | No | 例外を直接スローするフラグ | - |
| WhatIf | switch | No | 実際の変更を行わずに動作を表示 | - |
| Confirm | switch | No | 変更前に確認プロンプトを表示 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| DatabaseName | string | TDEを有効化したデータベース名（Nameプロパティのエイリアス） |
| EncryptionEnabled | bool | TDE有効化状態（処理後はtrue） |

### 出力先

- PowerShellパイプライン：Microsoft.SqlServer.Management.Smo.Database オブジェクト（Select-DefaultViewで表示プロパティを制限）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時にDatabaseパラメータの必須チェック
2. 対象データベース取得
   └─ SqlInstance使用時: Get-DbaDatabase経由で取得
   └─ InputObject使用時: パイプライン入力をそのまま使用
3. 各データベースに対するループ処理
   └─ DatabaseEncryptionKey のリフレッシュ
   └─ ShouldProcess確認（-WhatIf/-Confirm対応）
   └─ DEK存在チェック
       └─ 存在しない場合: New-DbaDbEncryptionKey を呼び出し
   └─ EncryptionEnabled = $true 設定
   └─ Alter()メソッド実行
   └─ DEKのリフレッシュ
   └─ 結果オブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C{Database指定?}
    C -->|No| D[エラー: Database必須]
    C -->|Yes| E[Get-DbaDatabase実行]
    B -->|No| F[InputObjectを使用]
    E --> G[対象DB取得完了]
    F --> G
    G --> H{次のDBあり?}
    H -->|No| Z[終了]
    H -->|Yes| I[DatabaseEncryptionKey.Refresh]
    I --> J{ShouldProcess?}
    J -->|No| H
    J -->|Yes| K{DEK存在?}
    K -->|No| L[New-DbaDbEncryptionKey実行]
    K -->|Yes| M[EncryptionEnabled = true]
    L --> M
    M --> N[Alter実行]
    N --> O[DatabaseEncryptionKey.Refresh]
    O --> P[結果出力]
    P --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Database必須チェック | SqlInstance使用時はDatabaseパラメータが必須 | SqlInstanceパラメータ指定時 |
| BR-002 | DEK自動作成 | DatabaseEncryptionKeyが存在しない場合は自動作成 | DEK未存在時 |
| BR-003 | 証明書バックアップ確認 | デフォルトで証明書がバックアップ済みか確認 | Force未指定時 |
| BR-004 | 高影響確認 | ConfirmImpact="High"によりデフォルトで確認プロンプト表示 | インタラクティブ実行時 |
| BR-005 | 暗号化アルゴリズム | DEK作成時はAES 256ビット暗号化を使用（New-DbaDbEncryptionKeyのデフォルト） | DEK新規作成時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DEK作成 | sys.database_encryption_keys | INSERT（間接） | New-DbaDbEncryptionKey経由で作成 |
| TDE有効化 | sys.dm_database_encryption_keys | UPDATE（間接） | SMO経由でEncryptionEnabledを変更 |

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

#### sys.dm_database_encryption_keys

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT/UPDATE | encryption_state | 暗号化状態の取得・更新 | SMOのEncryptionStateプロパティ経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance使用時にDatabase未指定 | Databaseパラメータを指定 |
| - | Stop-Function | 証明書が見つからない | EncryptorNameを正しく指定、または証明書を作成 |
| - | Stop-Function | 証明書がバックアップされていない | Forceスイッチを使用、または証明書をバックアップ |
| - | Stop-Function | 処理中の予期しない例外 | エラーメッセージを確認し原因を特定 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を中断し、次のデータベースに進む（-Continueフラグ使用時）。

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

SMOのAlter()メソッドにより暗黙的にトランザクション管理される。暗号化処理自体は非同期で行われ、SQL Serverエンジンが内部的にトランザクション管理を行う。

## パフォーマンス要件

- 暗号化処理時間はデータベースサイズに依存
- 暗号化中はCPUとI/Oリソースを消費
- 大規模データベースでは数時間から数日かかる場合がある
- 暗号化中もデータベースへのアクセスは可能（パフォーマンス低下あり）

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

- CONTROL DATABASE 権限が必要
- masterデータベースの証明書へのアクセス権限が必要
- 証明書とその秘密鍵のバックアップが必須（Forceスイッチ使用時は確認をスキップ）
- 証明書を紛失するとデータベースの復元が不可能になる
- tempdbも自動的に暗号化される（TDE有効化後）
- バックアップファイルも自動的に暗号化される

## 備考

- TDEはSQL Server Enterprise Edition（または Developer Edition）でのみ利用可能
- 暗号化完了までバックグラウンドで処理が継続（コマンドは即座に返る）
- tempdbが暗号化されるため、同一インスタンス上の他のDBにも影響がある可能性
- 証明書のローテーションには別途計画が必要

---

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

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

### 推奨読解順序

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

TDE関連のSMOオブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Database | Microsoft.SqlServer.Management.Smo | EncryptionEnabled, DatabaseEncryptionKeyプロパティの関係 |

**読解のコツ**: DatabaseEncryptionKeyプロパティはDEKオブジェクトへの参照を提供し、EncryptionAlgorithmプロパティでDEKの存在を確認できる。

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

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

**主要処理フロー**:
1. **99-110行目**: パラメータ定義（CmdletBinding, パラメータ属性）
2. **111-119行目**: SqlInstance使用時のDatabase必須チェックとGet-DbaDatabase呼び出し
3. **121-142行目**: 各データベースに対するループ処理

#### Step 3: DEK作成とTDE有効化ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaDbEncryption.ps1 | `public/Enable-DbaDbEncryption.ps1` | DEK作成判定とTDE有効化 |

**主要処理フロー**:
- **122-124行目**: DatabaseEncryptionKeyのリフレッシュ
- **126行目**: ShouldProcess確認
- **128-131行目**: DEK存在チェックと自動作成（EncryptionAlgorithmプロパティで判定）
- **132-133行目**: EncryptionEnabled = $true 設定とAlter()実行
- **134-136行目**: DEKリフレッシュ
- **137行目**: Select-DefaultViewで結果出力

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

```
Enable-DbaDbEncryption
    │
    ├─ Get-DbaDatabase (SqlInstance使用時)
    │      └─ Connect-DbaInstance
    │
    ├─ New-DbaDbEncryptionKey (DEK未存在時)
    │      └─ DEK作成（AES 256ビット）
    │      └─ 証明書バックアップ確認（Force未指定時）
    │
    └─ SMO Database.Alter()
           └─ TDE有効化設定をサーバーに適用
```

### データフロー図

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

SqlInstance/Database ───▶ Get-DbaDatabase ───▶ SMO Database[]
        or
InputObject ───────────────────────────────────▶ SMO Database[]
                                                       │
                                                       ▼
                                              DEK存在チェック
                                                       │
                                         ┌─────────────┴─────────────┐
                                         │                           │
                                    DEKなし                      DEKあり
                                         │                           │
                                         ▼                           │
                              New-DbaDbEncryptionKey                 │
                                         │                           │
                                         └─────────────┬─────────────┘
                                                       │
                                                       ▼
                                              EncryptionEnabled = true
                                                       │
                                                       ▼
                                                  Alter()実行
                                                       │
                                                       ▼
                                              Select-DefaultView
                                                       │
                                                       ▼
                                              パイプライン出力 ───▶ コンソール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Enable-DbaDbEncryption.ps1 | `public/Enable-DbaDbEncryption.ps1` | ソース | メイン機能実装 |
| New-DbaDbEncryptionKey.ps1 | `public/New-DbaDbEncryptionKey.ps1` | ソース | DEK作成機能 |
| Disable-DbaDbEncryption.ps1 | `public/Disable-DbaDbEncryption.ps1` | ソース | 対となる無効化機能 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得機能 |
| Enable-DbaDbEncryption.Tests.ps1 | `tests/Enable-DbaDbEncryption.Tests.ps1` | テスト | 単体・統合テスト |
