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