curl mTLS: Configure Mutual TLS from the Terminal

Mutual TLS has both client and server present certificates. With curl, use --cert, --key, and --cacert. Here is the full setup: generate certs, call an mTLS endpoint, and fix the three failures everyone hits.

One-way TLS vs mutual TLS

Regular HTTPS authenticates one side: the server proves its identity to the client, and the client stays anonymous at the TLS layer. Mutual TLS closes the loop — the client presents a certificate too, and the server validates it before any request is processed. The hero diagram above shows the exchange: both ends present a certificate, both verify the other, and only then is the connection trusted. It's the default pattern for service-to-service traffic and machine identity, where "who is calling this API" has to be answered by cryptography, not a bearer token that can leak.

The three curl flags

curl https://api.example.com/health \
  --cert   client.crt \    # the client certificate you present
  --key    client.key \    # its matching private key
  --cacert ca.crt          # the CA that signed the server's certificate

• --cert / --key — your client identity (the client-side half of mTLS).
• --cacert — the trust anchor for the server's certificate.

If the client cert and key are bundled in one PEM, --cert client.pem alone works; for a PKCS#12 bundle use --cert client.p12:password --cert-type P12.

Generate test certificates

To try mTLS locally you need a CA, a server cert, and a client cert — all chaining to that CA:

# 1. a throwaway CA
openssl genrsa -out ca.key 2048
openssl req -x509 -new -key ca.key -days 365 -out ca.crt -subj "/CN=demo-ca"

# 2. a client key + certificate signed by the CA
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/CN=test-client"
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out client.crt -days 90

Point your server at ca.crt as the client-CA trust store (in nginx: ssl_client_certificate ca.crt; ssl_verify_client on;), and the request above will succeed.

Verify it works

# a 200 means the server accepted your client certificate
curl -sw "%{http_code}\n" -o /dev/null https://api.example.com/health \
  --cert client.crt --key client.key --cacert ca.crt

The three failures everyone hits

• unable to get local issuer certificate — curl can't verify the server. Pass the server's CA with --cacert. Don't reach for -k/--insecure outside throwaway local tests; it disables verification entirely.
• 400 No required SSL certificate was sent / alert certificate required — the server wanted a client certificate and didn't get a valid one. Confirm --cert/--key are set and the client cert is signed by the CA the server trusts.
• SSL: no alternative certificate subject name matches — hostname mismatch. The name in the URL must match the server certificate's SAN. Fix the SAN or the URL; don't paper over it with --insecure.

mTLS setup checklist

• Client presents --cert + matching --key; both readable, key permissions locked down (chmod 600)
• Client trusts the server CA via --cacert — never -k/--insecure against a real endpoint
• Server has ssl_verify_client on and trusts the client CA
• Server and client certificates share (or chain to) a CA each side trusts
• Certificate SANs match the hostnames actually used
• Client certificates are short-lived and rotated — the same 47-day pressure applies to machine identities

Once the terminal call works, the same certificates drive mTLS in nginx, Envoy, and a service mesh — the handshake is identical; only the configuration surface changes.

Frequently asked