# Signed Certificate Support

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FTkUXfZjHDRfJzGuQEHZQ%2Fimage.png?alt=media&#x26;token=59a85dd7-554d-49d9-9690-139e01f9bf0f" alt=""><figcaption></figcaption></figure>

**Audience:** IT administrators deploying or managing Keeper Endpoint Privilege Manager (KEPM). This page explains how KEPM uses digital certificates to secure internal communications, authenticate plugins and executables, and how to configure custom or alternative certificates for your environment.

***

### Overview

Certificates in KEPM serve two complementary purposes:

1. **Transport Security** — KEPM's internal management API (HTTPS) and its internal message broker (MQTT) are both encrypted using TLS. Certificates are the foundation of that encryption.
2. **Component Authentication** — Before a plugin, job executable, or custom tool can connect to the agent's management API or message bus, KEPM validates that the executable is digitally signed by a trusted certificate. This prevents unauthorized code from interacting with privileged services.

Both of these mechanisms are active by default and require no initial configuration for most deployments.

***

### Default Certificate Behavior

#### Automatic Self-Signed Certificate Generation

At startup, KeeperPrivilegeManager automatically generates a **self-signed X.509 certificate** if no custom certificate is configured. This certificate is used for:

* The **HTTPS management API** (default port `6889`)
* The **MQTT message broker** (default port `8675`)

**Default certificate properties:**

| Property  | Value                                           |
| --------- | ----------------------------------------------- |
| Subject   | Localhost                                       |
| Key Usage | Server Authentication (OID `1.3.6.1.5.5.7.3.1`) |
| Binding   | Localhost / `127.0.0.1` only                    |
| Storage   | In-memory (regenerated on each service restart) |
| Validity  | Long-term                                       |

Because all communication is bound to `localhost` only, self-signed certificates are appropriate and secure for this use case. The agent's API and message bus are not exposed to the network.

> **Note:** Because the certificate is regenerated on each restart, clients that pin the certificate (e.g., custom scripts or monitoring tools) will need to re-trust it after service restarts. For environments that require a stable, pinned certificate, see Custom Certificates below.

***

### Plugin & Executable Certificate Validation

#### How KEPM Validates Components

Every plugin and executable that communicates with KEPM's management API or message bus must be **digitally signed** by a certificate that KEPM trusts. This is a core security control: it ensures that only Keeper-issued or explicitly approved code can interact with the privileged agent.

**The validation process (per component):**

1. KEPM extracts the digital signature from the plugin or executable.
2. It compares the certificate thumbprint against its list of trusted certificates.
3. If the thumbprint matches, the component is permitted to connect.
4. If no match is found, the connection is rejected and an error is logged.

**Trusted certificate sources:**

| Source                             | Description                                                                                                                       |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| KeeperPrivilegeManager certificate | Extracted automatically from the service executable itself. All Keeper-signed plugins are trusted by default.                     |
| Alternative certificates           | Thumbprints you add to `Settings:AlternativeSignatures` in `appsettings.json` for your own tools or enterprise-signed components. |

***

### Alternative Signatures

The `AlternativeSignatures` setting allows you to register additional trusted certificate thumbprints. This is used when:

* You have **custom tools** (e.g., automation scripts packaged as executables) that need to communicate with KEPM.
* You deploy KEPM components that are **re-signed** by your own enterprise code-signing certificate.
* You are developing or testing custom plugins or job executables.

#### Configuring Alternative Signatures

**Step 1: Obtain the certificate thumbprint.**

On **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
```

On **Linux / macOS**:

bash

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

> **Format:** Remove all spaces and colons from the thumbprint before adding it to configuration. Use uppercase for readability (the system is case-insensitive). Example: `A1B2C3D4E5F6789012345678901234567890ABCD`

**Step 2: Add the thumbprint to `appsettings.json`.**

json

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

**Step 3: Restart the KeeperPrivilegeManager service** to apply the change.

> **Important:** A service restart is required after any modification to `appsettings.json`.

#### Security Best Practices for Alternative Signatures

* **Keep the list minimal.** Only add thumbprints for certificates you explicitly trust. Each entry expands the set of code that can interact with privileged services.
* **Document your entries.** Note which certificate belongs to which tool and who issued it.
* **Review periodically.** Remove certificates that are no longer needed or have expired.
* **Never store certificate passwords in configuration files.** Use the Windows Certificate Store or a secure credential manager instead.

***

### Custom Certificates

> **Note:** Full custom certificate configuration for HTTPS and MQTT endpoints is planned for future KEPM versions. The following describes the expected configuration model.

When custom certificate support becomes available, you will be able to configure a specific certificate for the management API and MQTT broker rather than using the auto-generated self-signed certificate. This is intended for environments that require a stable, CA-issued, or internally managed certificate.

**Expected configuration in `appsettings.json`:**

json

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

| Setting        | Description                                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CertPath`     | Path to a `.pfx` (Windows) or `.pem` (Linux/macOS) certificate file.                                                                                  |
| `CertPassword` | Password for the certificate file. **Do not store this in plain text in production.** Use the Windows Certificate Store or a secrets manager instead. |
| `CertStore`    | Windows certificate store location: `My` (Personal), `Root` (Trusted Root), or `Trust` (Trusted Publishers).                                          |
| `CertName`     | Friendly name of the certificate in the Windows store.                                                                                                |

**Supported certificate formats:**

* `.pfx` / PKCS#12 — Windows
* `.pem` — Linux and macOS
* Windows Certificate Store — Windows (via `CertStore` + `CertName`)

***

### Certificate Renewal

#### Self-Signed Certificates (Default)

No manual action is required. KEPM regenerates the self-signed certificate automatically each time the service starts. There is no expiration concern in normal operation.

#### Custom Certificates

When using a custom certificate, manage renewals according to your organization's certificate lifecycle process:

1. Obtain the renewed certificate from your Certificate Authority (CA).
2. Install it (to the certificate file path or Windows store as appropriate).
3. Update `appsettings.json` if the path, name, or thumbprint has changed.
4. Restart the KeeperPrivilegeManager service.
5. If the thumbprint changed, update `AlternativeSignatures` in `appsettings.json` for any tools or plugins that relied on the old certificate.
6. Validate that plugins start successfully and that any custom tools can still connect.

> **Best Practice:** Renew certificates before they expire and test the renewal process in a non-production environment first.

***

### How Certificates Interact with the KEPM Security Model

Certificate validation is one layer within KEPM's broader defense-in-depth approach:

| Layer                     | Certificate's Role                                                                                                                                                                                                                                                                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transport encryption**  | TLS certificates encrypt HTTPS (port `6889`) and MQTT (port `8675`) traffic between the service and its components. All traffic stays on `localhost`.                                                                                                                                                                                              |
| **Plugin authentication** | Plugins loaded from `Plugins/*.json` must be signed by a trusted certificate. The service validates each plugin's signature before starting it.                                                                                                                                                                                                    |
| **API authorization**     | Callers of the management API at the `Plugin` authorization level must present a valid certificate (signed by KEPM or an alternative trusted certificate) in addition to being launched by KEPM. The `Admin` authorization level requires a valid certificate and admin privileges; it does not require the process to have been launched by KEPM. |
| **MQTT broker access**    | Only processes launched by KEPM that present a valid certificate identity are permitted to connect to the embedded MQTT broker. Arbitrary applications cannot connect.                                                                                                                                                                             |

This means that even if a malicious application is running on the same machine, it cannot interact with the KEPM agent unless it carries a certificate thumbprint that you have explicitly trusted.

***

### Troubleshooting

#### Plugins Fail to Start with Certificate Errors

**Symptoms:** A plugin does not start; certificate-related errors appear in the log.

**Steps:**

1. Verify the plugin executable is digitally signed. On Windows: `Get-AuthenticodeSignature "plugin.exe"`.
2. Confirm the certificate thumbprint matches an entry in `AlternativeSignatures` (if the plugin is not signed by Keeper's certificate).
3. Check that the certificate itself is valid (not expired, not revoked).
4. Restart the service after any configuration changes.

#### Custom Tools Receive 401 / 403 from the HTTP API

**Symptoms:** A custom executable or script gets an authorization error when calling the local management API.

**Steps:**

1. Verify the executable is digitally signed with a code-signing certificate.
2. Confirm the certificate thumbprint is correctly formatted (no spaces, uppercase) and present in `Settings:AlternativeSignatures`.
3. Confirm you restarted the service after adding the thumbprint.
4. Check that the certificate has not expired.

#### Clients Cannot Connect to HTTPS Endpoints

**Symptoms:** Browsers, scripts, or tools that call `https://localhost:6889/...` report a certificate error.

**Steps:**

1. If using the default self-signed certificate: configure your client to accept the self-signed certificate for `localhost`. This is expected behavior.
2. If using a custom certificate: verify the certificate file exists at the configured path and is accessible by the service.
3. Check service logs for certificate generation or load errors at startup.

#### Certificate Not Found at Startup

**Symptoms:** The service fails to start with a certificate-related error.

**Steps:**

1. Verify the path in `CertPath` is correct and the file exists.
2. Check file permissions — the KEPM service account must be able to read the certificate file.
3. On Windows, if using the certificate store, confirm the certificate name in `CertName` matches exactly.
