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