tlshd: Add parsing for tag definitions

TLS session tags are defined in files that reside in
/etc/tlshd/tags.d/*.{yaml,yml}. On daemon start-up, the tag
definitions are read into a data structure that is shared with
forked children processes.

Unfortunately the libyaml parser is nothing more than a token
emitter. A nicer API exists in libcyaml, but that library does not
appear to be available in many distributions. Thus the new tag
config file parsing code implements a full finite state parser of
the session tags files.

Session tag configuration errors are reported but are not fatal.

Nothing is done with these tags yet, and documentation is added
in a subsequent patch.

Signed-off-by: Chuck Lever <[email protected]>

Author: chucklever

man/man7/tls-session-tags.7

@@ -239,6 +239,44 @@ For example:
 This blurb defines a filter named "monsters-university".
 It uses a wildcard match that looks for "O=Monsters University"
 in the "issuer" field of each incoming x.509 certificate.
+.SS 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. For example:
+
+  tags:
+    ...
+    ror-mu-chapter:
+      filter:
+        - monsters-university
+        - not fear-tech
+        - fraternity-ror
+    ...
+
+This defines a tag named "ror-mu-chapter".
+The "monsters-university" and "fraternity-ror" filters must
+match, and the "fear-tech" filter must not match,
+in order for the
+.B tlshd
+program to assign the
+.I ror-mu-chapter
+tag to an incoming TLS session.
+.SS Handshake completion
+Once a TLS handshake is successful, the
+.B tlshd
+program scans the peer's certificate using the configured filter and
+tag definitions.
+Any tag matches are attached to the new TLS session and are made
+visible to the kernel consumer that is to use that session.
+Note that
+the session's authentication material,
+any filter types,
+and
+filter names
+are not exposed to kernel consumers.
 .SH STANDARDS
 x.509
 .BR