SPIFFE Workload API

Ghostunnel can obtain certificates and trusted roots from the SPIFFE Workload API. With the Workload API, Ghostunnel maintains up-to-date, frequently rotated client/server identities (X.509 certificates and private keys) and trusted X.509 roots. Peers are expected to present SPIFFE X509-SVIDs, which are verified using SPIFFE authentication.

To enable workload API support, use the --use-workload-api flag. By default, the location of the SPIFFE Workload API socket is picked up from the SPIFFE_ENDPOINT_SOCKET environment variable. If you prefer to specify this via flag, the --use-workload-api-addr flag can be used to explicitly set the address.

On UNIX systems (Linux, macOS):

ghostunnel server \
    --use-workload-api-addr unix:///run/spire/sockets/agent.sock \
    --listen localhost:8443 \
    --target localhost:8080 \
    --allow-uri spiffe://domain.test/frontend

On Windows:

ghostunnel server \
    --use-workload-api-addr npipe:spire-agent\\public\\api \
    --listen localhost:8443 \
    --target localhost:8080 \
    --allow-uri spiffe://domain.test/frontend

Authorization

The identity of the peer, i.e. the SPIFFE ID, is embedded as a URI SAN on the X509-SVID. Accordingly, the existing --verify-uri and --allow-uri flags can be used to authorize the peer:

As a server:

ghostunnel server \
    --use-workload-api \
    --listen localhost:8443 \
    --target localhost:8080 \
    --allow-uri spiffe://domain.test/frontend

As a client:

ghostunnel client \
    --use-workload-api \
    --listen localhost:8080 \
    --target localhost:8443 \
    --verify-uri spiffe://domain.test/backend

Trust Bundle Updates

When using the Workload API, Ghostunnel automatically watches for updates to both the X.509 identity (certificate and key) and the trusted root CA bundle. When the SPIFFE provider (e.g. SPIRE) rotates certificates or updates the trust bundle, Ghostunnel picks up the changes without requiring a manual reload or restart.

Demo

See the end-to-end demo for an example using Ghostunnel with SPIFFE Workload API support backed by SPIRE. The SPIRE getting started guide covers setting up SPIRE from scratch on Linux/macOS.