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