Signed Certificate Support

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

# 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

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

{
  "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

{
  "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.