Skip to content

Commit fc3bb8c

Browse files
chuckleverchucklever
committed
tlshd: man update for TLS session tags
Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
1 parent 4c75ec8 commit fc3bb8c

File tree

3 files changed

+172
-2
lines changed

3 files changed

+172
-2
lines changed

‎src/tlshd/etc/Makefile.am

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ tlshdconfig_DATA = config
2323
tlshdtags_DATA = tags.example
2424

2525
man5_MANS = tlshd.conf.man
26-
EXTRA_DIST = $(man5_MANS)
26+
man7_MANS = tls-session-tags.man
27+
EXTRA_DIST = $(man5_MANS) $(man7_MANS)
2728

2829
MAINTAINERCLEANFILES = Makefile.in
2930

‎src/tlshd/etc/tls-session-tags.man

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
.\"
2+
.\" Copyright (c) 2025 Oracle and/or its affiliates.
3+
.\"
4+
.\" ktls-utils is free software; you can redistribute it and/or
5+
.\" modify it under the terms of the GNU General Public License as
6+
.\" published by the Free Software Foundation; version 2.
7+
.\"
8+
.\" This program is distributed in the hope that it will be useful,
9+
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
10+
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11+
.\" General Public License for more details.
12+
.\"
13+
.\" You should have received a copy of the GNU General Public License
14+
.\" along with this program; if not, write to the Free Software
15+
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
16+
.\" 02110-1301, USA.
17+
.\"
18+
.\" tls-session-tags(7)
19+
.\"
20+
.TH tls-session-tags 7 "5 Aug 2025"
21+
.SH NAME
22+
tls-session-tags \- TLS session tags
23+
.SH SYNOPSIS
24+
.B /etc/tlsd/tags.d
25+
.SH DESCRIPTION
26+
The
27+
.B tlshd
28+
program implements a user agent that services TLS handshake requests
29+
on behalf of kernel TLS consumers.
30+
Its configuration files, found under the
31+
.I /etc/tlshd
32+
directory, contain information that the
33+
.B tlshd
34+
program reads when it starts up.
35+
The configuration files direct the
36+
.B tlshd
37+
program to information about which trust store and signing
38+
and encryption algorithms are to be used.
39+
The configuration files are considered a trusted source of information.
40+
.P
41+
When a remote presents an x.509 certificate during a TLS handshake, the
42+
.B tlshd
43+
program is responsible for verifying that the certificate was
44+
issued by a certificate authority that the receiver recognizes and
45+
trusts.
46+
Once that verification is successful, the receiver can trust
47+
the content of that certificate, including information about
48+
the peer identity presented in that certificate (eg. a DNS hostname
49+
or IP address, and so on).
50+
.P
51+
Once a peer's certificate is trusted,
52+
the
53+
.B tlshd
54+
program can be configured to scan the fields in the peer's certificate.
55+
Based on the scan,
56+
the
57+
.B tlshd
58+
program can assign tags to the new TLS session that
59+
indicate that the server recognizes the peer's identity.
60+
For example,
61+
the
62+
.B tlshd
63+
program can be configured to look for a specific string in
64+
.I subject
65+
fields, and assign tags to TLS sessions where the peer presented
66+
a certificate with matching content in that field.
67+
Kernel consumers can use those tags to authorize or deny access
68+
to resources based on the identity presented in peer certificates.
69+
.P
70+
The following sections describe how to configure this facility.
71+
.SH FORMAT
72+
TLS session tag definitions are YAML documents stored in files under the
73+
.I /etc/tlshd/tags.d
74+
directory.
75+
When it launches, the
76+
.B tlshd
77+
program reads all files in that directory with either the
78+
.I .yml
79+
or
80+
.I .yaml
81+
extension.
82+
Thus changes made in these files take effect only when the
83+
.B tlshd
84+
program is restarted.
85+
.P
86+
The
87+
.B tlshd
88+
program
89+
populates two dictionaries from the contents of these files:
90+
.TP
91+
.B filters
92+
Each filter defined in this dictionary specifies the name of a
93+
field in an x.509 certificate, and the conditions under which the
94+
contents of that field are a "match".
95+
.TP
96+
.B tags
97+
Each tag is a list of filters (defined in the
98+
.B filters
99+
dictionary)
100+
that all must be matched in order for the tag to be assigned to a new
101+
TLS session.
102+
.SS Filters
103+
The definition of a filter is small YAML dictionary (or mapping) that
104+
specifies the name of the filter, the certificate field it scans, and
105+
the condition that defines a "match". For example:
106+
107+
monsters-university:
108+
field: "issuer"
109+
type: "wildcard"
110+
expression: "*,O=Monsters University,*"
111+
112+
This defines a filter named "monsters-university".
113+
It uses a wildcard match to look for "O=Monsters Univerity" in
114+
each certificate's "issuer" field.
115+
The string value of the
116+
.I field
117+
key can be the name of any x.509 certificate field (though not
118+
all fields are supported yet).
119+
The string value of the
120+
.I type
121+
key is one of "exact", "wildcard", "regex", or "list".
122+
123+
When the value of
124+
.I type
125+
is "exact", "wildcard", or "regex",
126+
the
127+
.I expression
128+
value is a string that is to be matched against.
129+
When the value of
130+
.I type
131+
is "list", the
132+
.I expression
133+
value is a list of x.509 keyUsage bit names.
134+
.SS Tags
135+
The definition of a tag is a small YAML dictionary that specifies
136+
the name of the tag and a list of filters (as defined in the Filters
137+
mapping, above) that all must match for the tag to be assigned to
138+
a TLS session. For example:
139+
140+
ror-mu-chapter:
141+
filter:
142+
- "monsters-univerity"
143+
- "fraternity-ror"
144+
145+
This defines a tag named "ror-mu-chapter".
146+
Both the "monsters-university" and "fraternity-ror" filters must
147+
match in order for the
148+
.B tlshd
149+
program to assign this tag to an incoming TLS session.
150+
.SS Handshake completion
151+
Once a handshake is successful, the
152+
.B tlshd
153+
program scans the peer's certificate using the configured filter and
154+
tag definitions.
155+
Any tag matches are attached to the new TLS session and are made
156+
visible to the kernel consumer that is to use the session.
157+
Note that filter names are not exposed to kernel consumers.
158+
.SH STANDARDS
159+
x.509
160+
.BR
161+
RFC 5280
162+
.BR
163+
RFC 6125
164+
.SH SEE ALSO
165+
.BR tlshd (8),
166+
.BR tlshd.conf (5)
167+
.SH AUTHOR
168+
Chuck Lever

‎src/tlshd/etc/tlshd.conf.man

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@ a handshake request when no other certificate is available.
126126
This option specifies the pathname of a file containing
127127
a PEM-encoded private key associated with the above certificate.
128128
.SH SEE ALSO
129-
.BR tlshd (8)
129+
.BR tlshd (8),
130+
.BR tls-session-tags (7)
130131
.SH AUTHOR
131132
Chuck Lever

0 commit comments

Comments
 (0)