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