# 機能設計書 590-Copy-DbaDbCertificate

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Copy-DbaDbCertificate`コマンドレットに関する機能設計書です。本機能はデータベースレベルの証明書をソースSQL Serverから宛先サーバーにコピーします。秘密鍵とマスターキー依存関係を含めます。

### 本機能の処理概要

`Copy-DbaDbCertificate`は、ソースデータベースから証明書をバックアップし、宛先サーバーの一致するデータベースにリストアすることで、SQL Serverインスタンス間でデータベース証明書を転送します。Transparent Data Encryption (TDE)やその他の証明書ベースのセキュリティ機能を使用するデータベースを移動する際に不可欠な、複雑な証明書マイグレーションプロセスを処理します。

**業務上の目的・背景**：TDEやその他の証明書ベースのセキュリティ機能を使用するデータベースをマイグレーションする際、証明書も一緒に移行する必要があります。手動での証明書マイグレーションは複雑でエラーが発生しやすく、秘密鍵のバックアップ、共有パスへの配置、宛先でのマスターキー作成、証明書のリストアなど多くのステップが必要です。本機能はこれらの操作を自動化します。

**機能の利用シーン**：
- TDEを使用するデータベースのマイグレーション
- 災害復旧環境でのセキュリティ設定同期
- 証明書ベースの暗号化を維持した環境複製
- データベースコピー時の証明書依存関係の解決
- 複数サーバーへの証明書の一括デプロイ

**主要な処理内容**：
1. ソースインスタンスからの証明書情報取得（Get-DbaDbCertificate）
2. 共有パスへのアクセス権限確認
3. 宛先にマスターキーが存在しない場合は作成
4. Backup-DbaDbCertificateによる証明書バックアップ
5. ファイル権限の設定（Everyone読み取り可能）
6. Restore-DbaDbCertificateによる証明書リストア
7. バックアップファイルの削除

**関連システム・外部連携**：Get-DbaDbCertificate、Backup-DbaDbCertificate、Restore-DbaDbCertificate、New-DbaDbMasterKey、Get-DbaDbMasterKeyを使用します。

**権限による制御**：ソースおよび宛先の両方でsysadmin権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 33 | 証明書管理 | 補助機能 | データベース証明書のコピー |

## 機能種別

データ連携 / セキュリティ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | 証明書コピー元のソースインスタンス | sysadmin権限必要 |
| SourceSqlCredential | PSCredential | No | ソースインスタンス接続用の代替資格情報 | - |
| Destination | DbaInstanceParameter[] | Yes | 証明書コピー先の宛先インスタンス | 複数指定可能 |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンス接続用の代替資格情報 | - |
| Database | string[] | No | 証明書コピー対象のデータベース | - |
| ExcludeDatabase | string[] | No | 除外するデータベース | - |
| Certificate | string[] | No | コピー対象の特定証明書名 | - |
| ExcludeCertificate | string[] | No | 除外する証明書名 | - |
| SharedPath | string | Yes* | 証明書バックアップファイルの共有パス | 両サーバーからアクセス可能 |
| MasterKeyPassword | SecureString | No | 宛先でマスターキー作成時のパスワード | TDE証明書時に必要 |
| EncryptionPassword | SecureString | No | 証明書バックアップの暗号化パスワード | 未指定時は自動生成 |
| DecryptionPassword | SecureString | No | 証明書リストア時の復号パスワード | - |
| EnableException | switch | No | 例外をスローするモード | - |

### 入力データソース

- ソースインスタンスのデータベース証明書（Get-DbaDbCertificate）
- 共有ネットワークパスの証明書バックアップファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | コピー操作実行日時 |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | 証明書名 |
| Type | string | 常に"Database Certificate" |
| Status | string | 操作結果（Successful, Skipped, Failed） |
| Notes | string | 追加情報（スキップ理由、エラー詳細等） |

### 出力先

PowerShellパイプラインへのPSCustomObject（TypeName: MigrationObject）の出力

## 処理フロー

### 処理シーケンス

```
1. ソース証明書の取得（beginブロック）
   └─ Get-DbaDbCertificateでユーザー証明書を取得（#で始まらない）
   └─ ExcludeCertificateでフィルタリング

2. 暗号化パスワードの決定
   └─ EncryptionPassword未指定時はGet-RandomPasswordで自動生成

3. 共有パスへのアクセス権限確認
   └─ Test-DbaPathでソースサービスアカウントのアクセス確認

4. 各宛先インスタンスでの処理
   └─ Connect-DbaInstance（MinimumVersion 10）
   └─ Test-DbaPathで宛先サービスアカウントのアクセス確認

5. マスターキーの確認・作成
   └─ MasterKey暗号化証明書がある場合、masterデータベースにマスターキー必要
   └─ MasterKeyPasswordが指定されていれば作成

6. 各データベースでの証明書処理
   └─ 宛先データベースが存在するか確認
   └─ 証明書が宛先に既存かどうか確認
   └─ マスターキーの確認・作成（データベースレベル）
   └─ Backup-DbaDbCertificateで証明書バックアップ
   └─ ファイル権限設定（Everyone読み取り可能）
   └─ Restore-DbaDbCertificateで証明書リストア
   └─ バックアップファイル削除

7. 結果出力
   └─ MigrationObjectとして結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Get-DbaDbCertificate]
    B --> C[暗号化パスワード決定]
    C --> D[共有パスアクセス確認 Source]
    D --> E{アクセス可能?}
    E -->|No| F[エラー終了]
    E -->|Yes| G[各宛先ループ]
    G --> H[Connect-DbaInstance]
    H --> I[共有パスアクセス確認 Dest]
    I --> J{アクセス可能?}
    J -->|No| K[次の宛先へ]
    J -->|Yes| L{MasterKey暗号化証明書?}
    L -->|Yes| M[masterにマスターキー確認/作成]
    L -->|No| N[各データベースループ]
    M --> N
    N --> O[証明書存在確認]
    O --> P{既存?}
    P -->|Yes| Q[Skipped出力]
    P -->|No| R[マスターキー確認/作成]
    R --> S[Backup-DbaDbCertificate]
    S --> T{バックアップ成功?}
    T -->|No| U[Failed出力]
    T -->|Yes| V[ファイル権限設定]
    V --> W[Restore-DbaDbCertificate]
    W --> X{リストア成功?}
    X -->|No| U
    X -->|Yes| Y[Successful出力]
    Y --> Z[バックアップファイル削除]
    Z --> AA{次の証明書?}
    Q --> AA
    U --> AA
    AA -->|Yes| O
    AA -->|No| AB{次のDB?}
    AB -->|Yes| N
    AB -->|No| K
    K --> AC{次の宛先?}
    AC -->|Yes| G
    AC -->|No| AD[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-590-01 | 共有パス必須 | 両サーバーのサービスアカウントがアクセス可能な共有パスが必要 | 常時 |
| BR-590-02 | マスターキー自動作成 | MasterKeyPassword指定時、マスターキーがなければ自動作成 | MasterKey暗号化証明書時 |
| BR-590-03 | 既存証明書スキップ | 宛先に同名の証明書が存在する場合はスキップ | 常時 |
| BR-590-04 | システム証明書除外 | #で始まる証明書（システム証明書）は対象外 | 常時 |
| BR-590-05 | ファイル自動削除 | 転送後のバックアップファイルは自動削除 | 成功時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 証明書取得 | sys.certificates | SELECT | ソースから証明書情報取得 |
| マスターキー作成 | sys.symmetric_keys | INSERT | 宛先にマスターキー作成 |
| 証明書バックアップ | - | BACKUP CERTIFICATE | 証明書をファイルにエクスポート |
| 証明書リストア | sys.certificates | CREATE CERTIFICATE | 宛先に証明書をインポート |

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

#### sys.certificates

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, thumbprint, etc. | 全ユーザー証明書 | ソースから取得 |
| INSERT | - | Restore-DbaDbCertificate | 宛先に証明書作成 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | Stop-Function |
| - | AccessError | 共有パスアクセス不可 | Stop-Function |
| - | MasterKeyError | マスターキー作成失敗 | Stop-Function、次へ |
| - | BackupError | 証明書バックアップ失敗 | Failed出力、次の証明書へ |
| - | RestoreError | 証明書リストア失敗 | Failed出力、次の証明書へ |

### リトライ仕様

リトライ処理なし。各証明書は独立して処理されます。

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

各証明書のバックアップ/リストアは個別に実行されます。明示的なトランザクション管理はありません。

## パフォーマンス要件

特に規定なし。証明書数が多い場合はバックアップ/リストア処理に時間がかかる可能性があります。

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

- ソースおよび宛先の両方でsysadmin権限が必要
- 共有パスへの証明書バックアップファイルは一時的にEveryone読み取り可能に設定
- バックアップファイルは処理後に自動削除
- SupportsShouldProcess実装（ConfirmImpact = "High"）

## 備考

- 既存のバックアップファイルが共有パスに存在する場合は再利用を試みる
- MasterKey暗号化タイプの証明書にはマスターキーが必須
- SQL Server 2008以上対応（MinimumVersion 10）

---

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

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

### 推奨読解順序

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

出力されるMigrationObjectの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 256-268行目: 出力オブジェクト構造 |

**読解のコツ**: $copyDbCertificateStatusオブジェクトにはSourceServer、SourceDatabase、DestinationServer、Name、Type、Status、Notes、DateTimeが含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 132-149行目: パラメータ定義 |

**主要処理フロー**:
1. **134-139行目**: Source、Destination（必須）、資格情報
2. **140-143行目**: Database、ExcludeDatabase、Certificate、ExcludeCertificate
3. **144-148行目**: SharedPath、MasterKeyPassword、EncryptionPassword、DecryptionPassword

#### Step 3: ソース証明書の取得

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 150-168行目: beginブロック |

**主要処理フロー**:
- **152-161行目**: Get-DbaDbCertificateでユーザー証明書取得
- **162行目**: #で始まらない、ExcludeCertificateに含まれない証明書をフィルタ
- **170-174行目**: 暗号化パスワードの決定
- **176-179行目**: ソースサービスアカウントの共有パスアクセス確認

#### Step 4: マスターキー処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 195-217行目: masterデータベースのマスターキー |
| 4-2 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 226-249行目: 各データベースのマスターキー |

**主要処理フロー**:
- **195行目**: MasterKey暗号化証明書が存在するかチェック
- **197-215行目**: masterにマスターキーがなければ作成
- **227-249行目**: 各データベースにマスターキーがなければ作成

#### Step 5: 証明書のバックアップとリストア

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 300-350行目: バックアップ処理 |
| 5-2 | Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | 352-386行目: リストア処理 |

**主要処理フロー**:
- **304-312行目**: Backup-DbaDbCertificateパラメータ設定
- **318-327行目**: 既存ファイル確認、なければバックアップ実行
- **333-342行目**: ファイル権限設定（Everyone読み取り可能）
- **353-362行目**: Restore-DbaDbCertificateパラメータ設定
- **364行目**: Restore-DbaDbCertificate実行
- **377-382行目**: バックアップファイル削除

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

```
Copy-DbaDbCertificate
    │
    ├─ Get-DbaDbCertificate
    │      └─ ソース証明書の取得
    │
    ├─ Connect-DbaInstance
    │      └─ 宛先インスタンス接続（MinimumVersion 10）
    │
    ├─ Test-DbaPath
    │      └─ 共有パスアクセス確認
    │
    ├─ Get-DbaDbMasterKey
    │      └─ マスターキー存在確認
    │
    ├─ New-DbaDbMasterKey
    │      └─ マスターキー作成
    │
    ├─ Backup-DbaDbCertificate
    │      └─ 証明書バックアップ
    │
    ├─ Restore-DbaDbCertificate
    │      └─ 証明書リストア
    │
    └─ Remove-Item
           └─ バックアップファイル削除
```

### データフロー図

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

Source ────────────────▶ Get-DbaDbCertificate ─────────▶ $sourcecertificates
                              │
Database/Exclude ──────▶ フィルタリング ───────────────▶ 対象証明書
                              │
SharedPath ────────────▶ Backup-DbaDbCertificate ─────▶ .cer/.pvk ファイル
                              │
EncryptionPassword ────▶ 暗号化 ───────────────────────┐
                              │                         │
DecryptionPassword ────▶ Restore-DbaDbCertificate ────▶ 宛先証明書
                              │
MasterKeyPassword ─────▶ New-DbaDbMasterKey ──────────▶ マスターキー作成
                              │
                         MigrationObject出力 ──────────▶ 結果PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaDbCertificate.ps1 | `public/Copy-DbaDbCertificate.ps1` | ソース | メイン処理 |
| Get-DbaDbCertificate.ps1 | `public/Get-DbaDbCertificate.ps1` | ソース | 証明書取得 |
| Backup-DbaDbCertificate.ps1 | `public/Backup-DbaDbCertificate.ps1` | ソース | 証明書バックアップ |
| Restore-DbaDbCertificate.ps1 | `public/Restore-DbaDbCertificate.ps1` | ソース | 証明書リストア |
| Get-DbaDbMasterKey.ps1 | `public/Get-DbaDbMasterKey.ps1` | ソース | マスターキー取得 |
| New-DbaDbMasterKey.ps1 | `public/New-DbaDbMasterKey.ps1` | ソース | マスターキー作成 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パスアクセス確認 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
