ContextQMD
Back to Libwebsockets

lws-cert-dist-client

plugins/protocol_lws_cert_dist_client/README.md

5.0.02.6 KB
Original Source

lws-cert-dist-client

This is the client-side protocol plugin for the certificate distribution system. It allows unprivileged client processes to securely request and update their TLS certificates (fullchain and private key) from a central lws-cert-dist-server.

Features

  • Securely fetches and updates TLS certificates from the distribution server.
  • Establishes discrete mTLS WebSocket links for each configured client certificate; the certificate itself identifies the domain it is managing.
  • Spawns a privileged stub process (--lws-stub=distribution-client) when running as root to manage local file system writes and UDS communication.
  • Implements a UDS (Unix Domain Socket) IPC mechanism (lws-cert-dist-stub) for secure communication between the unprivileged process and the privileged stub.
  • Atomic symlink updates when new certificates are received.

Configuration PVOs (Per-VHost Options)

NameMeaningDefault
base-dirThe base directory where certificates will be stored./etc/lwsws-pki
server-urlThe WebSocket URL of the central distribution server.wss://distribution-server.local
ca-filepathOptional. Path to the CA certificate used to verify the distribution server's certificate. Needed if the server uses a self-signed or private CA.N/A
certsA list of mTLS client certificates and keys to connect to the server. The client establishes a connection for each entry. The server deduces the domain being managed from the certificate presented.N/A

Usage

When enabled, the plugin checks if it is running as root and if certs are configured. If so, it spawns a privileged stub process to handle file system operations and sets up a UDS server. Unprivileged clients connect to this UDS server, which forwards JSON payloads received from the central distribution server.

Example lwsws Configuration

Below is an example of how to configure this plugin in an lwsws JSON config file (e.g., /etc/lwsws/conf.d/cert-dist):

json
{
  "vhosts": [{
    "name": "cert-dist-client-vhost",
    "ws-protocols": [{
      "lws-cert-dist-client": {
        "status": "ok",
        "base-dir": "/etc/lwsws-pki",
        "server-url": "wss://distribution-server.local",
        "ca-filepath": "/etc/lwsws-pki/dist-server-ca.crt",
        "certs": {
          "example-com": {
            "cert": "/etc/lwsws-pki/example.com/mtls-client.crt",
            "key": "/etc/lwsws-pki/example.com/mtls-client.key"
          },
          "test-org": {
            "cert": "/etc/lwsws-pki/test.org/mtls-client.crt",
            "key": "/etc/lwsws-pki/test.org/mtls-client.key"
          }
        }
      }
    }]
  }]
}