# 機能設計書 539-Copy-DbaCredential

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるCopy-DbaCredential機能の設計仕様を定義するものである。この機能はSQL Server資格情報をインスタンス間で移行し、暗号化されたパスワードを保持する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server資格情報（Credential）は、外部リソースへの認証に使用される重要なセキュリティオブジェクトである。サーバー移行、災害復旧セットアップ、環境同期において、資格情報を移行する必要があるが、通常の方法ではパスワードを取得できない。本機能は、Dedicated Admin Connection (DAC)とパスワード復号化技術を使用して、元のパスワードを保持したまま資格情報を移行する。

**機能の利用シーン**：
- SQL Serverインスタンス間の移行
- 災害復旧環境のセットアップ
- 開発・テスト環境の同期
- サービスアカウント資格情報の複製
- Proxy資格情報の移行

**主要な処理内容**：
1. ソースサーバーへのDAC接続確立（パスワード復号化のため）
2. Get-DecryptedObject経由での資格情報パスワード復号化
3. Get-DbaCredential経由での資格情報一覧取得
4. 宛先サーバーへの接続確立
5. 既存資格情報の存在確認（Force時は削除）
6. New-DbaCredential経由での資格情報作成

**関連システム・外部連携**：
- Dedicated Admin Connection (DAC) - パスワード復号化に必要
- Get-DecryptedObject - 内部パスワード復号化関数
- Get-DbaCredential - 資格情報取得
- New-DbaCredential - 資格情報作成

**権限による制御**：
- 両サーバーでのsysadmin権限
- Windows管理者権限（パスワード復号化のため）
- DAC有効化（ソースサーバー）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 74 | 資格情報管理 | 補助機能 | 資格情報のコピー |

## 機能種別

データ移行処理（COPY / MIGRATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | 有効なSQL Server接続文字列 |
| SourceSqlCredential | PSCredential | No | ソース接続用の代替認証情報 | 有効なPSCredentialオブジェクト |
| Credential | PSCredential | No | Windows OS接続用の認証情報（パスワード復号化用） | 有効なPSCredentialオブジェクト |
| Destination | DbaInstanceParameter[] | Yes | 宛先SQL Serverインスタンス | 有効なSQL Server接続文字列 |
| DestinationSqlCredential | PSCredential | No | 宛先接続用の代替認証情報 | 有効なPSCredentialオブジェクト |
| Name | string[] | No | コピー対象の資格情報名 | - |
| ExcludeName | string[] | No | 除外する資格情報名 | - |
| Identity | string[] | No | コピー対象のID（ユーザー名） | - |
| ExcludeIdentity | string[] | No | 除外するID | - |
| ExcludePassword | switch | No | パスワードなしでコピー | - |
| Force | switch | No | 既存資格情報を削除して再作成 | - |
| EnableException | switch | No | 例外を呼び出し元にスローする | - |

### 入力データソース

- パラメータ入力（コマンドライン引数）
- ソースSQL Serverの資格情報（sys.credentials + 暗号化データ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | 資格情報名 |
| Type | string | オブジェクト種別（常に"Credential"） |
| Status | string | 操作結果（Successful/Skipping/Failed） |
| Notes | string | 操作詳細・エラー理由 |

### 出力先

- 標準出力（PSCustomObject / MigrationObject type）
- パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. プラットフォームチェック（beginブロック）
   └─ Windows以外では実行不可

2. ソースサーバー接続
   ├─ ExcludePassword時は通常接続
   └─ パスワード復号化時はDAC接続

3. パスワード復号化
   └─ Get-DecryptedObject呼び出し

4. 資格情報一覧取得
   └─ Get-DbaCredential呼び出し

5. 宛先サーバーループ（processブロック）
   ├─ 宛先サーバー接続
   └─ 資格情報ループ
       ├─ 既存確認（Force時は削除）
       ├─ CryptographicProvider確認（該当時）
       ├─ New-DbaCredentialで作成
       └─ 結果出力

6. クリーンアップ（endブロック）
   └─ DAC接続切断
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Windows?}
    B -->|No| C[エラー: Windows専用]
    B -->|Yes| D{ExcludePassword?}
    D -->|Yes| E[通常接続]
    D -->|No| F[DAC接続]
    E --> G[資格情報取得]
    F --> H[パスワード復号化]
    H --> G
    G --> I[foreach destination]
    I --> J[宛先接続]
    J --> K[foreach credential]
    K --> L{既存?}
    L -->|Yes| M{Force?}
    M -->|No| N[Skipping出力]
    M -->|Yes| O[Drop実行]
    O --> P[New-DbaCredential]
    L -->|No| P
    P --> Q{成功?}
    Q -->|No| R[Failed出力]
    Q -->|Yes| S[Successful出力]
    N --> T{次のCredential?}
    R --> T
    S --> T
    T -->|Yes| K
    T -->|No| U{次のDestination?}
    U -->|Yes| I
    U -->|No| V[DAC切断]
    V --> W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Windows専用 | Windows環境でのみ実行可能 | 常時 |
| BR-002 | DAC必須 | パスワード復号化にはDAC接続が必要 | ExcludePassword未指定時 |
| BR-003 | 最小バージョン | SQL Server 2005以上必須 | 常時 |
| BR-004 | 既存スキップ | 既存資格情報はデフォルトでスキップ | Force未指定時 |
| BR-005 | CryptoProvider | CryptographicProvider資格情報は宛先で設定済みであること | 該当資格情報移行時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 資格情報取得 | sys.credentials | SELECT | ソースから資格情報一覧取得 |
| パスワード復号化 | master.sys.sysobjvalues | SELECT（DAC） | 暗号化パスワード取得 |
| 資格情報削除 | sys.credentials | DELETE | Force時の既存資格情報削除 |
| 資格情報作成 | sys.credentials | INSERT | 宛先での資格情報作成 |

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

#### sys.credentials（宛先）

New-DbaCredential経由で以下相当のDDLが実行される：
```sql
CREATE CREDENTIAL [資格情報名]
WITH IDENTITY = '[ID]',
SECRET = '[パスワード]'
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非サポート環境 | Windows以外 | Windows環境で実行する |
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報・ネットワークを確認 |
| - | 復号化失敗 | パスワード復号化失敗 | DAC有効化・権限を確認 |
| - | CryptoProvider未設定 | 宛先でCryptoProviderが無効 | 宛先でCryptoProviderを設定 |
| - | 削除失敗 | Force時の削除失敗 | 資格情報の依存関係を確認 |

### リトライ仕様

Stop-Function -Continueにより、エラー発生時も次の資格情報/宛先処理を継続する。

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

各資格情報の作成は個別のトランザクションとして処理される。

## パフォーマンス要件

- DAC接続の確立に数秒かかる場合がある
- パスワード復号化は暗号化処理を含むため若干の遅延
- 多数の資格情報を一括コピーする場合は順次処理

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

- sysadmin権限とWindows管理者権限が必要
- DAC接続はセキュリティ上の重要機能であり、慎重に使用
- パスワードは復号化されてメモリに一時保持される
- ConfirmImpact=Mediumにより確認プロンプト表示
- NetSPIのパスワード復号化技術を使用

## 備考

- 技術参考: Antti Rantasaari (NetSPI, 2014) によるパスワード復号化手法
- ExcludePasswordを使用すると、パスワードなしで資格情報定義のみコピー可能
- CryptographicProvider資格情報は宛先での事前設定が必要

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaCredential.ps1 | `public/Copy-DbaCredential.ps1` | 出力オブジェクト構造（208-216行目）copyCredentialStatus定義 |

**読解のコツ**: PSCustomObjectで定義されるMigrationObjectの構造を確認し、各ステータスの意味を把握する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaCredential.ps1 | `public/Copy-DbaCredential.ps1` | param()ブロック（122-143行目）でパラメータ定義確認 |

**主要処理フロー**:
1. **145-149行目**: beginブロック - Windows専用チェック
2. **153-178行目**: DAC接続またはh通常接続の選択
3. **180-188行目**: パスワード復号化（Get-DecryptedObject）
4. **190-192行目**: 資格情報一覧取得（Get-DbaCredential）
5. **193-275行目**: processブロック - 宛先ループと移行処理

#### Step 3: 資格情報移行ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaCredential.ps1 | `public/Copy-DbaCredential.ps1` | 205-274行目の資格情報コピー処理 |

**主要処理フロー**:
- **218-238行目**: 既存資格情報チェックとForce処理
- **241-259行目**: New-DbaCredentialパラメータ構築
- **249-255行目**: CryptographicProvider処理
- **256-259行目**: パスワード設定（ExcludePassword未指定時）
- **261-273行目**: New-DbaCredential実行と結果出力

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

```
Copy-DbaCredential
    │
    ├─ begin: プラットフォームチェック
    │      └─ Windows専用確認
    │
    ├─ Connect-DbaInstance（ソース接続）
    │      └─ DAC接続 or 通常接続
    │
    ├─ Get-DecryptedObject（パスワード復号化）
    │      └─ 内部暗号化データ取得・復号
    │
    ├─ Get-DbaCredential（資格情報取得）
    │      └─ Name/Identity フィルタ
    │
    └─ foreach destination
           ├─ Connect-DbaInstance（宛先接続）
           │
           └─ foreach credential
                  ├─ 既存確認
                  │      └─ Force時はDrop()
                  │
                  ├─ CryptographicProvider確認
                  │
                  └─ New-DbaCredential（資格情報作成）
                         └─ MigrationObject出力
```

### データフロー図

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

Source ──────────────▶ Connect-DbaInstance
                       (DAC) ──────────────────────▶ SMO Server
                              │
Credential ──────────────────┤
(Windows)                     │
                              ▼
                       Get-DecryptedObject ────────▶ Decrypted Passwords
                              │
Name/Identity ───────────────┤
ExcludeName/Identity ────────┤
                              ▼
                       Get-DbaCredential ──────────▶ Credential List
                              │
Destination[] ───────────────┤
                              ▼
                       Connect-DbaInstance ────────▶ Dest Server
                              │
Force ───────────────────────┤
                              ▼
                       New-DbaCredential ──────────▶ PSCustomObject
                                                     (MigrationObject)
                                                     - DateTime
                                                     - SourceServer
                                                     - DestinationServer
                                                     - Name
                                                     - Type
                                                     - Status
                                                     - Notes
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaCredential.ps1 | `public/Copy-DbaCredential.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続（DAC対応） |
| Get-DbaCredential.ps1 | `public/Get-DbaCredential.ps1` | ソース | 資格情報取得 |
| New-DbaCredential.ps1 | `public/New-DbaCredential.ps1` | ソース | 資格情報作成 |
| Get-DecryptedObject.ps1 | `private/Get-DecryptedObject.ps1` | ソース | パスワード復号化（内部関数） |
