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