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