usr.sbin/rpc.tlsservd/rpc.tlsservd.8

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