Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

TLS and mutual TLS

The credential verifier serves every endpoint over TLS. A relying-party endpoint additionally requires a client certificate. This page documents the TLS parameters, the certificate formats, the client identifier, and the authentication flow.

TLS parameters

The [tls_params] table configures the TLS listener.

KeyTypeRequiredDefaultDescription
server_private_keystringYes—Server private key in PKCS#8 PEM format.
server_certificatestringYes—Server X.509 certificate in PEM format.
server_ca_chainstringYes—CA chain in PEM format.
client_ca_cert_chainstringNoserver_ca_chainCA chain that validates client certificates.
tls_cipher_suitesstringNoMozilla intermediate v5Colon-separated list of TLS cipher suites to enable.
[tls_params]
server_private_key   = "certs/server.key.pem"
server_certificate   = "certs/server.cert.pem"
server_ca_chain      = "certs/ca.chain.pem"
client_ca_cert_chain = "certs/client-ca.pem"

All paths are relative to the configuration file directory. See Configuration for the path resolution rule.

Protocol versions and cipher suites

When tls_cipher_suites is omitted, the server builds the listener from the Mozilla intermediate v5 profile and allows TLS 1.2 through TLS 1.3.

When tls_cipher_suites is set, the server builds the listener from the Mozilla modern v5 profile and applies the given list. The server splits the list into TLS 1.3 suites and TLS 1.2 suites.

List contentMinimum protocol version
TLS 1.3 suites onlyTLS 1.3
TLS 1.2 suites onlyTLS 1.2
Both groupsTLS 1.2

The TLS 1.3 suites that the server recognizes are TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, and TLS_AES_128_CCM_8_SHA256.

Certificate formats

MaterialEncodingExpected header
Private keyPKCS#8 PEM-----BEGIN PRIVATE KEY-----
CertificateX.509 PEM-----BEGIN CERTIFICATE-----
CA chainConcatenated X.509 PEMOne -----BEGIN CERTIFICATE----- block per certificate, root last.

The server loads the server private key with PKey::private_key_from_pem, the server certificate with X509::from_pem, and each CA chain with X509::stack_from_pem. A file that fails to parse stops the server at startup with a configuration error.

Mutual TLS

The server always configures client certificate verification. The server builds an X.509 trust store from the client_ca_cert_chain file. When client_ca_cert_chain is absent, the server uses server_ca_chain.

The server sets the OpenSSL verify mode to PEER. In this mode the server requests a client certificate during the TLS handshake and verifies the certificate when the client presents one. The handshake still completes when the client presents no certificate. The credential verifier then enforces authentication at the application layer, so an unauthenticated request to a relying-party endpoint receives status 401.

Relying-party authentication

The server authenticates a relying party with the Common Name (CN) of the client certificate. The table below describes the authentication stages.

OrderStageAction
1TLS handshakeVerify the client certificate chain against the client CA trust store.
2Connection setupStore the peer certificate on the connection.
3SslAuthRead the CN of the peer certificate and treat the CN as the username.
4EnsureAuthRequire an authenticated username on a relying-party endpoint.
5HandlerRead the username from the request context.

The table below lists the outcomes.

ConditionResult
Valid client certificateRequest proceeds with the username set to the certificate CN.
No client certificate on a relying-party endpointStatus 401, unless disable_authentication is true.
Certificate not signed by a CA in the trust storeThe TLS handshake fails.
CN ends with *Status 401. Wildcard usernames are rejected.
Certificate has no CNStatus 401.
CN is not valid UTF-8Status 401.

Client certificates must meet these requirements:

  • The certificate is signed by a CA in the client CA trust store.
  • The Subject field contains a Common Name.
  • The certificate is within its validity period.

The CN is any UTF-8 string. The server recommends a value such as ewqwe-client-01.

Test client certificate

The included test client certificate has the Subject CN=user1.acme.com and the Issuer CN=acme.com. Use it to send a request to a relying-party endpoint during development.

The x509_san_dns client identifier

For the HAIP profile, the server builds the client_id value as x509_san_dns:<san_dns_name>. The server reads san_dns_name from the DNS subject alternative name (SAN) of the leaf certificate in openid4vp_config.haip_config.x509_cert_path. The same client_id value appears in the signed authorization request.

The wallet checks that the host part of the client_id matches the DNS SAN of the server certificate. The server certificate must therefore carry the DNS name that the wallet uses to reach the server.

The included test TLS certificate has these SAN entries: DNS:demo.ewqwe.local, DNS:localhost, and IP:127.0.0.1. With this certificate the server builds the client identifier x509_san_dns:demo.ewqwe.local.

Test certificates

Warning

Never use the test certificates in production.

The test certificates are in the certificates/ directory at the repository root.

TLS certificates

The TLS certificates are in certificates/tls/.

FilePurpose
ewqwe.server.cert.pemServer TLS certificate. CN ewqwe.acme.com.
ewqwe.server.key.pemServer TLS private key.
ewqwe.server.fullchain.pemServer leaf certificate and CA chain, used for the JAR x5c header.
ewqwe.ca.pemCA chain. The tests also use it as the client CA chain.
ewqwe.root.key.pemRoot CA private key.
ewqwe.user1.cert.pemClient certificate for mutual TLS. CN user1.acme.com.
ewqwe.user1.key.pemClient private key that matches ewqwe.user1.cert.pem.
ewqwe.user2.cert.pemA second client certificate.

The server certificate carries the SAN entries DNS:demo.ewqwe.local, DNS:localhost, and IP:127.0.0.1.

Attestation signing certificates

The attestation signing certificates are in certificates/signer/.

FilePurpose
ewqwe.signer.leaf.cert.pemAttestation issuer certificate. CN ewqwe.acme.com.
ewqwe.signer.leaf.key.pemAttestation issuer private key.
ewqwe.signer.leaf.fullchain.pemAttestation issuer certificate and CA chain.
ewqwe.signer.ca.pemAttestation issuer CA certificate.
ewqwe.signer.ca.key.pemAttestation issuer CA private key.

Credential issuer CA certificates

The trusted credential issuer CA certificates are in certificates/issuers_cas/. The directory holds the age-verification issuer CA, the EU PID issuer CA, and public root CAs such as dc4eu.pem, isrg_root_x1.pem, and isrg_root_x2.pem.

Disabling authentication

The disable_authentication key turns off the client certificate requirement. When the value is true, the EnsureAuth middleware inserts disabled_authentication_user as the authenticated username on every request that has no certificate. The default username is test.

Warning

The disable_authentication = true setting removes authentication from every relying-party endpoint. Use it only for local development and tests.