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