tls-session-tags(7)

📦 version 1.4.0, in fedora 43, fedora 44

💖 NAME 💖

okay bestie, welcome to tls-session-tags — the TLS session tags page 💅✨ (that's tls-session-tags(7) out of the Miscellaneous Information Manual, if you're keeping track 🎀).

This is the one that explains how you get cute little labels stamped onto TLS sessions so the kernel knows who's who. no cap. 🏷️🦋

✨ SYNOPSIS ✨

/etc/tlshd/tags.d/

that's it. that's the vibe. one directory, endless power 🌸

🌈 DESCRIPTION 🌈

so, the tlshd program runs a user agent that services TLS handshake requests on behalf of kernel TLS consumers 🫶. its configuration files live under the /etc/tlshd directory, and they hold the info that tlshd reads when it starts up. these config files are the ones telling tlshd where to find stuff about which trust store and which signing and encryption algorithms are supposed to be used. and like — important — these configuration files are considered a trusted source of information. they're the main character, they don't get questioned 💅.

when a peer shows up with an X.509 certificate during a TLS handshake, tlshd is the one responsible for verifying that the certificate was issued by a certificate authority that the receiver recognizes and trusts 🔍✅. once that verification goes through, the receiver can trust the content of that certificate, including all the info about the peer identity presented in it (e.g., a DNS hostname or IP address, and so on 👀).

and once a peer's certificate is trusted?? that's when it gets good. tlshd can be configured to scan the fields in the peer's certificate 🔥. based on that scan, tlshd can assign tags to the new TLS session that indicate the server recognizes the peer's identity 🏷️💖. for example, tlshd 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 then use those tags to authorize or deny access to resources based on the identity presented in peer certificates. literally access control but make it fashion 👑

the following sections describe how to configure this facility. buckle up 🧚

🎀 FORMAT 🎀

TLS session tag definitions are YAML documents stored in files in the /etc/tlshd/tags.d directory 📂. when it launches, tlshd reads all files in that directory with either the .yml or .yaml extension. heads up though: modifications to the content of these files take effect only when the tlshd program is restarted — so edit, save, restart, slay 🔄✨.

tlshd populates two dictionaries from the contents of these files:

  • filters — every filter defined in this dictionary specifies the name of a field in an X.509 certificate, plus the conditions under which the contents of that field are considered a match 🔍.
  • tags — each tag is a list of one or more filters (the ones defined in the filters dictionary) that all must be matched in order for that tag to get assigned to a new TLS session 🏷️.

🌸 Filter types 🌸

a filter's type decides which part of the incoming authentication material tlshd examines to figure out if there's a match 👀. for example, for the x509.tbs.subject filter type, a string argument specifies a simple wildcard pattern that gets matched against an incoming X.509 certificate's subject field. the complete list of filter types lives down in the FILTER TYPE REFERENCE section below 👇💜.

👑 FILTER TYPE REFERENCE 👑

tlshd currently implements the following filter types 🫶:

  • x509.cert.signatureAlgorithm — 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, which can be an algorithm name or an algorithm OID.
  • x509.tbs.version — filters of this type examine an incoming X.509 certificate's version field, which is 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 gets matched against the certificate's version.
  • x509.tbs.serialNumber — 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.
  • x509.tbs.issuer — 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.
  • x509.tbs.validity.notBefore — 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. it matches when the certificate's activation time is equal to or later than the specified threshold ⏰. use this one when you want to accept only certificates issued on or after a particular date. no old certs allowed 💅.
  • x509.tbs.validity.notAfter — 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. it matches when the certificate's expiration time is equal to or earlier than the specified threshold ⏰. use this one to accept only certificates that expire on or before a particular date. expired-and-proud stays OUT 🙅.
  • x509.tbs.subject — 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.
  • x509.extension.keyUsage — filters of this type examine an incoming X.509 certificate's keyUsage field, which is one of the standard certificate extensions 🔑. the filter takes a list of bit names that must all be set in the field for the filter to match. that list contains zero or more of the following bit names: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, or decipherOnly. ✨
  • x509.extension.extendedKeyUsage — 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 💀 sorry bestie, it's giving "coming soon", it does nothing yet.
  • x509.derived.fingerprint — 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 the derived SHA256 fingerprint.
  • x509.derived.selfSigned — 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 a 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. iconic behavior honestly.

💜 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. periodt.

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 tlshd to assign the ror-mu-chapter tag to an incoming TLS session. the way that it's a whole membership check 😭💖

✨ Handshake completion ✨

once a TLS handshake is successful 🤝, tlshd scans the peer's certificate using the configured filter and tag definitions. for each tag whose filter conditions the certificate satisfies, tlshd attaches that tag's name to the new TLS session 🏷️✨. and here's the slay part: the kernel consumer receives only the list of matching tag names — the session's authentication material, filter types, and filter names all stay private to tlshd 🔒. gatekeeping, but correctly.

📜 STANDARDS 📜

X.509 RFC 5280, RFC 6125 📚

👀 SEE ALSO 👀

tlshd(8), tlshd.conf(5) 💖

🫶 AUTHOR 🫶

Chuck Lever 👑

and that's the whole page bestie, ty for coming to my TED talk 🎀✨ this was the Miscellaneous Information Manual's tls-session-tags(7) — dated 28 Dec 2025 📅 — mwah, go tag some sessions, ily 💅💖🦋

📦 where this page comes from