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
- Before you start
- Make a CA for client certificates
- Issue a client certificate
- Configure sipnab
- Configure a client
- Require member certificates on a fleet center
- Check that it works
- Troubleshooting
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:
| Mode | A client with no certificate | A client with a bad certificate |
|---|---|---|
off (the default without a client CA) | served | served: sipnab asks for no certificate |
optional | served, with no client named | refused |
required (the default with a client CA) | refused | refused |
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 namecapture01.example.net, port8443, and the server’s CA inca.pem. - The listener has a token configured (
--api-key,--api-signing-key-file,--mcp-token-fileor--mcp-signing-key-file). Client certificates add to the token; they do not stand in for it. opensslon the machine where you make the CA, andcurlon 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.
-
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" -
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 -
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 -
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:
| Cause | What curl prints | What sipnab logs after client certificate: |
|---|---|---|
| No certificate sent | tlsv13 alert certificate required | peer sent no certificates |
| Issued by another CA | tlsv1 alert unknown ca | invalid peer certificate: UnknownIssuer |
| Expired | sslv3 alert certificate expired | invalid peer certificate: certificate expired: verification time 1794071703 (UNIX), but certificate is not valid after 1609459200 (184612503 seconds ago) |
| Not valid yet | sslv3 alert certificate expired | invalid 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 only | sslv3 alert unsupported certificate | invalid 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
--certand--key, or useoptionalwhile 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 -datesand 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-wthe CA file. offwith a client CA does not stop the run:offwins, so a command line can turn off what the config file asks for, and sipnab logsAPI TLS asks clients for no certificate: the client-auth mode is off, so the client CA clients-ca.pem is not readat 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.