Skip to main content
Version: v4

certificate-management

id: certificate-management title: Certificate Management​

Certificate Management

This page covers certificate management for Harper's external-facing HTTP and Operations APIs. For replication certificate management, see [TODO:reference_versioned_docs/version-v4/replication/clustering.md 'Replication clustering and certificate management'].

Default Behavior​

On first run, Harper automatically generates self-signed TLS certificates at <ROOTPATH>/keys/:

  • certificate.pem — The server certificate
  • privateKey.pem — The server private key
  • ca.pem — A self-signed Certificate Authority

These certificates do not have a valid Common Name (CN) for your Harper node. HTTPS can be used with them, but clients must be configured to accept the invalid certificate.

Development Setup​

By default, HTTPS is disabled. HTTP is suitable for local development and trusted private networks. If you are developing on a remote server with requests traversing the Internet, enable HTTPS.

To enable HTTPS, set http.securePort in harperdb-config.yaml and restart Harper:

http:
  securePort: 9926

Harper will use the auto-generated certificates from <ROOTPATH>/keys/.

Production Setup​

For production, use certificates from your own CA or a public CA such as Let's Encrypt, with CNs that match the Fully Qualified Domain Name (FQDN) of your Harper node.

Option 1: Replace Harper Certificates​

Enable HTTPS and replace the certificate files:

http:
  securePort: 9926
tls:
  certificate: ~/hdb/keys/certificate.pem
  privateKey: ~/hdb/keys/privateKey.pem

Either replace the files at <ROOTPATH>/keys/ in place, or update tls.certificate and tls.privateKey to point to your new files and restart Harper.

The operationsApi.tls section is optional. If not set, Harper uses the values from the top-level tls section. You can specify different certificates for the Operations API:

operationsApi:
  tls:
    certificate: ~/hdb/keys/certificate.pem
    privateKey: ~/hdb/keys/privateKey.pem

Option 2: Nginx Reverse Proxy​

Instead of enabling HTTPS directly on Harper, use Nginx as a reverse proxy. Configure Nginx to handle HTTPS with certificates from your own CA or a public CA (e.g. via Certbot for Let's Encrypt), then forward HTTP requests to Harper.

This approach keeps Harper's HTTP interface internal while Nginx handles TLS termination.

Option 3: External Reverse Proxy / Load Balancer​

External services such as an AWS Application Load Balancer or GCP HTTPS load balancer can act as TLS-terminating reverse proxies. Configure the service to accept HTTPS connections and forward over a private network to Harper as HTTP.

These services typically include integrated certificate management.

mTLS Setup​

Mutual TLS (mTLS) requires both client and server to present certificates. To enable mTLS, provide a CA certificate that Harper will use to verify client certificates:

http:
  mtls:
    required: true
tls:
  certificateAuthority: ~/hdb/keys/ca.pem

For full mTLS authentication details, see mTLS Authentication.

Certificate Revocation Checking​

Added in: v4.5.0 (certificate revocation); v4.7.0 (OCSP support)

When using mTLS, enable certificate revocation checking to ensure revoked certificates cannot authenticate even if still within their validity period:

http:
  mtls:
    required: true
    certificateVerification: true

Harper supports two industry-standard methods:

CRL (Certificate Revocation List)

  • Downloaded and cached locally (24 hours by default)
  • Fast verification after first download (no network requests)
  • Best for high-volume verification and offline scenarios

OCSP (Online Certificate Status Protocol)

  • Real-time query to the CA's OCSP responder
  • Best for certificates without CRL distribution points
  • Responses cached (1 hour by default)

Harper's approach: CRL-first with OCSP fallback

  1. Checks CRL if available (fast, cached locally)
  2. Falls back to OCSP if CRL is unavailable or fails
  3. Applies the configured failure mode if both methods fail

For full configuration options and troubleshooting, see Certificate Verification.

Dynamic Certificate Management​

Added in: v4.4.0 (confirmed via release notes)

Certificates — including CAs and private keys — can be dynamically managed without restarting Harper.

Multiple Certificate Authorities​

It is possible to use different certificates for the Operations API and the HTTP (custom application) API. For example, in scenarios where only your application endpoints need to be exposed to the Internet and the Operations API is reserved for administration, you may use a private CA for the Operations API and a public CA for your application certificates.

Configure each separately:

# Top-level tls: used by HTTP/application endpoints
tls:
  certificate: ~/hdb/keys/app-certificate.pem
  privateKey: ~/hdb/keys/app-privateKey.pem

# Operations API can use a separate cert
operationsApi:
  tls:
    certificate: ~/hdb/keys/ops-certificate.pem
    privateKey: ~/hdb/keys/ops-privateKey.pem

Renewing Certificates​

The harper renew-certs CLI command renews the auto-generated Harper certificates. See CLI Commands for details.

Changes to TLS settings require a restart, except where dynamic certificate management is used.