usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8

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