# 機能設計書 596-Get-DbaDbAsymmetricKey

## 概要

本ドキュメントは、SQL Serverデータベースから非対称キー情報を取得するPowerShellコマンドレット `Get-DbaDbAsymmetricKey` の機能設計書である。

### 本機能の処理概要

本機能は、SQL Serverデータベースに格納されている非対称キー（Asymmetric Key）の情報を取得し、セキュリティ監査や暗号化キー管理に使用するコマンドレットである。

**業務上の目的・背景**：SQL Serverでは非対称キーを使用して、列レベル暗号化、デジタル署名、証明書の作成、Transparent Data Encryption (TDE)の暗号化キー保護などを行う。従来はシステムカタログを直接クエリする必要があったが、本コマンドを使用することで、複数データベースの非対称キーインベントリの取得、暗号化アルゴリズムとキー長の確認、コンプライアンス監査でのキー一覧作成を自動化できる。

**機能の利用シーン**：
- セキュリティ監査での暗号化キーインベントリ作成
- 暗号化アルゴリズムの強度確認（RSA 2048以上の確認等）
- キーローテーション計画のための既存キー把握
- 複数データベース間でのキー構成比較
- コンプライアンス報告書作成

**主要な処理内容**：
1. SqlInstanceパラメータ使用時はGet-DbaDatabase経由で対象データベースを取得
2. 各データベースのAsymmetricKeysコレクションにアクセス
3. 名前によるフィルタリング（Name指定時）
4. SMO AsymmetricKeyオブジェクトに追加プロパティを付与
5. 結果をパイプラインに出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してSQL Serverインスタンスに接続し、AsymmetricKeysコレクションを取得する。

**権限による制御**：対象データベースに対するVIEW DEFINITION権限が必要。非対称キーのメタデータを読み取るためには適切な権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio | 参照画面 | データベース > セキュリティ > 非対称キーで確認 |
| - | PowerShellコンソール | 主画面 | コマンドの実行および結果表示 |

## 機能種別

データ取得処理 / セキュリティ監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 接続用の代替資格情報 | 有効なPSCredentialオブジェクト |
| Database | string[] | No | 検索対象データベース名（ワイルドカード対応） | データベース名 |
| ExcludeDatabase | string[] | No | 除外するデータベース名（ワイルドカード対応） | データベース名 |
| Name | string[] | No | 取得する非対称キー名（ワイルドカード対応） | キー名 |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力用データベースオブジェクト | SMO Databaseオブジェクト |
| EnableException | switch | No | 例外を直接スローするフラグ | - |

### 入力データソース

- SqlInstanceパラメータ：ユーザー指定のSQL Serverインスタンス名
- InputObject：Get-DbaDatabase等の他のdbatoolsコマンドからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| Database | string | 非対称キーが格納されているデータベース名 |
| Name | string | 非対称キーの名前 |
| Owner | string | 非対称キーの所有者 |
| KeyEncryptionAlgorithm | string | キー暗号化アルゴリズム（RSA_512, RSA_1024, RSA_2048, RSA_3072, RSA_4096） |
| KeyLength | int | キー長（ビット単位） |
| PrivateKeyEncryptionType | string | 秘密鍵の暗号化タイプ |
| Thumbprint | byte[] | 非対称キーのサムプリント |

### 出力先

- PowerShellパイプライン：Microsoft.SqlServer.Management.Smo.AsymmetricKey オブジェクト（追加プロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. 対象データベース取得
   └─ SqlInstance使用時: Get-DbaDatabase経由で取得
   └─ InputObject使用時: パイプライン入力をそのまま使用
2. 各データベースに対するループ処理
   └─ アクセシビリティチェック（IsAccessible）
   └─ AsymmetricKeysコレクション取得
   └─ 空の場合はスキップ（Verboseログ出力）
3. フィルタリング
   └─ Name指定時: 名前でフィルタ
4. プロパティ追加と出力
   └─ ComputerName, InstanceName, SqlInstance, Database, DatabaseId追加
   └─ Select-DefaultViewで表示プロパティ制限
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDatabase実行]
    B -->|No| D[InputObjectを使用]
    C --> E[対象DB取得完了]
    D --> E
    E --> F{次のDBあり?}
    F -->|No| Z[終了]
    F -->|Yes| G{IsAccessible?}
    G -->|No| H[警告出力してスキップ]
    H --> F
    G -->|Yes| I[AsymmetricKeys取得]
    I --> J{キーあり?}
    J -->|No| K[Verboseログ出力]
    K --> F
    J -->|Yes| L{Name指定?}
    L -->|Yes| M[名前でフィルタ]
    L -->|No| N[全キー使用]
    M --> O[各キーにプロパティ追加]
    N --> O
    O --> P[Select-DefaultView]
    P --> Q[パイプライン出力]
    Q --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクセシビリティチェック | IsAccessible=falseのデータベースはスキップ | 各データベース処理時 |
| BR-002 | 空コレクション処理 | 非対称キーが存在しない場合はVerboseログのみ | AsymmetricKeys.Count=0時 |
| BR-003 | 名前フィルタリング | Nameパラメータ指定時は-in演算子でフィルタ | Name指定時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読み取り | sys.asymmetric_keys | SELECT（間接） | SMO経由で非対称キーメタデータ取得 |

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

#### sys.asymmetric_keys

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, principal_id, pvt_key_encryption_type, algorithm_desc, key_length, thumbprint | 全件取得 | SMO AsymmetricKeyオブジェクト経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Warning | データベースにアクセス不可 | データベース状態を確認 |
| - | Verbose | 非対称キーが存在しない | 情報メッセージのみ（正常動作） |

### リトライ仕様

リトライ処理は実装されていない。アクセス不可データベースはスキップして処理を継続。

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

該当なし（読み取り専用処理）

## パフォーマンス要件

- データベース数とキー数に比例した処理時間
- SMOのコレクション取得は初回アクセス時に遅延読み込み

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

- VIEW DEFINITION権限が必要
- 秘密鍵の内容は取得できない（メタデータのみ）
- Thumbprintは秘密情報ではないが、キーの特定に使用可能

## 備考

- RSA 2048ビット以上のキー長が現代のセキュリティ要件では推奨
- PrivateKeyEncryptionTypeでマスターキー暗号化かパスワード暗号化かを確認可能

---

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

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

### 推奨読解順序

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

SMO AsymmetricKeyオブジェクトの構造と追加プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbAsymmetricKey.ps1 | `public/Get-DbaDbAsymmetricKey.ps1` | 129-133行目のAdd-Member定義 |

**読解のコツ**: SMO AsymmetricKeyオブジェクトにComputerName, InstanceName, SqlInstance, Database, DatabaseIdプロパティを追加している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbAsymmetricKey.ps1 | `public/Get-DbaDbAsymmetricKey.ps1` | 関数定義全体の構造 |

**主要処理フロー**:
1. **95-105行目**: パラメータ定義
2. **106-109行目**: SqlInstance指定時のGet-DbaDatabase呼び出し
3. **111-137行目**: データベースループと非対称キー取得

#### Step 3: フィルタリングと出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbAsymmetricKey.ps1 | `public/Get-DbaDbAsymmetricKey.ps1` | フィルタリングとプロパティ追加 |

**主要処理フロー**:
- **111-115行目**: IsAccessibleチェックとスキップ処理
- **117-122行目**: AsymmetricKeys取得と空チェック
- **124-126行目**: Name指定時のフィルタリング
- **128-135行目**: プロパティ追加とSelect-DefaultView

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

```
Get-DbaDbAsymmetricKey
    │
    ├─ Get-DbaDatabase (SqlInstance使用時)
    │      └─ Connect-DbaInstance
    │
    └─ foreach ($db in $InputObject)
           │
           ├─ IsAccessibleチェック
           │
           ├─ $db.AsymmetricKeys
           │      └─ SMO経由でsys.asymmetric_keysから取得
           │
           ├─ Where-Object Name -in $Name (フィルタリング)
           │
           ├─ Add-Member (プロパティ追加)
           │
           └─ Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance ───────────▶ Get-DbaDatabase ───▶ SMO Database[]
        or
InputObject ─────────────────────────────────▶ SMO Database[]
                                                    │
                                                    ▼
                                            IsAccessibleチェック
                                                    │
                                                    ▼
                                            AsymmetricKeys取得
                                                    │
                                                    ▼
                                            Name フィルタ（オプション）
                                                    │
                                                    ▼
                                            Add-Member
                                                    │
                                                    ▼
                                            Select-DefaultView
                                                    │
                                                    ▼
                                            パイプライン出力 ───▶ コンソール表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbAsymmetricKey.ps1 | `public/Get-DbaDbAsymmetricKey.ps1` | ソース | メイン機能実装 |
| New-DbaDbAsymmetricKey.ps1 | `public/New-DbaDbAsymmetricKey.ps1` | ソース | 非対称キー作成機能 |
| Remove-DbaDbAsymmetricKey.ps1 | `public/Remove-DbaDbAsymmetricKey.ps1` | ソース | 非対称キー削除機能 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得機能 |
