1.\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/
2.\" Authors: Doug Rabson <dfr@rabson.org>
3.\" Developed with Red Inc: Alfred Perlstein <alfred@FreeBSD.org>
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.\" Modified from gssd.8 for rpc.tlsservd.8 by Rick Macklem.
29.Dd November 10, 2022
30.Dt RPC.TLSSERVD 8
31.Os
32.Sh NAME
33.Nm rpc.tlsservd
34.Nd "Sun RPC over TLS Server Daemon"
35.Sh SYNOPSIS
36.Nm
37.Op Fl 2
38.Op Fl C Ar available_ciphers
39.Op Fl D Ar certdir
40.Op Fl d
41.Op Fl h
42.Op Fl l Ar CAfile
43.Op Fl m
44.Op Fl N Ar num_servers
45.Op Fl n Ar domain
46.Op Fl p Ar CApath
47.Op Fl r Ar CRLfile
48.Op Fl u
49.Op Fl v
50.Op Fl W
51.Op Fl w
52.Sh DESCRIPTION
53The
54.Nm
55program provides support for the server side of the kernel Sun RPC over TLS
56implementation.
57This daemon must be running to allow the kernel RPC to perform the TLS
58handshake after a TCP client has sent the STARTTLS Null RPC request to
59the server.
60This daemon requires that the kernel be built with
61.Dq options KERNEL_TLS
62and be running on an architecture such as
63.Dq amd64
64that supports a direct map (not i386) with
65.Xr ktls 4
66enabled.
67Note that the
68.Fl tls
69option in the
70.Xr exports 5
71file specifies that the client must use RPC over TLS.
72The
73.Fl tlscert
74option in the
75.Xr exports 5
76file specifies that the client must provide a certificate
77that verifies.
78The
79.Fl tlscertuser
80option in the
81.Xr exports 5
82file specifies that the client must provide a certificate
83that verifies and has a otherName:1.3.6.1.4.1.2238.1.1.1;UTF8: field of
84subjectAltName of the form
85.Dq user@domain
86where
87.Dq domain
88matches the one for this server and
89.Dq user
90is a valid user name that maps to a <uid, gid_list>.
91For the latter two cases, the
92.Fl m
93and either the
94.Fl l
95or
96.Fl p
97options must be specified.
98The
99.Fl tlscertuser
100option also requires that the
101.Fl u
102option on this daemon be specified.
103.Pp
104Also, if the IP address used by the client cannot be trusted,
105the rules in
106.Xr exports 5
107cannot be applied safely.
108As such, the
109.Fl h
110option can be used along with
111.Fl m
112and either the
113.Fl l
114or
115.Fl p
116options to require that the client certificate have the correct
117Fully Qualified Domain Name (FQDN) in it.
118.Pp
119A certificate and associated key must exist in /etc/rpc.tlsservd
120(or the
121.Dq certdir
122specified by the
123.Fl D
124option)
125in files named
126.Dq cert.pem
127and
128.Dq certkey.pem .
129.Pp
130If a SIGHUP signal is sent to the daemon it will reload the
131.Dq CRLfile
132and will shut down any extant connections that presented certificates
133during TLS handshake that have been revoked.
134If the
135.Fl r
136option was not specified, the SIGHUP signal will be ignored.
137.Pp
138The daemon will log failed certificate verifications via
139.Xr syslogd 8
140using LOG_INFO | LOG_DAEMON when the
141.Fl m
142option has been specified.
143.Pp
144The options are as follows:
145.Bl -tag -width indent
146.It Fl 2 , Fl Fl allowtls1_2
147Permit clients to mount using TLS version 1.2.
148By default, the daemon will only allow mounts
149using TLS version 1.3, as required by the RFC.
150However, early
151.Fx
152.Pq 13.0 and 13.1
153clients require
154this option, since they use TLS version 1.2.
155.It Fl C Ar available_ciphers , Fl Fl ciphers= Ns Ar available_ciphers
156Specify which ciphers are available during TLS handshake.
157If this option is specified,
158.Dq SSL_CTX_set_ciphersuites()
159will be called with
160.Dq available_ciphers
161as the argument.
162If this option is not specified, the cipher will be chosen by
163.Xr ssl 7 ,
164which should be adequate for most cases.
165The format for the available ciphers is a simple
166.So
167:
168.Sc
169separated list, in order of preference.
170The command
171.Dq openssl ciphers -s -tls1_3
172lists available ciphers.
173.It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir
174Use
175.Dq certdir
176instead of /etc/rpc.tlsservd as the location for the
177certificate in a file called
178.Dq cert.pem
179and associated key in
180.Dq certkey.pem .
181.It Fl d , Fl Fl debuglevel
182Run in debug mode.
183In this mode,
184.Nm
185will not fork when it starts.
186.It Fl h , Fl Fl checkhost
187This option specifies that the client must provide a certificate
188that both verifies and has a FQDN that matches the reverse
189DNS name for the IP address that
190the client uses to connect to the server.
191The FQDN should be
192in the DNS field of the subjectAltName, but is also allowed
193to be in the CN field of the
194subjectName in the certificate.
195By default, a wildcard "*" in the FQDN is not allowed.
196With this option, a failure to verify the client certificate
197or match the FQDN will result in the
198server sending AUTH_REJECTEDCRED replies to all client RPCs.
199This option requires the
200.Fl m
201and either the
202.Fl l
203or
204.Fl p
205options.
206.It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile
207This option specifies the path name of a CA certificate(s) file
208in pem format, which is used to verify client certificates and to
209set the list of CA(s) sent to the client so that it knows which
210certificate to send to the server during the TLS handshake.
211This path name is used in
212.Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL)
213and
214.Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile))
215openssl library calls.
216Note that this is a path name for the file and is not assumed to be
217in
218.Dq certdir .
219Either this option or the
220.Fl p
221option must be specified when the
222.Fl m
223option is specified so that the daemon can verify the client's
224certificate.
225.It Fl m , Fl Fl mutualverf
226This option specifies that the server is to request a certificate
227from the client during the TLS handshake.
228It does not require that the client provide a certificate.
229It should be specified unless no client doing RPC over TLS is
230required to have a certificate.
231For NFS, either the
232.Xr exports 5
233option
234.Fl tlscert
235or
236.Fl tlscertuser
237may be used to require a client to provide a certificate
238that verifies.
239See
240.Xr exports 5 .
241.It Fl N Ar num_servers , Fl Fl numdaemons= Ns Ar num_servers
242For a server with a large number of NFS-over-TLS client mounts,
243this daemon might get overloaded after a reboot, when many
244clients attempt to do a TLS handshake at the same time.
245This option may be used to specify that
246.Dq num_servers
247daemons are to be run instead of a single daemon.
248When this is done, the TLS handshakes are spread across the
249.Dq num_servers
250daemons in a round robin fashion to spread out the load.
251.It Fl n Ar domain , Fl Fl domain= Ns Ar domain
252This option specifies what the
253.Dq domain
254is for use with the
255.Fl u
256option, overriding the domain taken from the
257.Xr gethostname 2
258of the server this daemon is running on.
259If you have specified the
260.Fl domain
261command line option for
262.Xr nfsuserd 8
263then you should specify this option with the same
264.Dq domain
265that was specified for
266.Xr nfsuserd 8 .
267This option is only meaningful when used with the
268.Fl u
269option.
270.It Fl p Ar CApath , Fl Fl verifydir= Ns Ar CApath
271This option is similar to the
272.Fl l
273option, but specifies the path of a directory with CA
274certificates in it.
275When this option is used,
276.Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file())
277is not called, so a list of CA names might not be passed
278to the client during the TLS handshake.
279.It Fl r Ar CRLfile , Fl Fl crl= Ns Ar CRLfile
280This option specifies a Certificate Revocation List (CRL) file
281that is to be loaded into the verify certificate store and
282checked during verification.
283This option is only meaningful when either the
284.Fl l
285or
286.Fl p
287have been specified.
288.It Fl u , Fl Fl certuser
289This option specifies that if the client provides a certificate
290that both verifies and has a subjectAltName with an otherName
291component of the form
292.Dq otherName:1.3.6.1.4.1.2238.1.1.1;UTF8:user@domain
293where
294.Dq domain
295matches the one for this server,
296then the daemon will attempt to map
297.Dq user
298in the above
299to a user credential <uid, gid_list>.
300There should only be one of these otherName components for each
301.Dq domain .
302If
303.Dq user
304is a valid username in the password database,
305then the <uid, gid_list> for
306.Dq user
307will be used for all
308RPCs on the mount instead of the credentials in the RPC request
309header.
310This option requires the
311.Fl m
312and either the
313.Fl l
314or
315.Fl p
316options.
317Use of this option might not conform to RFC-9289, which does
318not allow certificates to be used for user authentication.
319.It Fl v , Fl Fl verbose
320Run in verbose mode.
321In this mode,
322.Nm
323will log activity messages to
324.Xr syslogd 8
325using LOG_INFO | LOG_DAEMON or to
326stderr, if the
327.Fl d
328option has also been specified.
329.It Fl W , Fl Fl multiwild
330This option is used with the
331.Fl h
332option to allow use of a wildcard
333.Dq *
334that matches multiple
335components of the reverse DNS name for the client's IP
336address.
337For example, the FQDN
338.Dq *.uoguelph.ca
339would match both
340.Dq laptop21.uoguelph.ca
341and
342.Dq laptop3.cis.uoguelph.ca .
343.It Fl w , Fl Fl singlewild
344Similar to
345.Fl W
346but allows the wildcard
347.Dq *
348to match a single component of the reverse DNS name.
349For example, the FQDN
350.Dq *.uoguelph.ca
351would match
352.Dq laptop21.uoguelph.ca
353but not
354.Dq laptop3.cis.uoguelph.ca .
355Only one of the
356.Fl W
357and
358.Fl w
359options is allowed.
360.El
361.Sh EXIT STATUS
362.Ex -std
363.Sh SEE ALSO
364.Xr openssl 1 ,
365.Xr ktls 4 ,
366.Xr exports 5 ,
367.Xr ssl 7 ,
368.Xr mount_nfs 8 ,
369.Xr nfsuserd 8 ,
370.Xr rpc.tlsclntd 8 ,
371.Xr syslogd 8
372.Sh STANDARDS
373The implementation is based on the specification in
374.Rs
375.%B "RFC 9289"
376.%T "Towards Remote Procedure Call Encryption By Default"
377.Re
378.Sh HISTORY
379The
380.Nm
381manual page first appeared in
382.Fx 13.0 .
383.Sh BUGS
384This daemon cannot be safely shut down and restarted if there are
385any active RPC-over-TLS connections.
386Doing so will orphan the KERNEL_TLS connections, so that they
387can no longer do upcalls successfully, since the
388.Dq SSL *
389structures in userspace have been lost.
390