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