# 機能設計書 609-New-DbaServiceMasterKey

## 概要

本ドキュメントは、masterデータベースにインスタンスレベルの暗号化階層のためのサービスマスターキーを作成する`New-DbaServiceMasterKey`機能の設計書である。

### 本機能の処理概要

`New-DbaServiceMasterKey`は、masterデータベースにサービスマスターキーを作成する機能である。サービスマスターキーはSQL Serverの暗号化階層の最上位に位置し、インスタンス上のすべてのデータベースのデータベースマスターキー、証明書、およびその他の暗号化オブジェクトを自動的に暗号化して保護する。これは通常、SQL Serverインスタンスで暗号化戦略を実装する最初のステップであり、個々のデータベースマスターキーのパスワードを手動で管理する必要性を排除する。

**業務上の目的・背景**：サービスマスターキー（実際にはmasterデータベースのマスターキー）は、SQL Server暗号化階層のルートとして機能する。このキーは、他のデータベースのマスターキーを自動的に暗号化し、SQL Serverサービス起動時に透過的に復号化される。これにより、管理者は各データベースのマスターキーパスワードを個別に管理する必要がなくなり、暗号化運用が大幅に簡素化される。

**機能の利用シーン**：
- 新規SQL Serverインスタンスの暗号化基盤構築
- TDEやAlways Encrypted実装前の準備
- 複数データベースにわたる暗号化戦略の一元管理
- セキュリティ要件に基づくインスタンス初期設定

**主要な処理内容**：
1. パスワードの取得（SecurePassword、Credential、または対話入力）
2. New-DbaDbMasterKeyをDatabase=masterで呼び出し
3. 結果を返却

**関連システム・外部連携**：SQL Server SMO、SQL Server暗号化階層

**権限による制御**：masterデータベースに対するCONTROL権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | CLIベースの機能のため関連画面なし |

## 機能種別

オブジェクト作成（INSERT相当） / 暗号化キー管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | Mandatory |
| SqlCredential | PSCredential | No | SQL Server接続用の代替資格情報 | なし |
| Credential | PSCredential | No | サービスマスターキーパスワードを提供するPSCredentialオブジェクト | なし |
| SecurePassword | SecureString | No | サービスマスターキーの暗号化に使用するパスワード | なし |
| EnableException | Switch | No | 例外処理の有効化フラグ | なし |

### 入力データソース

- SQL Server SMO（New-DbaDbMasterKey経由）
- コンソール入力（パスワード未指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス形式） |
| Database | String | 常に"master" |
| CreateDate | DateTime | サービスマスターキーの作成日時 |
| DateLastModified | DateTime | サービスマスターキーの最終更新日時 |
| IsEncryptedByServer | Boolean | サーバーによって暗号化されているかどうか |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.MasterKey オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 各SqlInstanceに対して処理（processブロック）
   ├─ ShouldProcess確認
   └─ New-DbaDbMasterKey を Database = master で呼び出し
       └─ SecurePassword と Credential を引き継ぎ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ開始]
    B --> C{ShouldProcess確認}
    C -->|No| D[スキップ]
    C -->|Yes| E[New-DbaDbMasterKey呼び出し]
    E --> F[Database = master]
    F --> G[結果出力]
    G --> H{次のインスタンス?}
    D --> H
    H -->|Yes| B
    H -->|No| I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-609-01 | データベース固定 | 常にmasterデータベースにマスターキーを作成 | 常時 |
| BR-609-02 | 必須パラメータ | SqlInstanceは必須 | 常時 |
| BR-609-03 | 委譲パターン | 実際の処理はNew-DbaDbMasterKeyに委譲 | 常時 |
| BR-609-04 | パスワード引き継ぎ | SecurePasswordとCredentialをそのままNew-DbaDbMasterKeyに渡す | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| マスターキー作成 | master.sys.symmetric_keys | INSERT | サービスマスターキーレコードの作成 |

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

#### master.sys.symmetric_keys

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | ##MS_DatabaseMasterKey## | システム予約名 |
| INSERT | create_date | 現在日時 | システムにより設定 |
| INSERT | is_master_key_encrypted_by_server | 1 | Windowsサービスアカウントで暗号化 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 既存マスターキーエラー | masterに既にMasterKeyが存在 | 既存キーを削除 |
| - | 権限エラー | CONTROL権限なし | 適切な権限を付与 |
| - | 接続エラー | SQL Serverに接続できない | 接続情報を確認 |

### リトライ仕様

特になし（New-DbaDbMasterKeyに委譲）

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

SMOによるマスターキー作成は暗黙のトランザクション内で実行される

## パフォーマンス要件

特に規定なし

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

- masterデータベースに対するCONTROL権限が必要
- サービスマスターキーはWindowsサービスアカウントによって暗号化される
- パスワードはSecureString型で安全に取り扱われる
- サービスマスターキーのバックアップを安全に保管することが重要
- サービスアカウントの変更時はキーの再暗号化が必要になる場合がある

## 備考

- 本機能はNew-DbaDbMasterKeyのシンプルなラッパーである
- Database = "master" が固定で指定される
- サービスマスターキーは他のデータベースのマスターキーを自動的に保護する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaServiceMasterKey.ps1 | `public/New-DbaServiceMasterKey.ps1` | 38-56行目のコメントで出力オブジェクト（MasterKey）の構造を確認 |
| 1-2 | New-DbaServiceMasterKey.ps1 | `public/New-DbaServiceMasterKey.ps1` | 74-83行目のparamブロックで入力パラメータ定義を確認 |

**読解のコツ**: 本機能は非常にシンプルなラッパーで、実際の処理はNew-DbaDbMasterKeyに委譲されている点に注目。

#### Step 2: processブロックの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaServiceMasterKey.ps1 | `public/New-DbaServiceMasterKey.ps1` | 85-91行目でNew-DbaDbMasterKey呼び出しを確認 |

**主要処理フロー**:
- **86行目**: foreachでSqlInstanceをループ
- **87行目**: ShouldProcess確認（"Creating new master key"）
- **88行目**: New-DbaDbMasterKeyを呼び出し（Database = master, SecurePassword, Credential引き継ぎ）

#### Step 3: 委譲先の処理を理解する（参照）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbMasterKey.ps1 | `public/New-DbaDbMasterKey.ps1` | 委譲先の詳細実装を確認（608-New-DbaDbMasterKey設計書参照） |

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

```
New-DbaServiceMasterKey
    │
    └─ [process]
        │
        └─ New-DbaDbMasterKey
               │
               ├─ Database = "master" (固定)
               │
               ├─ SqlInstance (引き継ぎ)
               │
               ├─ SqlCredential (引き継ぎ)
               │
               ├─ SecurePassword (引き継ぎ)
               │
               └─ Credential (引き継ぎ)
                      │
                      ├─ Get-DbaDatabase (master)
                      │
                      ├─ SMO MasterKey作成
                      │
                      └─ 結果出力
```

### データフロー図

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

SqlInstance ─────────┐
                     │
SqlCredential ───────┤
                     ├─▶ New-DbaDbMasterKey
SecurePassword ──────┤        │
                     │        ├─ Database = "master"
Credential ──────────┘        │
                              ▼
                    master.MasterKey 作成
                              │
                              ▼
                    MasterKeyオブジェクト出力
                    - ComputerName
                    - InstanceName
                    - SqlInstance
                    - Database = "master"
                    - CreateDate
                    - DateLastModified
                    - IsEncryptedByServer
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaServiceMasterKey.ps1 | `public/New-DbaServiceMasterKey.ps1` | ソース | メイン機能（ラッパー） |
| New-DbaDbMasterKey.ps1 | `public/New-DbaDbMasterKey.ps1` | ソース | 実際の処理を行う委譲先 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得（間接） |
| ConvertFrom-SecurePass.ps1 | `private/functions/ConvertFrom-SecurePass.ps1` | ソース | SecureString変換（間接） |
