1. Manuals
  2. Tumbleweed
  3. ktls-utils
  4. tls-session-tags(7)

Scroll to navigation

tls-session-tags(7) Miscellaneous Information Manual tls-session-tags(7)

NAME

tls-session-tags - TLS session tags

SYNOPSIS

/etc/tlshd/tags.d/

DESCRIPTION

The tlshd program implements a user agent that services TLS handshake requests on behalf of kernel TLS consumers. Its configuration files, found under the /etc/tlshd directory, contain information that the tlshd program reads when it starts up. The configuration files direct the tlshd program to information about which trust store and signing and encryption algorithms are to be used. The configuration files are considered a trusted source of information.

When a peer presents an X.509 certificate during a TLS handshake, the tlshd program is responsible for verifying that the certificate was issued by a certificate authority that the receiver recognizes and trusts. Once that verification is successful, the receiver can trust the content of that certificate, including information about the peer identity presented in that certificate (e.g., a DNS hostname or IP address, and so on).

Once a peer's certificate is trusted, the tlshd program can be configured to scan the fields in the peer's certificate. Based on the scan, the tlshd program can assign tags to the new TLS session that indicate that the server recognizes the peer's identity. For example, the tlshd program can be configured to look for a specific string in subject fields, and assign tags to TLS sessions where the peer presented a certificate with matching content in that field. Kernel consumers can use those tags to authorize or deny access to resources based on the identity presented in peer certificates.

The following sections describe how to configure this facility.

FORMAT

TLS session tag definitions are YAML documents stored in files in the /etc/tlshd/tags.d directory. When it launches, the tlshd program reads all files in that directory with either the .yml or .yaml extension. Modifications to the content of these files take effect only when the tlshd program is restarted.

The tlshd program populates two dictionaries from the contents of these files:

Each filter defined in this dictionary specifies the name of a field in an X.509 certificate, and the conditions under which the contents of that field are to be considered a match.
Each tag is a list of one or more filters (defined in the filters dictionary) that all must be matched in order for the tag to be assigned to a new TLS session.

Filter types

A filter's type determines the part of the incoming authentication material that the tlshd program examines to determine if there is a match. For example, for the x509.tbs.subject filter type, a string argument specifies a simple wildcard pattern that is matched against an incoming X.509 certificate's subject field. A complete list of filter types appears in the FILTER TYPE REFERENCE section below.

FILTER TYPE REFERENCE

The tlshd program currently implements the following filter types:

Filters of this type examine an incoming X.509 certificate's signatureAlgorithm field, as defined in RFC 5280, Section 4.1.1.2. The filter takes an additional string wildcard pattern that can be an algorithm name or an algorithm OID.
Filters of this type examine an incoming X.509 certificate's version field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.1. The filter takes an additional numeric value that is matched against the certificate's version.
Filters of this type examine an incoming X.509 certificate's serialNumber field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.2. The filter takes an additional string wildcard pattern that matches a hexadecimal number.
Filters of this type examine an incoming X.509 certificate's issuer field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.4. The filter takes an additional string wildcard pattern that matches the distinguished name part of the certificate's issuer field.
Filters of this type examine an incoming X.509 certificate's activation time field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.5. The filter takes a date and time string. The filter matches when the certificate's activation time is equal to or later than the specified threshold. Use this filter to accept only certificates issued on or after a particular date.
Filters of this type examine an incoming X.509 certificate's expiration time field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.5. The filter takes a date and time string. The filter matches when the certificate's expiration time is equal to or earlier than the specified threshold. Use this filter to accept only certificates that expire on or before a particular date.
Filters of this type examine an incoming X.509 certificate's subject field, part of the To-Be-Signed section of the certificate, as defined in RFC 5280, Section 4.1.2.6. The filter takes an additional string wildcard pattern that matches the distinguished name part of the certificate's subject field.

Filters of this type examine an incoming X.509 certificate's keyUsage field, one of the standard certificate extensions. The filter takes a list of bit names that must be set in the field in order for the filter to match. This list contains zero or more of the following bit names: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, or decipherOnly.
Filters of this type examine an incoming X.509 certificate's extendedKeyUsage field, one of the standard certificate extensions. This filter type is not yet implemented.
Filters of this type locally compute an incoming X.509 certificate's SHA1 and SHA256 fingerprint. The filter takes an additional string wildcard pattern that matches the hexadecimal value of either the derived SHA1 or derived SHA256 fingerprint.
Filters of this type match when an incoming X.509 certificate's issuer and subject distinguished names are exactly equal.

Filters

The definition of each filter is YAML mapping that specifies the unique name of the filter, its filter type, and zero or more specific match arguments to be used. For example:

filters:


  ...


  monsters-university:


    type: "x509.tbs.issuer"


    pattern: "*,O=Monsters University,*"


  ...

This example defines a filter named "monsters-university". The filter performs a wildcard match for "O=Monsters University" in the issuer field of each incoming X.509 certificate.

Tags

The definition of each tag is a YAML mapping that specifies the unique name of the tag and a list of filters, as defined in the Filters mapping, that all must match for the tag to be assigned to a TLS session.

A filter name can be prefixed with "not " to invert its matching behavior. When a filter is negated, the tag matches only if that filter does not match. A tag matches when all non-negated filters match and all negated filters do not match.

For example:

tags:


  ...


  ror-mu-chapter:


    filter:


      - monsters-university


      - not fear-tech


      - fraternity-ror


  ...

This example defines a tag named "ror-mu-chapter". The peer's certificate must satisfy both the "monsters-university" and "fraternity-ror" filter conditions, and must fail to satisfy the "fear-tech" filter condition, in order for the tlshd program to assign the ror-mu-chapter tag to an incoming TLS session.

Handshake completion

Once a TLS handshake is successful, the tlshd program scans the peer's certificate using the configured filter and tag definitions. For each tag whose filter conditions the certificate satisfies, the tlshd program attaches that tag's name to the new TLS session. The kernel consumer receives only the list of matching tag names; the session's authentication material, filter types, and filter names remain private to the tlshd program.

STANDARDS

RFC 5280, RFC 6125

SEE ALSO

tlshd(8), tlshd.conf(5)

AUTHOR

Chuck Lever

28 Dec 2025