NAME

tlshd.conf - tlshd configuration file

SYNOPSIS

/etc/tlshd/config
/etc/tlshd.conf (deprecated)

DESCRIPTION

The tlshd program implements a user agent that services TLS handshake requests on behalf of kernel TLS consumers. Its configuration file contains information that the program reads when it starts up. The file is designed to be human readable and contains a list of keywords with values that provide various types of information. The configuration file is considered a trusted source of information.

The tlshd program reads this file once when it is launched. Thus changes made in this file take effect only when the tlshd program is restarted. If this file does not exist, the tlshd program exits immediately.

OPTIONS

The configuration file is split into sections.

The [debug] section specifies debugging settings for the tlshd program. In this section, there are three available options:

loglevel

This option specifies an integer which indicates the debug message level. Zero, the quietest setting, is the default.

tls

This option specifies an integer which indicates the debug message level for TLS library calls. Zero, the quietest setting, is the default.

nl

This option specifies an integer which indicates the debug message level for netlink library calls. Zero, the quietest setting, is the default.

The [authenticate] section specifies default authentication material when establishing TLS sessions. In this section, there are four available options:

keyrings

This option specifies a semicolon-separated list of auxiliary keyrings that contain handshake authentication tokens. tlshd links these keyrings into its session keyring. The configuration file may specify either a keyring's name or serial number. tlshd always includes the .nvme keyring on its session keyring. When a handshake request names no keyring of its own, the process that performs a client handshake links the .nfs keyring, and the process that performs a server handshake links the .nfsd keyring, into its process keyring for the duration of that handshake.

dane

This option specifies the DANE policy for client handshakes that authenticate a server certificate. off is the default, and means tlshd performs no TLSA lookup. opportunistic means a DNSSEC-validated TLSA RRset authenticates the server when one is published, and PKIX authentication applies when one is not. require means the handshake fails unless DANE governs it. The setting applies to every client handshake: the handshake protocol does not yet carry a per-handshake policy, so a kernel consumer cannot name one of its own.

This option is available only when tlshd was built with DANE support. A build without it accepts off and refuses to start with any other setting.

dane.trust_anchor

This option specifies the pathname of a file containing the DNSSEC root trust anchor, in the format unbound-anchor(8) writes. If this option is not specified, tlshd tries /var/lib/unbound/root.key, /usr/share/dns/root.key, /etc/unbound/root.key, /etc/dnssec-trust-anchors.d/root.key, and /etc/trusted-key.key, in that order, and uses the first one it can read. tlshd reads the anchor but does not maintain it: RFC 5011 key rollover is the job of whatever wrote the file. A trust anchor that is missing, unreadable, or malformed makes every DANE evaluation an error, which fails the handshake. It never silently downgrades to no DANE.

dane.resolver

This option specifies a semicolon-separated list of IP addresses of DNS resolvers to forward queries to. If this option is not specified, tlshd uses the resolvers named in resolv.conf(5). Whichever resolvers are used, they must return DNSSEC records: tlshd validates the answers itself.

And, in this section, there are two subsections: [client] and [server]. The tlshd program consults the settings in the [client] subsection when handling the client end of a handshake, and it consults the settings in the [server] subsection when handling the server end of a handshake.

In each of these two subsections, there are four available options:

x509.truststore

This option specifies the pathname of a file containing a PEM-encoded trust store that is to be used to verify a certificate during a handshake. If this option is not specified, tlshd uses the system's trust store.

x509.crl

This option specifies the pathname of a file containing PEM-encoded certificate revocation lists (CRL) that are to be used to verify the revocation status of certificates during each handshake. If this option is not specified, CRL checking is skipped.

x509.certificate

This option specifies the pathname of a file containing a PEM-encoded x.509 certificate that is to be presented during a handshake request when no other certificate is available.

x509.private_key

This option specifies the private key associated with the above certificate, either in the pathname of a key file in PEM encoding, or a GnuTLS-compatible key URL. In case of ambiguity where a relative path may be interpreted as a URL, prefix the path with "./".

x509.pq.certificate

This option specifies the pathname of a file containing a PEM-encoded x.509 certificate that is to be presented during a handshake request if the peer supports post-quantum cryptography. This certificate must be using a post-quantum public-key algorithm (ML-DSA-44, ML-DSA-65, or ML-DSA-87). If the peer does not support post-quantum cryptography, the certificate configured in the x509.certificate option will be presented instead.

x509.pq.private_key

This option specifies the private key associated with the above certificate, either in the pathname of a key file in PEM encoding, or a GnuTLS-compatible key URL. In case of ambiguity where a relative path may be interpreted as a URL, prefix the path with "./".

SEE ALSO

tlshd(8), tls-session-tags(7)

AUTHOR

Chuck Lever