Certificate Formats

Ghostunnel supports several certificate and private key formats. The format is auto-detected from the file extension or by inspecting the first few bytes, so you don’t need to specify it explicitly.

Formats at a Glance

These options are mutually exclusive with each other and with --use-workload-api, --keychain-identity, and PKCS#11 flags.

PEM Files (Separate Cert and Key)

Pass the certificate chain and private key as two separate PEM files:

ghostunnel server \
    --cert server-chain.pem \
    --key server-key.pem \
    --listen localhost:8443 \
    --target localhost:8080 \
    --cacert cacert.pem \
    --allow-cn client

Order matters. List your server’s certificate first (the leaf), then each intermediate CA in chain order, working up toward the root. Ghostunnel sends the chain to clients in this exact order during the TLS handshake, so the client can verify a path back to a root it already trusts. The root itself is not included — the client must already have it.

# 1. Your server's certificate (the leaf / end-entity cert).
-----BEGIN CERTIFICATE-----
... your server's certificate ...
-----END CERTIFICATE-----

# 2. Intermediate CA that signed the leaf.
-----BEGIN CERTIFICATE-----
... intermediate CA certificate ...
-----END CERTIFICATE-----

# 3. (Optional) any further intermediates, each signed by the next one up.

The key file must contain a single PEM-encoded private key (RSA, ECDSA, or Ed25519).

PEM Keystore (Combined File)

A single PEM file containing both the certificate chain and private key can be passed with --keystore. The private key can appear anywhere in the file, but the leaf certificate must still come before any intermediates:

ghostunnel server \
    --keystore server-combined.pem \
    --listen localhost:8443 \
    --target localhost:8080 \
    --cacert cacert.pem \
    --allow-cn client

To create a combined PEM file:

cat server-cert.pem intermediate.pem server-key.pem > server-combined.pem

PKCS#12

PKCS#12 (.p12 / .pfx) bundles the certificate chain and private key into a single password-protected binary file. This is also the format used when importing into the macOS Keychain or Windows Certificate Store (see Keychain Support).

ghostunnel server \
    --keystore server.p12 \
    --storepass <password> \
    --listen localhost:8443 \
    --target localhost:8080 \
    --cacert cacert.pem \
    --allow-cn client

To create a PKCS#12 file from PEM files:

openssl pkcs12 -export \
    -in server-cert.pem \
    -inkey server-key.pem \
    -certfile intermediate.pem \
    -out server.p12 \
    -passout pass:<password>

See the openssl-pkcs12 man page for all options.

JCEKS

Ghostunnel can read Java keystores in JCEKS or JKS format. This is mainly useful when migrating from a Java-based TLS terminator:

ghostunnel server \
    --keystore server.jceks \
    --storepass <password> \
    --listen localhost:8443 \
    --target localhost:8080 \
    --cacert cacert.pem \
    --allow-cn client

CA Bundle

The --cacert flag accepts a PEM file containing one or more trusted CA certificates. If omitted, Ghostunnel uses the system trust store.

To build a CA bundle from individual certificates:

cat root-ca.pem intermediate-ca.pem > cacert.pem

Format Auto-Detection

Ghostunnel detects the format in this order:

1. File extension: .pem/.crt → PEM, .p12/.pfx → PKCS#12, .jceks/.jks → JCEKS.
2. Magic bytes: if the extension is ambiguous, the first bytes of the file are inspected (e.g. -----BEGIN → PEM, ASN.1 sequence → PKCS#12).

In practice, just use the right file extension and Ghostunnel will do the right thing.

Common Operations

Inspect a PEM Certificate

openssl x509 -in server-cert.pem -noout -text

Inspect a PKCS#12 File

openssl pkcs12 -in server.p12 -info -nokeys

Convert PKCS#12 to PEM

# Extract the leaf certificate
openssl pkcs12 -in server.p12 -clcerts -nokeys -out server-cert.pem

# Extract CA/intermediate certificates
openssl pkcs12 -in server.p12 -cacerts -nokeys -out ca-chain.pem

# Extract private key
openssl pkcs12 -in server.p12 -nocerts -nodes -out server-key.pem

Verify a Certificate Chain

openssl verify -CAfile cacert.pem server-cert.pem