# 機能設計書 49-Test-DbaBackupEncrypted

## 概要

本ドキュメントは、バックアップファイルの暗号化状態を分析し、暗号化詳細を取得するdbatools PowerShellコマンド `Test-DbaBackupEncrypted` の機能設計書である。

### 本機能の処理概要

この機能は、SQL Serverバックアップファイルを検査して、バックアップ暗号化またはTDE（Transparent Data Encryption）によって暗号化されているかどうかを識別する。RESTORE HEADERONLYおよびRESTORE FILELISTONLYコマンドを使用して、実際にデータベースをリストアすることなくバックアップヘッダーとファイルメタデータを検査する。

**業務上の目的・背景**：DBAは暗号化コンプライアンスを確認し、リストアの問題をトラブルシューティングし、環境全体の暗号化されたバックアップのインベントリを維持する必要がある。暗号化証明書がないとリストアが失敗するため、事前にバックアップの暗号化状態を把握することが重要である。

**機能の利用シーン**：
- バックアップ暗号化コンプライアンスの監査
- 暗号化証明書不足によるリストア失敗のトラブルシューティング
- 暗号化されたバックアップのインベントリ作成
- TDE対応データベースのバックアップ確認

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. RESTORE HEADERONLYでバックアップ暗号化情報取得
3. RESTORE FILELISTONLYでTDEサムプリント取得
4. 暗号化状態の判定と結果オブジェクト生成

**関連システム・外部連携**：バックアップファイル（ローカル、ネットワーク共有）

**権限による制御**：RESTORE HEADERONLYおよびRESTORE FILELISTONLY実行権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIベースの監査/診断コマンド |

## 機能種別

検証 / 診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | バックアップ読み取りに使用するSQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| FilePath | string[] | Yes | バックアップファイルパス | パイプライン入力可能 |
| EnableException | switch | No | 例外を有効にするスイッチ | - |

### 入力データソース

バックアップファイル（.bak, .trn, .dif等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| FilePath | string | バックアップファイルパス |
| BackupName | string | バックアップセットの論理名 |
| Encrypted | bool | 暗号化されているかどうか |
| KeyAlgorithm | string | 暗号化キーアルゴリズム（AES128/AES192/AES256等） |
| EncryptorThumbprint | string | バックアップ暗号化証明書のSHA-1サムプリント |
| EncryptorType | string | 暗号化タイプ（Certificate/Asymmetric Key） |
| TDEThumbprint | string | TDEサムプリント（16進数形式） |
| Compressed | bool | 圧縮が有効かどうか |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQL Server接続
   └─ Connect-DbaInstanceで接続確立
2. 各ファイルに対して処理
   ├─ RESTORE HEADERONLY実行
   │   └─ KeyAlgorithm, EncryptorThumbprint, EncryptorType取得
   ├─ RESTORE FILELISTONLY実行
   │   └─ TDEThumbprint取得
   └─ 暗号化判定
3. 結果オブジェクト生成
   └─ PSCustomObject出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E{各ファイルループ}
    E --> F[パスエスケープ処理]
    F --> G[RESTORE HEADERONLY実行]
    G --> H{成功?}
    H -->|No| I[Stop-Function Continue]
    H -->|Yes| J{KeyAlgorithm等確認}
    J -->|null以外あり| K[Encrypted=true]
    J -->|全てnull| L[RESTORE FILELISTONLY実行]
    K --> L
    L --> M{TDEThumbprintあり?}
    M -->|Yes| N[Encrypted=true, TDEThumbprint設定]
    M -->|No| O[結果オブジェクト生成]
    N --> O
    O --> E
    E --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | バックアップ暗号化検出 | KeyAlgorithm/EncryptorThumbprint/EncryptorTypeのいずれかがnull以外の場合、暗号化と判定 | RESTORE HEADERONLY結果 |
| BR-49-02 | TDE検出 | TDEThumbprintの長さが1より大きい場合、暗号化と判定 | RESTORE FILELISTONLY結果 |
| BR-49-03 | パスエスケープ | シングルクォートを二重にエスケープ | パスにシングルクォートを含む場合 |

### 計算ロジック

**暗号化判定（99-105行目）**:
```powershell
if ($results.KeyAlgorithm -isnot [dbnull] -or
    $results.EncryptorThumbprint -isnot [dbnull] -or
    $results.EncryptorType -isnot [dbnull]) {
    $encrypted = $true
}
```

**TDEサムプリント変換（115行目）**:
```powershell
$thumbprint = Convert-ByteToHexString $thumb
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ヘッダー読取 | - | RESTORE HEADERONLY | バックアップヘッダー情報取得 |
| ファイルリスト取得 | - | RESTORE FILELISTONLY | バックアップ内ファイル情報取得 |

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

本機能はバックアップファイルを直接読み取るため、データベーステーブルへの操作は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで終了 |
| - | HEADERONLY失敗 | バックアップファイル読み取りエラー | Stop-Function Continueで継続 |
| - | thumbprint例外 | FILELISTONLY実行時のエラー | 例外内容でthumbprint有無を判定 |

### リトライ仕様

本機能にはリトライ機構は実装されていない。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

各バックアップファイルに対して2つのRESTOREコマンドを実行するため、大量ファイル処理時はパフォーマンスに注意。

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

- RESTORE HEADERONLYおよびRESTORE FILELISTONLY実行権限が必要
- バックアップファイルへのSQL Serverサービスアカウントのアクセス権が必要
- 暗号化サムプリント情報は機密性が低い（公開鍵情報）

## 備考

- バックアップ暗号化とTDEは異なる暗号化方式
- バックアップ暗号化: バックアップ作成時に暗号化
- TDE: データベース自体が暗号化されており、バックアップにもその情報が含まれる

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

入力パラメータの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 68-77行目のparam定義 |

**読解のコツ**: FilePathはFullName/Pathのエイリアスを持ち、パイプライン入力可能。

#### Step 2: 接続とファイルループを理解する

processブロックの基本構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 78-87行目 |

**主要処理フロー**:
- **79-84行目**: Connect-DbaInstance接続
- **87行目**: 各ファイルのループ開始

#### Step 3: RESTORE HEADERONLY処理を理解する

バックアップ暗号化情報の取得を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 88-105行目 |

**主要処理フロー**:
- **91行目**: パスのシングルクォートエスケープ
- **92-94行目**: RESTORE HEADERONLY実行
- **99-105行目**: KeyAlgorithm等の非nullチェック

#### Step 4: RESTORE FILELISTONLY処理を理解する

TDE情報の取得を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 107-124行目 |

**主要処理フロー**:
- **108行目**: RESTORE FILELISTONLY実行
- **110行目**: TDEThumbprintの取得
- **112-116行目**: サムプリント長チェックと16進数変換
- **117-123行目**: 例外時のthumbprint検出

#### Step 5: 結果オブジェクト生成を理解する

出力オブジェクトの構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | 126-140行目 |

**主要処理フロー**:
- **127-139行目**: PSCustomObject構築
- **132-138行目**: 各プロパティの設定

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

```
Test-DbaBackupEncrypted
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ server.Query("RESTORE HEADERONLY")
    │      └─ バックアップ暗号化情報取得
    │
    ├─ server.Query("RESTORE FILELISTONLY")
    │      └─ TDE情報取得
    │
    └─ Convert-ByteToHexString
           └─ TDEサムプリント16進数変換
```

### データフロー図

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

FilePath ───────────────────► パスエスケープ ───────────────────►
SqlInstance ────────────────► Connect-DbaInstance ──────────────►
                                      │
                                      ▼
バックアップファイル ────────► RESTORE HEADERONLY
                                      │
                                      ├──► KeyAlgorithm
                                      ├──► EncryptorThumbprint
                                      └──► EncryptorType
                                             │
                                             ▼
                              RESTORE FILELISTONLY
                                      │
                                      └──► TDEThumbprint
                                             │
                              Convert-ByteToHexString
                                             │
                                             ▼
                              暗号化判定
                                             │
                                             ▼
                              PSCustomObject ────► 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaBackupEncrypted.ps1 | `public/Test-DbaBackupEncrypted.ps1` | ソース | メイン機能実装 |
| Test-DbaBackupEncrypted.Tests.ps1 | `tests/Test-DbaBackupEncrypted.Tests.ps1` | テスト | Pesterテストコード |
| Convert-ByteToHexString.ps1 | `private/functions/Convert-ByteToHexString.ps1` | ソース | サムプリント変換（依存関数） |
