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.tlsservd.8 by Rick Macklem. 29.Dd January 29, 2021 30.Dt RPC.TLSSERVD 8 31.Os 32.Sh NAME 33.Nm rpc.tlsservd 34.Nd "Sun RPC over TLS Server Daemon" 35.Sh SYNOPSIS 36.Nm 37.Op Fl D Ar certdir 38.Op Fl d 39.Op Fl h 40.Op Fl l Ar CAfile 41.Op Fl m 42.Op Fl n Ar domain 43.Op Fl p Ar CApath 44.Op Fl r Ar CRLfile 45.Op Fl u 46.Op Fl v 47.Op Fl W 48.Op Fl w 49.Sh DESCRIPTION 50The 51.Nm 52program provides support for the server side of the kernel Sun RPC over TLS 53implementation. 54This daemon must be running to allow the kernel RPC to perform the TLS 55handshake after a TCP client has sent the STARTTLS Null RPC request to 56the server. 57This daemon requires that the kernel be built with 58.Dq options KERNEL_TLS 59and be running on an architecture such as 60.Dq amd64 61that supports a direct map (not i386) with 62.Xr ktls 4 63enabled. 64Note that the 65.Fl tls 66option in the 67.Xr exports 5 68file specifies that the client must use RPC over TLS. 69The 70.Fl tlscert 71option in the 72.Xr exports 5 73file specifies that the client must provide a certificate 74that verifies. 75The 76.Fl tlscertuser 77option in the 78.Xr exports 5 79file specifies that the client must provide a certificate 80that verifies and has a otherName:1.3.6.1.4.1.2238.1.1.1;UTF8: field of 81subjectAltName of the form 82.Dq user@domain 83where 84.Dq domain 85matches the one for this server and 86.Dq user 87is a valid user name that maps to a <uid, gid_list>. 88For the latter two cases, the 89.Fl m 90and either the 91.Fl l 92or 93.Fl p 94options must be specified. 95The 96.Fl tlscertuser 97option also requires that the 98.Fl u 99option on this daemon be specified. 100.Pp 101Also, if the IP address used by the client cannot be trusted, 102the rules in 103.Xr exports 5 104cannot be applied safely. 105As such, the 106.Fl h 107option can be used along with 108.Fl m 109and either the 110.Fl l 111or 112.Fl p 113options to require that the client certificate have the correct 114Fully Qualified Domain Name (FQDN) in it. 115.Pp 116A certificate and associated key must exist in /etc/rpc.tlsservd 117(or the 118.Dq certdir 119specified by the 120.Fl D 121option) 122in files named 123.Dq cert.pem 124and 125.Dq certkey.pem . 126.Pp 127If a SIGHUP signal is sent to the daemon it will reload the 128.Dq CRLfile 129and will shut down any extant connections that presented certificates 130during TLS handshake that have been revoked. 131If the 132.Fl r 133option was not specified, the SIGHUP signal will be ignored. 134.Pp 135The daemon will log failed certificate verifications via 136.Xr syslogd 8 137using LOG_INFO | LOG_DAEMON when the 138.Fl m 139option has been specified. 140.Pp 141The options are as follows: 142.Bl -tag -width indent 143.It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir 144Use 145.Dq certdir 146instead of /etc/rpc.tlsservd as the location for the 147certificate in a file called 148.Dq cert.pem 149and associated key in 150.Dq certkey.pem . 151.It Fl d , Fl Fl debuglevel 152Run in debug mode. 153In this mode, 154.Nm 155will not fork when it starts. 156.It Fl h , Fl Fl checkhost 157This option specifies that the client must provide a certificate 158that both verifies and has a FQDN that matches the reverse 159DNS name for the IP address that 160the client uses to connect to the server. 161The FQDN should be 162in the DNS field of the subjectAltName, but is also allowed 163to be in the CN field of the 164subjectName in the certificate. 165By default, a wildcard "*" in the FQDN is not allowed. 166With this option, a failure to verify the client certificate 167or match the FQDN will result in the 168server sending AUTH_REJECTEDCRED replies to all client RPCs. 169This option requires the 170.Fl m 171and either the 172.Fl l 173or 174.Fl p 175options. 176.It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile 177This option specifies the path name of a CA certificate(s) file 178in pem format, which is used to verify client certificates and to 179set the list of CA(s) sent to the client so that it knows which 180certificate to send to the server during the TLS handshake. 181This path name is used in 182.Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL) 183and 184.Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile)) 185openssl library calls. 186Note that this is a path name for the file and is not assumed to be 187in 188.Dq certdir . 189Either this option or the 190.Fl p 191option must be specified when the 192.Fl m 193option is specified so that the daemon can verify the client's 194certificate. 195.It Fl m , Fl Fl mutualverf 196This option specifies that the server is to request a certificate 197from the client during the TLS handshake. 198It does not require that the client provide a certificate. 199It should be specified unless no client doing RPC over TLS is 200required to have a certificate. 201For NFS, either the 202.Xr exports 5 203option 204.Fl tlscert 205or 206.Fl tlscertuser 207may be used to require a client to provide a certificate 208that verifies. 209See 210.Xr exports 5 . 211.It Fl n Ar domain , Fl Fl domain= Ns Ar domain 212This option specifies what the 213.Dq domain 214is for use with the 215.Fl u 216option, overriding the domain taken from the 217.Xr gethostname 2 218of the server this daemon is running on. 219If you have specified the 220.Fl domain 221command line option for 222.Xr nfsuserd 8 223then you should specify this option with the same 224.Dq domain 225that was specified for 226.Xr nfsuserd 8 . 227This option is only meaningful when used with the 228.Fl u 229option. 230.It Fl p Ar CApath , Fl Fl verifydir= Ns Ar CApath 231This option is similar to the 232.Fl l 233option, but specifies the path of a directory with CA 234certificates in it. 235When this option is used, 236.Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file()) 237is not called, so a list of CA names might not be passed 238to the client during the TLS handshake. 239.It Fl r Ar CRLfile , Fl Fl crl= Ns Ar CRLfile 240This option specifies a Certificate Revocation List (CRL) file 241that is to be loaded into the verify certificate store and 242checked during verification. 243This option is only meaningful when either the 244.Fl l 245or 246.Fl p 247have been specified. 248.It Fl u , Fl Fl certuser 249This option specifies that if the client provides a certificate 250that both verifies and has a subjectAltName with an otherName 251component of the form 252.Dq otherName:1.3.6.1.4.1.2238.1.1.1;UTF8:user@domain 253where 254.Dq domain 255matches the one for this server, 256then the daemon will attempt to map 257.Dq user 258in the above 259to a user credential <uid, gid_list>. 260There should only be one of these otherName components for each 261.Dq domain . 262If 263.Dq user 264is a valid username in the password database, 265then the <uid, gid_list> for 266.Dq user 267will be used for all 268RPCs on the mount instead of the credentials in the RPC request 269header. 270This option requires the 271.Fl m 272and either the 273.Fl l 274or 275.Fl p 276options. 277Use of this option might not conform to RFC-NNNN, which does 278not allow certificates to be used for user authentication. 279.It Fl v , Fl Fl verbose 280Run in verbose mode. 281In this mode, 282.Nm 283will log activity messages to 284.Xr syslogd 8 285using LOG_INFO | LOG_DAEMON or to 286stderr, if the 287.Fl d 288option has also been specified. 289.It Fl W , Fl Fl multiwild 290This option is used with the 291.Fl h 292option to allow use of a wildcard 293.Dq * 294that matches multiple 295components of the reverse DNS name for the client's IP 296address. 297For example, the FQDN 298.Dq *.uoguelph.ca 299would match both 300.Dq laptop21.uoguelph.ca 301and 302.Dq laptop3.cis.uoguelph.ca . 303.It Fl w , Fl Fl singlewild 304Similar to 305.Fl W 306but allows the wildcard 307.Dq * 308to match a single component of the reverse DNS name. 309For example, the FQDN 310.Dq *.uoguelph.ca 311would match 312.Dq laptop21.uoguelph.ca 313but not 314.Dq laptop3.cis.uoguelph.ca . 315Only one of the 316.Fl W 317and 318.Fl w 319options is allowed. 320.El 321.Sh EXIT STATUS 322.Ex -std 323.Sh SEE ALSO 324.Xr openssl 1 , 325.Xr ktls 4 , 326.Xr exports 5 , 327.Xr mount_nfs 8 , 328.Xr nfsuserd 8 , 329.Xr rpc.tlsclntd 8 , 330.Xr syslogd 8 331.Sh STANDARDS 332The implementation is based on the specification in 333.Rs 334.%B "RFC NNNN" 335.%T "Towards Remote Procedure Call Encryption By Default" 336.Re 337.Sh HISTORY 338The 339.Nm 340manual page first appeared in 341.Fx 13.0 . 342.Sh BUGS 343This daemon cannot be safely shut down and restarted if there are 344any active RPC-over-TLS connections. 345Doing so will orphan the KERNEL_TLS connections, so that they 346can no longer do upcalls successfully, since the 347.Dq SSL * 348structures in userspace have been lost. 349