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