xref: /freebsd/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 (revision ec0ea6efa1ad229d75c394c1a9b9cac33af2b1d3)
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.tlsclntd.8 by Rick Macklem.
29.Dd February 17, 2021
30.Dt RPC.TLSCLNTD 8
31.Os
32.Sh NAME
33.Nm rpc.tlsclntd
34.Nd "Sun RPC over TLS Client Daemon"
35.Sh SYNOPSIS
36.Nm
37.Op Fl C Ar preferred_ciphers
38.Op Fl D Ar certdir
39.Op Fl d
40.Op Fl l Ar CAfile
41.Op Fl m
42.Op Fl p Ar CApath
43.Op Fl r Ar CRLfile
44.Op Fl v
45.Sh DESCRIPTION
46The
47.Nm
48program provides support for the client side of the kernel Sun RPC over TLS
49implementation.
50This daemon must be running for the kernel RPC to be able to do a TLS
51connection to a server for an NFS over TLS mount.
52This daemon requires that the kernel be built with
53.Dq options KERNEL_TLS
54and be running on an architecture such as
55.Dq amd64
56that supports a direct map (not i386) with
57.Xr ktls 4
58enabled.
59.Pp
60If either of the
61.Fl l
62or
63.Fl p
64options have been specified, the daemon will require the server's
65certificate to verify
66and have a Fully Qualified Domain Name (FQDN) in it.
67This FQDN must match
68the reverse DNS name for the IP address that
69the server is using for the TCP connection.
70The FQDN may be
71in either the DNS field of the subjectAltName or the CN field of the
72subjectName in the certificate and
73cannot have a wildcard
74.Dq *
75in it.
76.Pp
77If a SIGHUP signal is sent to the daemon it will reload the
78.Dq CRLfile
79and will shut down any extant connections that presented certificates
80during TLS handshake that have been revoked.
81If the
82.Fl r
83option was not specified, the SIGHUP signal will be ignored.
84.Pp
85The daemon will log failed certificate verifications via
86.Xr syslogd 8
87using LOG_INFO | LOG_DAEMON when the
88.Fl l
89or
90.Fl p
91option has been specified.
92.Pp
93The options are as follows:
94.Bl -tag -width indent
95.It Fl C Ar preferred_ciphers , Fl Fl ciphers= Ns Ar preferred_ciphers
96Specify what preferred ciphers are to be used.
97If this option is specified,
98.Dq SSL_CTX_set_cipher_list()
99will be called with
100.Dq preferred_ciphers
101as the argument.
102If this option is not specified, the cipher will be chosen by
103.Xr ssl 7 .
104.It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir
105Use
106.Dq certdir
107instead of /etc/rpc.tlsclntd for the
108.Fl m
109option.
110.It Fl d , Fl Fl debuglevel
111Run in debug mode.
112In this mode,
113.Nm
114will not fork when it starts.
115.It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile
116This specifies the path name of a CAfile which holds the information
117for server certificate verification.
118This path name is used in
119.Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL)
120and
121.Dq SSL_CTX_set0_CA_list(ctx,SSL_load_client_CA_file(CAfile))
122openssl library calls.
123Note that this is a path name for the file and is not assumed to be
124in
125.Dq certdir .
126.It Fl m , Fl Fl mutualverf
127Enable support for mutual authentication.
128A certificate and associated key must be found in /etc/rpc.tlsclntd
129(or the directory specified by the
130.Fl D
131option)
132in case a server requests a peer certificate.
133The first certificate needs to be in a file named
134.Dq cert.pem
135and the associated key in a file named
136.Dq certkey.pem .
137The
138.Xr mount_nfs 8
139option
140.Fl tlscertname
141can be used to override the default certificate for a given
142NFS mount, where the files use the alternate naming specified by the option.
143If there is a passphrase on the
144.Dq certkey.pem
145file, this daemon will prompt for the passphrase during startup.
146The keys for alternate certificates cannot have passphrases.
147.It Fl p Ar CApath , Fl Fl verifydir= Ns Ar CApath
148This option is similar to the
149.Fl l
150option, but specifies the path of a directory with CA
151certificates in it.
152When this option is used,
153.Dq SSL_CTX_set0_CA_list(ctx,SSL_load_client_CA_file())
154is not called, so a list of CA names is not be passed
155to the server during the TLS handshake.
156The openssl documentation indicates this call is rarely needed.
157.It Fl r Ar CRLfile , Fl Fl crl= Ns Ar CRLfile
158This option specifies a Certificate Revocation List (CRL) file
159that is to be loaded into the verify certificate store and
160checked during verification of the server's certificate.
161This option is meaningless unless either the
162.Fl l
163or
164.Fl p
165have been specified.
166.It Fl v , Fl Fl verbose
167Run in verbose mode.
168In this mode,
169.Nm
170will log activity messages to syslog using LOG_INFO | LOG_DAEMON or to
171stderr, if the
172.Fl d
173option has also been specified.
174.El
175.Sh EXIT STATUS
176.Ex -std
177.Sh SEE ALSO
178.Xr openssl 1 ,
179.Xr ktls 4 ,
180.Xr mount_nfs 8 ,
181.Xr rpc.tlsservd 8 ,
182.Xr ssl 7 ,
183.Xr syslogd 8
184.Sh STANDARDS
185The implementation is based on the specification in
186.Rs
187.%B "RFC NNNN"
188.%T "Towards Remote Procedure Call Encryption By Default"
189.Re
190.Sh HISTORY
191The
192.Nm
193manual page first appeared in
194.Fx 13.0 .
195.Sh BUGS
196This daemon cannot be safely shut down and restarted if there are
197any active RPC-over-TLS connections.
198Doing so will orphan the KERNEL_TLS connections, so that they
199can no longer do upcalls successfully, since the
200.Dq SSL *
201structures in userspace have been lost.
202