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