Docs Require client certificates

Require client certificates

Make a CA and client certificates, make the REST API and MCP over HTTP refuse a client without one, and read why sipnab refused a handshake.

On this page

The REST API (--api) and MCP over HTTP (--mcp-transport http) can ask each client for a TLS certificate issued by your own certificate authority (CA), and refuse the handshake of a client that has none. This is mutual TLS: the client checks the server’s certificate, and the server checks the client’s.

Use it when a bearer token alone is not enough to let a client in: a fleet member that pushes to a central server, a write path, or a port that hosts outside this one can reach. A stolen token is then useless without the client’s private key, and a stolen client key is useless without a token.

On this page:

What a client certificate does and does not do

  • It decides who may connect. With required, a client that sends no certificate, or one the CA did not issue, does not complete the TLS handshake and never reaches a route.
  • It does not replace the token. Every request still needs the bearer token, and the token’s scope still decides what the request may do. A good certificate without a token gets 401, as before.
  • It names the client in the log. sipnab logs each verified client when it connects, by subject and by its DNS and URI names. The MCP audit record names it too, after the token (client-cert=).
  • rustls checks it. The certificate must chain to a CA in your client CA file, be inside its validity period, and, when it lists extended key usages, list client authentication.
  • A client sends its intermediates. A client whose certificate an intermediate CA issued must send that intermediate with its certificate, or sipnab refuses it: sipnab fetches nothing. Every certificate in the client CA file is a trust anchor, so a file that holds only an intermediate admits that intermediate’s clients, and a file may hold several CA certificates.
  • Revocation lists are not read. To shut out one client before its certificate expires, revoke its token (--api-revoked-file, --mcp-revoked-file; see Revocation). Issue client certificates with a short lifetime, so a lost key stops working on its own.

The three modes, set with --api-tls-client-auth and --mcp-tls-client-auth:

ModeA client with no certificateA client with a bad certificate
off (the default without a client CA)servedserved: sipnab asks for no certificate
optionalserved, with no client namedrefused
required (the default with a client CA)refusedrefused

Before you start

  • The listener already serves HTTPS with its own certificate (--api-tls-cert / --api-tls-key, or --mcp-tls-cert / --mcp-tls-key). See API TLS, MCP TLS and Make a certificate. The examples below use the server name capture01.example.net, port 8443, and the server’s CA in ca.pem.
  • The listener has a token configured (--api-key, --api-signing-key-file, --mcp-token-file or --mcp-signing-key-file). Client certificates add to the token; they do not stand in for it.
  • openssl on the machine where you make the CA, and curl on a client to check the result.
  • Changes on other systems: each client needs its certificate and key, and a way to present them. curl does (--cert, --key). For an MCP client that cannot, see An MCP client without a certificate setting. No firewall change: the port is the one the listener already serves.

Make a CA for client certificates

Keep this CA separate from the one that issued the server’s certificate. The client CA file is the whole trust store for client certificates: sipnab does not add the host’s CA bundle, so it refuses a certificate from a public CA.

openssl req -x509 -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout clients-ca.key -out clients-ca.pem -days 3650 \
  -subj "/O=Example Fleet/CN=Example Fleet client CA" \
  -addext "basicConstraints=critical,CA:TRUE,pathlen:0" \
  -addext "keyUsage=critical,keyCertSign,cRLSign"

Then make its key readable by you only:

chmod 600 clients-ca.key

clients-ca.key signs client certificates: keep it off the sipnab host. clients-ca.pem is public and goes to the sipnab host.

Issue a client certificate

One certificate per client. Put the name sipnab should log in the subject alternative names: a URI (a SPIFFE ID works) and a DNS name.

  1. Make the client’s key and a certificate request:

    openssl req -new -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
      -keyout member-1.key -out member-1.csr -subj "/O=Example Fleet/CN=member-1"
    
  2. Write the certificate’s extensions to a file named member-1.ext:

    basicConstraints=critical,CA:FALSE
    keyUsage=critical,digitalSignature
    extendedKeyUsage=clientAuth
    subjectAltName=DNS:member-1.fleet.example.com,URI:spiffe://fleet.example.com/member/1
    
  3. Sign it with the client CA:

    openssl x509 -req -in member-1.csr -CA clients-ca.pem -CAkey clients-ca.key \
      -CAcreateserial -out member-1.pem -days 365 -extfile member-1.ext
    
  4. Make the client’s key readable by its owner only:

    chmod 600 member-1.key
    

Check it before you hand it out:

openssl verify -CAfile clients-ca.pem -purpose sslclient member-1.pem

It prints:

member-1.pem: OK

Then print the subject. This is the subject exactly as sipnab writes it in its log:

openssl x509 -in member-1.pem -noout -subject -nameopt RFC2253

It prints:

subject=CN=member-1,O=Example Fleet

Configure sipnab

Copy clients-ca.pem to the sipnab host, for example to /etc/sipnab/clients-ca.pem. It holds no secret. Any user may read it, but no other user may write it (chmod 644, owned by root): whoever can write the file chooses which clients get in, and sipnab refuses a file every user can write.

Add the client CA to the REST API’s HTTPS flags. A CA alone means required:

sudo sipnab -N -d eth0 --user sipnab --api 0.0.0.0:8443 \
  --api-signing-key-file /etc/sipnab/signing.key \
  --api-allowed-host capture01.example.net \
  --api-tls-cert /etc/sipnab/api.pem --api-tls-key /etc/sipnab/api.key \
  --api-tls-client-ca /etc/sipnab/clients-ca.pem

For MCP over HTTP, the same with the MCP flags:

sudo sipnab -N -d eth0 --user sipnab --mcp --mcp-transport http --mcp-bind 0.0.0.0:8731 \
  --mcp-token-file /etc/sipnab/mcp.token \
  --mcp-allowed-host capture01.example.net \
  --mcp-tls-cert /etc/sipnab/mcp.pem --mcp-tls-key /etc/sipnab/mcp.key \
  --mcp-tls-client-ca /etc/sipnab/clients-ca.pem

The two listeners take their own CA. Point both at one file to share it.

To roll client certificates out without cutting off clients that have none yet, start with --api-tls-client-auth optional. sipnab then verifies a certificate when a client sends one, logs who it is, and still serves a client that sends none. Switch to required (or drop the flag) once every client has its certificate.

The same settings in sipnab.toml:

[api]
tls_cert = "/etc/sipnab/api.pem"
tls_key = "/etc/sipnab/api.key"
tls_client_ca = "/etc/sipnab/clients-ca.pem"
tls_client_auth = "required"

[mcp]
tls_cert = "/etc/sipnab/mcp.pem"
tls_key = "/etc/sipnab/mcp.key"
tls_client_ca = "/etc/sipnab/clients-ca.pem"

Each flag replaces its own key. A root run reads the client CA file before it drops to --user, as it reads the server’s certificate and key.

At startup sipnab logs that it asks for certificates:

INFO sipnab::tls_listener: API TLS asks clients for a certificate (required)

Configure a client

curl

Give curl the server’s CA, the client’s certificate and key, and the token:

curl --cacert ca.pem --cert member-1.pem --key member-1.key \
  -H "Authorization: Bearer $TOKEN" https://capture01.example.net:8443/v1/stats

Another HTTP client

Any client that can present a TLS client certificate works: give it member-1.pem and member-1.key, and keep sending the Authorization: Bearer header. Python’s requests, for example, takes cert=("member-1.pem", "member-1.key") and verify="ca.pem". That example is from the requests documentation and was not run for this page.

An MCP client without a certificate setting

An MCP client that has no setting for a client certificate cannot connect to a listener with required. Run a local bridge beside it that adds the certificate: the client talks plain HTTP to a loopback port, and the bridge talks HTTPS with the certificate to sipnab. With socat:

socat TCP-LISTEN:18732,bind=127.0.0.1,reuseaddr,fork \
  OPENSSL:capture01.example.net:8731,cafile=ca.pem,cert=member-1.pem,key=member-1.key

Configure the MCP client with http://127.0.0.1:18732/mcp and its token as before. sipnab answers the loopback Host name the client sends by default. Keep the bridge on 127.0.0.1: anyone who can reach its port gets the certificate’s identity, though they still need the token. socat prints W OpenSSL: Warning: this implementation does not check CRLs on each connection. It means socat reads no revocation lists, and sipnab reads none either.

Require member certificates on a fleet center

sipnab fleet serve serves through the REST API’s listener, and takes the same settings as --tls-client-ca and --tls-client-auth. Issue each member a certificate as in Issue a client certificate, then:

sipnab fleet serve --listen 192.0.2.10:8444 --store /var/lib/sipnab/center.store \
  --store-key-file /etc/sipnab/center.storekey \
  --signing-key-file /etc/sipnab/center.signing \
  --tls-cert /etc/sipnab/center.crt --tls-key /etc/sipnab/center.key \
  --tls-client-ca /etc/sipnab/members-ca.pem

A member then posts its heartbeat with its certificate and its fleet-report token:

curl --cacert ca.pem --cert edge-a.pem --key edge-a.key \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/x-ndjson" \
  --data-binary @heartbeat.ndjson https://center.example.net:8444/v1/fleet/ingest

The token’s id is still the member’s name the center records. The center logs the verified certificate of each connection, so you can compare the two. A center refuses a heartbeat without a certificate at the handshake, as in Troubleshooting. sipnab fleet serve names the settings it refuses with its own flags (--tls-client-ca, --tls-client-auth, --tls-cert, --tls-key). The center’s refusal of a member without a certificate, and its acceptance of one with, are what tests/fleet_center_test.rs checks. Nobody ran the commands above as written.

Check that it works

Run each of these from the client. With the certificate and the token, sipnab serves the request:

curl --cacert ca.pem --cert member-1.pem --key member-1.key \
  -H "Authorization: Bearer $TOKEN" https://capture01.example.net:8443/health

It prints:

ok

The certificate without the token is still refused, with 401:

curl -s -o /dev/null -w '%{http_code}\n' --cacert ca.pem --cert member-1.pem \
  --key member-1.key https://capture01.example.net:8443/v1/stats

It prints:

401

The token without a certificate does not complete the handshake:

curl --cacert ca.pem -H "Authorization: Bearer $TOKEN" https://capture01.example.net:8443/v1/stats

It prints:

curl: (56) OpenSSL SSL_read: OpenSSL/3.0.13: error:0A00045C:SSL routines::tlsv13 alert certificate required, errno 0

sipnab’s log names the client it served and the one it refused:

INFO sipnab::tls_listener: API TLS: 192.0.2.10:54202 presented a verified client certificate: subject="CN=member-1,O=Example Fleet" dns=["member-1.fleet.example.com"] uri=["spiffe://fleet.example.com/member/1"]
WARN sipnab::tls_listener: API TLS: refused the TLS handshake with 192.0.2.10:54238: client certificate: peer sent no certificates

For MCP, the audit line of a tool call, and its record in --mcp-audit-file, carry the client after the token: its first URI name, else its first DNS name, else its subject, percent-encoded. This call used a token minted with --token-id member-1:

INFO serve_inner: mcp_audit: tool=server_capabilities id=2 caller="192.0.2.10:54436 bearer-verified scope=full token=member-1 client-cert=spiffe:%2F%2Ffleet.example.com%2Fmember%2F1" outcome=ok elapsed_ms=0 args={}

Troubleshooting

The commands and outputs on this page ran on 2026-11-07 against sipnab built from this change, OpenSSL 3.0.13 and curl 8.5.0. The test ran on loopback, and this page writes the client address as 192.0.2.10.

sipnab refuses the client at the handshake

The client sees the refusal as a TLS alert, and sipnab logs the reason at warn. Each pair below is one cause:

CauseWhat curl printsWhat sipnab logs after client certificate:
No certificate senttlsv13 alert certificate requiredpeer sent no certificates
Issued by another CAtlsv1 alert unknown cainvalid peer certificate: UnknownIssuer
Expiredsslv3 alert certificate expiredinvalid peer certificate: certificate expired: verification time 1794071703 (UNIX), but certificate is not valid after 1609459200 (184612503 seconds ago)
Not valid yetsslv3 alert certificate expiredinvalid peer certificate: certificate not valid yet: verification time {now} (UNIX), but certificate is not valid before {not_before} ({seconds} seconds in future)
Made for a server: extended key usage serverAuth onlysslv3 alert unsupported certificateinvalid peer certificate: certificate does not allow extended key usage for client authentication, allows server authentication

Each log line starts API TLS: refused the TLS handshake with <address>: (or MCP TLS:). In the not-yet-valid row, {now} and {not_before} are UNIX times and {seconds} the difference between them. That row quotes the rustls 0.23.46 source and checked by sipnab’s tests: OpenSSL 3.0 cannot issue such a certificate for a live run.

  • No certificate sent: give the client --cert and --key, or use optional while you roll certificates out.
  • Another CA: the certificate was not issued by a CA in the client CA file. Check it with openssl verify -CAfile clients-ca.pem -purpose sslclient member-1.pem.
  • Expired, or not valid yet: check the dates with openssl x509 -in member-1.pem -noout -dates and the clock of both hosts. Issue a new certificate.
  • Made for a server: issue the certificate with extendedKeyUsage=clientAuth.

sipnab serves the client, but it gets 401

The handshake succeeded, and the token is missing or wrong. A client certificate never replaces the token. See Bearer-token authentication.

sipnab does not start

Each of these stops the run before anything listens, with exit status 2 for a flag (1 when only the config file set it). Each flag name in the messages has its config key after it:

--api-tls-client-ca (or [api] tls_client_ca) clients-ca.pem needs --api-tls-cert (or [api] tls_cert) and --api-tls-key (or [api] tls_key): a client certificate is asked for only in a TLS handshake
--api-tls-client-auth (or [api] tls_client_auth) required needs --api-tls-client-ca (or [api] tls_client_ca): name the CA that issues the client certificates
server error: clients-ca.pem: the API TLS client CA file is writable by every user (mode 0666); chmod o-w it
  • The first: give the listener its own certificate and key, or remove the CA.
  • The second: name the client CA, or remove the mode.
  • The third: chmod o-w the CA file.
  • off with a client CA does not stop the run: off wins, so a command line can turn off what the config file asks for, and sipnab logs API TLS asks clients for no certificate: the client-auth mode is off, so the client CA clients-ca.pem is not read at warn.
  • sipnab refuses a CA file that does not exist, or holds no certificate, the same way, naming the file.

The MCP listener’s messages are the same with MCP TLS and the --mcp-tls-client-ca, --mcp-tls-client-auth, --mcp-tls-cert and --mcp-tls-key flags. With MCP on stdio, sipnab refuses the client flags with --mcp-tls-client-ca/--mcp-tls-client-auth ask MCP over HTTPS clients for a certificate and do nothing without --mcp --mcp-transport http. Every message has an entry in Errors.

Nothing names the client in the log

sipnab names a client only when it verified the client’s certificate. With optional, sipnab serves a client that sent no certificate without a name. Check for the startup line asks clients for a certificate (optional) or (required). Without it, no client CA reached the listener.