# 画面設計書 257-オブジェクト復号

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Invoke-DbaDbDecryptObject` コマンドに関する画面設計書です。このコマンドは、専用管理者接続（DAC）を使用して暗号化されたストアドプロシージャ、関数、ビュー、トリガーを復号します。

### 本画面の処理概要

**業務上の目的・背景**：災害復旧シナリオや元のソースコードが失われた状況において、暗号化されたデータベースオブジェクトから元のソースコードを復元する必要が生じることがあります。このコマンドは、DAC接続を使用して `sys.sysobjvalues` からバイナリデータにアクセスし、XOR復号を実行して元のT-SQLコードを復元します。ストアドプロシージャ、ユーザー定義関数（スカラー、インライン、テーブル値）、ビュー、トリガーを復号できます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Invoke-DbaDbDecryptObject` コマンドを実行します。事前にリモートDAC接続を有効にする必要があります。

**主要な操作・処理内容**：
1. リモートDAC接続の有効化状態を確認
2. DAC接続（ADMIN:プレフィックス）でSQL Serverに接続
3. 対象データベースの暗号化オブジェクトを列挙
4. 各オブジェクトに対して：
   - sys.sysobjvaluesから暗号化バイナリを取得
   - 既知のプレーンテキストで同等のオブジェクトを作成
   - 暗号化されたバイナリを取得
   - XOR演算で復号
5. 結果をコンソールまたはファイルに出力

**画面遷移**：CLIコマンドのため画面遷移はありません。

**権限による表示制御**：sysadmin権限またはDAC接続権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 168 | Invoke-DbaDbDecryptObject | 主機能 | 暗号化オブジェクトの復号 |
| 100 | Get-DbaSpConfigure | 補助機能 | リモートDAC設定の確認 |
| 101 | Set-DbaSpConfigure | 補助機能 | リモートDAC設定の有効化 |

## 画面種別

ユーティリティ・復元（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象SQL Serverインスタンス（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | Yes | 対象データベース名 |
| ObjectName | string[] | No | 対象オブジェクト名（省略時は全暗号化オブジェクト） |
| EncodingType | string | No | テキストエンコーディング（ASCII または UTF8、デフォルト: ASCII） |
| ExportDestination | string | No | 復号スクリプトの出力先フォルダ |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | SQL Serverインスタンスのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Type | string | オブジェクトタイプ（StoredProcedure, UserDefinedFunction, View, Trigger） |
| Schema | string | スキーマ名 |
| Name | string | オブジェクト名 |
| FullName | string | スキーマ修飾名（schema.name） |
| Script | string | 復号されたT-SQLソースコード |
| OutputFile | string | 出力ファイルパス（ExportDestination指定時） |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. リモートDAC接続設定を確認
2. DAC接続を確立（Connect-DbaInstance -DedicatedAdminConnection）
3. 対象データベースの暗号化オブジェクトを列挙
4. 各オブジェクトに対して：
   - sys.sysobjvaluesから暗号化データ取得（$secret）
   - 既知のプレーンテキストALTER文を構築（$queryKnownPlain）
   - トランザクション内でALTER実行し暗号化バイナリ取得後ロールバック（$knownSecret）
   - XOR演算で復号（Invoke-DecryptData）
5. ExportDestination指定時はフォルダ構造を作成してファイル出力
6. DAC接続を切断

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 暗号化データ取得 | sys.sysobjvalues | SELECT | 暗号化バイナリの読み取り |
| 既知暗号化取得 | sys.sysobjvalues | BEGIN/ROLLBACK | ALTER実行後ロールバック |

### テーブル別更新項目詳細

このコマンドは実質的に読み取り専用です。ALTER文はトランザクション内でロールバックされるため、永続的な変更は行われません。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | DAC未有効 | "DAC is not enabled for instance $instance. Please use 'Set-DbaSpConfigure...'" |
| エラー | 接続失敗 | "Error occurred while establishing connection to $instance" |
| エラー | 暗号化データ取得失敗 | "Couldn't retrieve secret from $instance" |
| エラー | プレーンテキスト変換失敗 | "Couldn't convert the known plain to binary" |
| エラー | 既知暗号化取得失敗 | "Couldn't retrieve known secret from $instance" |
| エラー | フォルダ作成失敗 | "Couldn't create destination folder $destinationFolder" |
| エラー | ファイル出力失敗 | "Couldn't export the results of $($object.Name) to $filePath" |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| DAC未有効 | Stop-Functionでメッセージ表示して次のインスタンスへ続行 |
| 接続エラー | Stop-Functionでメッセージ表示して次のインスタンスへ続行 |
| 暗号化データ取得失敗 | Stop-Functionで該当オブジェクトをスキップ |
| ファイル出力失敗 | Stop-Functionで該当オブジェクトをスキップ |

## 備考

- リモートDAC接続を事前に有効化する必要があります
  - 確認: `Get-DbaSpConfigure -SqlInstance [instance] -ConfigName RemoteDacConnectionsEnabled`
  - 有効化: `Set-DbaSpConfigure -SqlInstance [instance] -ConfigName RemoteDacConnectionsEnabled -Value 1`
- ローカルDAC接続はデフォルトで有効
- 暗号化アルゴリズムはXOR暗号を使用
- ASCIIエンコーディングで問題がある場合はUTF8を試行
- ExportDestination使用時のフォルダ構造: `<ExportDestination>\<instance>\<database>\<objectType>\`

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | 出力PSCustomObject構造（行366-377） |
| 1-2 | Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | Invoke-DecryptData内部関数（行125-161） |

**読解のコツ**: XOR復号のロジックを理解することで、このコマンドの動作原理を把握できます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | 関数定義全体（行1-389） |

**主要処理フロー**:
1. **行123-182**: beginブロックで内部関数定義とエンコーディング設定
2. **行193-196**: DAC設定確認
3. **行198-213**: DAC接続確立
4. **行222-252**: 暗号化オブジェクト列挙
5. **行257-325**: 各オブジェクトの復号処理
6. **行331-363**: ファイル出力処理
7. **行366-377**: 結果オブジェクト出力

#### Step 3: 復号アルゴリズムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | XOR復号ロジック（行139-152） |
| 3-2 | Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | 既知プレーンテキスト構築（行270-295） |

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

```
Invoke-DbaDbDecryptObject
    │
    ├─ Get-DbaSpConfigure (DAC設定確認)
    │
    ├─ Connect-DbaInstance -DedicatedAdminConnection
    │
    ├─ 暗号化オブジェクト列挙
    │      ├─ $db.StoredProcedures
    │      ├─ $db.UserDefinedFunctions
    │      ├─ $db.Views
    │      └─ $db.Tables.Triggers
    │
    ├─ 各オブジェクトの復号
    │      ├─ sys.sysobjvalues SELECT (暗号化データ)
    │      ├─ ALTER文構築
    │      ├─ BEGIN TRAN / ALTER / SELECT / ROLLBACK
    │      └─ Invoke-DecryptData (XOR復号)
    │
    └─ Disconnect-DbaInstance
```

### データフロー図

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

SqlInstance ───▶ DAC設定確認
                           │
                           ▼
                    DAC接続確立
                           │
Database ──────▶ 暗号化オブジェクト列挙
                           │
ObjectName ────▶ フィルタリング
                           │
                    ┌──────┴──────┐
                    ▼             ▼
              sys.sysobjvalues  既知プレーンテキスト
              (暗号化データ)    (ALTER文)
                    │             │
                    ▼             ▼
              $secret        $knownPlain
                    │             │
                    ▼             ▼
              sys.sysobjvalues (トランザクション内)
              (既知暗号化データ)
                    │
                    ▼
              $knownSecret
                    │
                    ▼
              XOR復号 ($secret XOR $knownPlain XOR $knownSecret)
                    │
                    ▼
              復号済みScript
                    │
              ┌─────┴─────┐
              ▼           ▼
         PSCustomObject  ファイル出力
              │           │
              ▼           ▼
         パイプライン   .sqlファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbDecryptObject.ps1 | `public/Invoke-DbaDbDecryptObject.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | DAC接続処理 |
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | DAC設定確認 |
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | ソース | 接続切断 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
