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