Certificate Pinning

Certificate Pinning

New in 0.15.0 — covers all four surfaces.

Most Proxmox boxes serve a self-signed certificate, signed by a per-cluster CA that no public root trusts. The usual answers are to ship that CA around or to disable TLS verification — and Proximo refuses to send a token over a channel it can't verify, so "disable TLS" isn't an option here anyway.

Fingerprint pinning is the cleaner answer: pin the box by its exact certificate.

How it works

Set the certificate's SHA-256 fingerprint (the form the Proxmox GUI shows — colon-separated is fine). Then:

• The pin replaces CA and hostname validation with an exact-certificate match.
• The match is checked on the TLS handshake itself. A mismatch closes the socket before your token or credentials are ever sent.
• A pin alone is sufficient verification for a self-signed box — no CA bundle needed.
• A garbled fingerprint refuses loudly at startup, rather than silently degrading to "no pin."

This is the same idea as proxmox-backup-client --fingerprint, applied across every surface Proximo talks to.

Set it, per surface

export PROXIMO_FINGERPRINT="AB:CD:…"        # Proxmox VE
export PROXIMO_PBS_FINGERPRINT="AB:CD:…"    # Backup Server
export PROXIMO_PMG_FINGERPRINT="AB:CD:…"    # Mail Gateway
export PROXIMO_PDM_FINGERPRINT="AB:CD:…"    # Datacenter Manager

Or, in a multi-target registry entry, set the fingerprint field. See Configuration.

Get the fingerprint

From the Proxmox web UI (it displays the cert fingerprint), or from the command line against your own server:

echo | openssl s_client -connect your-pve.example.lan:8006 2>/dev/null \
  | openssl x509 -noout -fingerprint -sha256

Honest limit

The check runs on the synchronous HTTP transport that all four backends use. It is documented as sync-only — an async client would bypass it — and no async path touches a Proxmox backend today. It's a correctly-scoped guarantee, not a universal one.

Every pin above is proven against a real self-signed Proxmox host (VE 9.2, PBS 4.2, PMG 9.1, PDM), matching pin connecting and wrong pin refusing, in addition to unit tests against a live TLS socket.