# 署名付き証明書のサポート

<figure><img src="/files/tWYaRqfnM6xbVc5YUnhu" alt=""><figcaption></figcaption></figure>

**対象:** Keeperエンドポイント特権マネージャー (KEPM) を展開または運用するIT管理者向け。KEPMがデジタル証明書で内部通信を保護し、プラグインや実行ファイルを認証する仕組みと、環境に応じたカスタム証明書や代替署名 (AlternativeSignatures) の構成方法を説明します。

***

### 概要

KEPMにおける証明書には、次の2つの補完的な役割があります。

1. **トランスポートの保護** — KEPMの内部管理API (HTTPS) と内部メッセージブローカー (MQTT) はいずれもTLSで暗号化されます。証明書はその暗号化の基盤です。
2. **コンポーネントの認証** — プラグイン、ジョブの実行ファイル、カスタムツールがエージェントの管理APIまたはメッセージバスに接続する前に、KEPMは実行ファイルが信頼された証明書でデジタル署名されているかを検証します。これにより、未承認のコードが特権サービスとやり取りするのを防ぎます。

どちらの仕組みも既定で有効であり、多くの展開では初期構成は不要です。

***

### 既定の証明書の挙動

#### 自己署名証明書の自動生成

起動時に、カスタム証明書が構成されていない場合、KeeperPrivilegeManagerは**自己署名のX.509証明書**を自動的に生成します。この証明書は次の用途に使われます。

* **HTTPS管理API** (既定ポート `6889`)
* **MQTTメッセージブローカー** (既定ポート `8675`)

**既定の証明書の属性**

| プロパティ     | 値                                               |
| --------- | ----------------------------------------------- |
| Subject   | Localhost                                       |
| Key Usage | Server Authentication (OID `1.3.6.1.5.5.7.3.1`) |
| Binding   | Localhost / `127.0.0.1` のみ                      |
| Storage   | メモリ内 (サービス再起動のたびに再生成)                           |
| Validity  | 長期                                              |

通信はすべて `localhost` にのみバインドされるため、この用途では自己署名証明書で問題なく安全です。エージェントのAPIとメッセージバスはネットワークに公開されません。

{% hint style="info" %}
証明書は再起動のたびに再生成されるため、証明書をピン留めするクライアント (例: カスタムスクリプトや監視ツール) は、サービス再起動後に再信頼が必要になります。安定したピン留め証明書が必要な環境では、下記の「カスタム証明書」をご参照ください。
{% endhint %}

***

### プラグインと実行ファイルの証明書検証

#### KEPMがコンポーネントを検証する方法

KEPMの管理APIまたはメッセージバスと通信するすべてのプラグインと実行ファイルは、KEPMが信頼する証明書による**デジタル署名**が必要です。これは中核的なセキュリティ制御であり、Keeperが発行したコード、または管理者が明示的に信頼した証明書で署名されたコードだけが、特権を持つエージェントとやり取りできるようにします。

**検証の流れ (コンポーネントごと)**

1. KEPMはプラグインまたは実行ファイルからデジタル署名を取り出します。
2. 証明書のサムプリントを、信頼済み証明書の一覧と照合します。
3. サムプリントが一致すれば、コンポーネントの接続が許可されます。
4. 一致しない場合、接続は拒否され、エラーがログに記録されます。

**信頼済み証明書の出所**

| 出所                         | 説明                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------- |
| KeeperPrivilegeManagerの証明書 | サービス実行ファイルから自動的に取り出されます。Keeper署名のプラグインは既定で信頼されます。                                     |
| 代替証明書                      | 独自ツールや企業署名コンポーネント用に、`appsettings.json` の `Settings:AlternativeSignatures` に登録するサムプリント |

***

### AlternativeSignatures (代替署名)

`AlternativeSignatures` 設定では、追加の信頼済み証明書サムプリントを登録できます。次のような場合に使います。

* KEPMと通信する**カスタムツール** (例: 実行ファイルとしてパッケージ化した自動化スクリプト) がある場合
* KEPMのコンポーネントを自社のコード署名証明書で**再署名**して展開している場合
* カスタムプラグインやジョブの実行ファイルを開発またはテストしている場合

#### AlternativeSignaturesの構成

**手順1: 証明書のサムプリントを取得する**

**Windows (PowerShell)** の場合:

powershell

```powershell
# From an executable's Authenticode signature
Get-AuthenticodeSignature "C:\Path\To\YourTool.exe" |
    Select-Object -ExpandProperty SignerCertificate |
    Select-Object -ExpandProperty Thumbprint

# From a certificate store
Get-ChildItem -Path Cert:\CurrentUser\My -CodeSigningCert |
    Select-Object Thumbprint

# From a .pfx file
$cert = Get-PfxData -FilePath "certificate.pfx" `
    -Password (ConvertTo-SecureString "password" -AsPlainText -Force)
$cert.EndEntityCertificates[0].Thumbprint
```

**Linux / macOS** の場合:

bash

```bash
openssl x509 -in certificate.pem -fingerprint -noout -sha1
```

> **形式:** 構成に追加する前に、サムプリントからスペースとコロンをすべて取り除きます。読みやすさのため大文字にしてかまいません (照合は大文字・小文字を区別しません)。例: `A1B2C3D4E5F6789012345678901234567890ABCD`

**手順2: サムプリントを `appsettings.json` に追加する**

json

```json
{
  "Settings": {
    "AlternativeSignatures": [
      "A1B2C3D4E5F6789012345678901234567890ABCD",
      "FEDCBA0987654321098765432109876543210FEDC"
    ]
  }
}
```

**手順3: KeeperPrivilegeManagerサービスを再起動**し、変更を反映します。

> **重要:** `appsettings.json` を変更したあとは、必ずサービスを再起動してください。

#### AlternativeSignaturesに関するセキュリティのベストプラクティス

* **一覧は最小限に保つ。** 明示的に信頼する証明書のサムプリントだけを追加する。各エントリは、権限の高いサービスとやり取りできるコードの範囲を広げます。
* **エントリを記録する。** どの証明書がどのツールに対応し、誰が発行したかをメモする。
* **定期的に見直す。** 不要になった証明書や期限切れの証明書は削除する。
* **証明書のパスワードを構成ファイルに書かない。** Windowsの証明書ストアまたはシークレットマネージャーなどを使う。

***

### カスタム証明書

> **注:** HTTPSおよびMQTTエンドポイント向けの完全なカスタム証明書構成は、今後のKEPMバージョンで予定されています。以下は想定される構成モデルです。

カスタム証明書のサポートが利用可能になったら、自動生成の自己署名証明書の代わりに、管理APIとMQTTブローカー用に特定の証明書を構成できるようになります。安定したCA発行証明書や社内管理の証明書が必要な環境向けです。

**想定される `appsettings.json` の構成**

json

```json
{
  "Settings": {
    "CertPath": "C:\\Certificates\\keeper.pfx",
    "CertPassword": "",
    "CertStore": "My",
    "CertName": "KeeperPrivilegeManager"
  }
}
```

| 設定             | 説明                                                                   |
| -------------- | -------------------------------------------------------------------- |
| `CertPath`     | `.pfx` (Windows) または `.pem` (Linux/macOS) 証明書ファイルのパス                 |
| `CertPassword` | 証明書ファイルのパスワード。**本番では平文で保存しない。** Windowsの証明書ストアまたはシークレットマネージャーなどを使う。  |
| `CertStore`    | Windows証明書ストアの場所: `My` (個人)、`Root` (信頼されたルート)、`Trust` (信頼されたパブリッシャー) |
| `CertName`     | Windowsストア内の証明書の表示名                                                  |

**サポートされる証明書形式**

* `.pfx` / PKCS#12 — Windows
* `.pem` — LinuxおよびmacOS
* Windows証明書ストア — Windows (`CertStore` + `CertName` 経由)

***

### 証明書の更新

#### 自己署名証明書 (既定)

手作業は不要です。KEPMはサービス起動のたびに自己署名証明書を自動的に再生成します。通常運用では有効期限の心配はありません。

#### カスタム証明書

カスタム証明書を使う場合は、組織の証明書ライフサイクルに従って更新します。

1. 認証局 (CA) から更新済み証明書を取得します。
2. 証明書ファイルのパスまたはWindowsストアなど、適切な場所にインストールします。
3. パス、名前、またはサムプリントが変わった場合は `appsettings.json` を更新します。
4. KeeperPrivilegeManagerサービスを再起動します。
5. サムプリントが変わった場合、古い証明書に依存していたツールやプラグイン向けに `appsettings.json` の `AlternativeSignatures` を更新します。
6. プラグインが正常に起動し、カスタムツールが引き続き接続できることを確認します。

{% hint style="info" %}
**ベストプラクティス:** 期限切れ前に証明書を更新し、更新手順はまず本番以外の環境で試しましょう。
{% endhint %}

***

### 証明書がKEPMのセキュリティモデルで果たす役割

証明書の検証は、KEPMの多層防御の一層です。

| 層                   | 証明書の役割                                                                                                                                                                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **トランスポート暗号化**      | TLS証明書により、サービスとコンポーネント間のHTTPS (ポート `6889`) とMQTT (ポート `8675`) トラフィックが暗号化されます。トラフィックはすべて `localhost` 上にとどまります。                                                                                       |
| **プラグイン認証**         | `Plugins/*.json` から読み込まれるプラグインは、信頼された証明書で署名されている必要があります。サービスは起動前に各プラグインの署名を検証します。                                                                                                                   |
| **APIの認可**          | 管理APIの `Plugin` 認可レベルでは、呼び出し元がKEPMによって起動されていることに加え、KEPMが信頼する証明書に基づく有効なアイデンティティを示す必要があります (Keeperの署名、または `AlternativeSignatures` に登録したサムプリントに一致する署名)。`Admin` 認可レベルでは有効な証明書と管理者権限が必要で、KEPMによる起動は不要です。 |
| **MQTTブローカーへのアクセス** | KEPMによって起動され、有効な証明書アイデンティティを提示するプロセスだけが、組み込みMQTTブローカーに接続できます。任意のアプリケーションは接続できません。                                                                                                                   |

これにより、同じマシン上で悪意のあるアプリケーションが動いていても、KEPMが信頼するサムプリントで署名されていない限り、KEPMエージェントとやり取りできません。

***

### トラブルシュート

#### 証明書エラーでプラグインが起動しない

**症状:** プラグインが起動しない。ログに証明書関連のエラーが出る。

**手順:**

1. プラグインの実行ファイルがデジタル署名されているか確認します。Windowsでは `Get-AuthenticodeSignature "plugin.exe"` を実行します。
2. 証明書のサムプリントが `AlternativeSignatures` のいずれかと一致するか確認します (Keeperの証明書で署名されていないプラグインの場合)。
3. 証明書自体が有効か (期限切れでない、失効していないか) を確認します。
4. 構成を変更したあとはサービスを再起動します。

#### カスタムツールがHTTP APIから401 / 403を受け取る

**症状:** カスタムの実行ファイルやスクリプトがローカル管理APIを呼び出すと認可エラーになる。

**手順:**

1. 実行ファイルがコード署名証明書でデジタル署名されているか確認します。
2. 証明書のサムプリントが正しい形式 (スペースなし、大文字) で `Settings:AlternativeSignatures` に含まれているか確認します。
3. サムプリントを追加したあとサービスを再起動したか確認します。
4. 証明書が期限切れでないか確認します。

#### クライアントがHTTPSエンドポイントに接続できない

**症状:** ブラウザ、スクリプト、またはツールが `https://localhost:6889/...` を呼び出すと証明書エラーになる。

**手順:**

1. 既定の自己署名証明書を使っている場合: クライアントで `localhost` の自己署名証明書を受け入れるよう構成します。これは想定どおりの挙動です。
2. カスタム証明書を使っている場合: 構成されたパスに証明書ファイルがあり、サービスから読み取れるか確認します。
3. 起動時の証明書生成または読み込みエラーがサービスログにないか確認します。

#### 起動時に証明書が見つからない

**症状:** 証明書関連のエラーでサービスが起動に失敗する。

**手順:**

1. `CertPath` のパスが正しく、ファイルが存在するか確認します。
2. ファイルのアクセス権を確認します。KEPMのサービスアカウントが証明書ファイルを読める必要があります。
3. Windowsでストアを使う場合、`CertName` の証明書名が完全一致しているか確認します。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/jp/endpoint-privilege-manager/reference/signed-certificate-support.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.