# 機能設計書 232-Set-DbatoolsInsecureConnection

## 概要

本ドキュメントは、dbatools PowerShellモジュールのSet-DbatoolsInsecureConnection関数に関する機能設計書です。この関数はSQL Server接続のセキュリティ設定を緩和し、暗号化を無効化して全てのサーバー証明書を信頼する設定に戻します。

### 本機能の処理概要

**業務上の目的・背景**：Microsoftは SQL Serverクライアントライブラリのデフォルト接続設定を変更し、暗号化を必須とし証明書検証を行うようになりました。この変更により、開発環境や自己署名証明書を使用する環境、レガシー環境で接続エラーが発生する場合があります。本機能は、これらの新しいセキュリティデフォルトを元に戻し、以前の動作との互換性を確保します。

**機能の利用シーン**：開発・テスト環境での接続問題解決時、自己署名証明書を使用するサーバーへの接続時、レガシー環境でのdbatools使用時、接続エラー「証明書チェーンは信頼されていない認証局によって発行されました」が発生した場合に使用されます。

**主要な処理内容**：
1. sql.connection.trustcert設定をtrueに変更（全てのサーバー証明書を信頼）
2. sql.connection.encrypt設定をfalseに変更（暗号化を無効化）
3. SessionOnly指定がない場合は設定を永続化

**関連システム・外部連携**：dbatoolsの内部設定システム（Set-DbatoolsConfig, Register-DbatoolsConfig）と連携します。

**権限による制御**：特別な権限は不要です。設定スコープによりユーザー単位またはシステム全体への適用が可能です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | CLIコマンド | 主機能 | PowerShellコマンドラインから直接実行 |

## 機能種別

構成設定変更処理（Configuration Management）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SessionOnly | switch | No | 現在のセッションのみに設定を適用（永続化しない） | - |
| Scope | ConfigScope | No | 永続化設定のスコープ（デフォルト：UserDefault） | 有効なConfigScopeのみ |
| Register | switch | No | 非推奨パラメータ（将来削除予定） | 使用時に警告出力 |

### 入力データソース

- PowerShellコマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | None | パイプラインへの出力なし |

### 出力先

- 設定値はdbatoolsの内部設定システムに保存
- Passthruオプションにより設定オブジェクトが内部的に処理される

## 処理フロー

### 処理シーケンス

```
1. Registerパラメータのチェック
   └─ 指定時は非推奨警告を出力
2. sql.connection.trustcert設定の変更
   └─ 値をtrueに設定（Passthru指定）
3. sql.connection.encrypt設定の変更
   └─ 値をfalseに設定（Passthru指定）
4. 永続化判定
   └─ SessionOnlyでない場合は両設定を登録
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Register指定?}
    B -->|Yes| C[非推奨警告出力]
    B -->|No| D[trustcert設定変更]
    C --> D
    D --> E[encrypt設定変更]
    E --> F{SessionOnly?}
    F -->|Yes| G[終了]
    F -->|No| H[trustcert永続化]
    H --> I[encrypt永続化]
    I --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 証明書信頼設定 | sql.connection.trustcertをtrueに設定 | 常時 |
| BR-002 | 暗号化無効化 | sql.connection.encryptをfalseに設定 | 常時 |
| BR-003 | デフォルト永続化 | SessionOnly未指定時は設定を永続化 | SessionOnly未指定時 |
| BR-004 | 非推奨パラメータ警告 | Registerパラメータ使用時に警告 | Register指定時 |

### 計算ロジック

特になし（設定値は固定）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

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

データベース操作はありません。dbatools内部設定システムのみを操作します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 通常はエラーなし | - |

### リトライ仕様

リトライ処理は不要です。

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

トランザクション管理は不要です（設定変更のみ）。

## パフォーマンス要件

即座に設定が適用されます。

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

- **警告**：この機能は接続セキュリティを低下させます
- 暗号化が無効になるため、ネットワーク上でデータが平文で送信される可能性があります
- 証明書検証が無効になるため、中間者攻撃のリスクがあります
- 本番環境での使用は推奨されません
- 開発・テスト環境でのみ使用することを推奨します

## 備考

- 詳細情報：https://dbatools.io/newdefaults
- 関連ブログ：https://blog.netnerds.net/2023/03/new-defaults-for-sql-server-connections-encryption-trust-certificate/

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbatoolsInsecureConnection.ps1 | `public/Set-DbatoolsInsecureConnection.ps1` | パラメータ定義（51-55行目） |

**読解のコツ**: Dataplat.Dbatools.Configuration.ConfigScopeはdbatoolsの設定スコープを定義するEnum型です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbatoolsInsecureConnection.ps1 | `public/Set-DbatoolsInsecureConnection.ps1` | 関数定義とprocess block（49-68行目） |

**主要処理フロー**:
1. **57-59行目**: Registerパラメータの非推奨警告
2. **61行目**: sql.connection.trustcert設定をtrueに変更
3. **62行目**: sql.connection.encrypt設定をfalseに変更
4. **64-67行目**: SessionOnly未指定時の永続化処理

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | 設定値の変更方法 |
| 3-2 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | 設定の永続化方法 |

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

```
Set-DbatoolsInsecureConnection
    │
    ├─ Write-Message
    │      └─ 非推奨警告の出力
    │
    ├─ Set-DbatoolsConfig (trustcert)
    │      └─ sql.connection.trustcert = true
    │
    ├─ Set-DbatoolsConfig (encrypt)
    │      └─ sql.connection.encrypt = false
    │
    └─ Register-DbatoolsConfig (条件付き)
           ├─ sql.connection.trustcert永続化
           └─ sql.connection.encrypt永続化
```

### データフロー図

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

SessionOnly ────────┐
                    │
Scope ──────────────┼──▶ Set-DbatoolsInsecureConnection ──▶ なし（内部設定変更のみ）
                    │         │
Register ───────────┘         ├─ Set-DbatoolsConfig
                              └─ Register-DbatoolsConfig

[dbatools内部設定] ◄───── 設定書き込み ─────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbatoolsInsecureConnection.ps1 | `public/Set-DbatoolsInsecureConnection.ps1` | ソース | メイン関数実装 |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定値変更ヘルパー |
| Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ソース | 設定永続化ヘルパー |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力ヘルパー |
