123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388 |
- .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/
- .\" Authors: Doug Rabson <dfr@rabson.org>
- .\" Developed with Red Inc: Alfred Perlstein <alfred@FreeBSD.org>
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .\" Modified from gssd.8 for rpc.tlsservd.8 by Rick Macklem.
- .Dd November 10, 2022
- .Dt RPC.TLSSERVD 8
- .Os
- .Sh NAME
- .Nm rpc.tlsservd
- .Nd "Sun RPC over TLS Server Daemon"
- .Sh SYNOPSIS
- .Nm
- .Op Fl 2
- .Op Fl C Ar available_ciphers
- .Op Fl D Ar certdir
- .Op Fl d
- .Op Fl h
- .Op Fl l Ar CAfile
- .Op Fl m
- .Op Fl N Ar num_servers
- .Op Fl n Ar domain
- .Op Fl p Ar CApath
- .Op Fl r Ar CRLfile
- .Op Fl u
- .Op Fl v
- .Op Fl W
- .Op Fl w
- .Sh DESCRIPTION
- The
- .Nm
- program provides support for the server side of the kernel Sun RPC over TLS
- implementation.
- This daemon must be running to allow the kernel RPC to perform the TLS
- handshake after a TCP client has sent the STARTTLS Null RPC request to
- the server.
- This daemon requires that the kernel be built with
- .Dq options KERNEL_TLS
- and be running on an architecture such as
- .Dq amd64
- that supports a direct map (not i386) with
- .Xr ktls 4
- enabled.
- Note that the
- .Fl tls
- option in the
- .Xr exports 5
- file specifies that the client must use RPC over TLS.
- The
- .Fl tlscert
- option in the
- .Xr exports 5
- file specifies that the client must provide a certificate
- that verifies.
- The
- .Fl tlscertuser
- option in the
- .Xr exports 5
- file specifies that the client must provide a certificate
- that verifies and has a otherName:1.3.6.1.4.1.2238.1.1.1;UTF8: field of
- subjectAltName of the form
- .Dq user@domain
- where
- .Dq domain
- matches the one for this server and
- .Dq user
- is a valid user name that maps to a <uid, gid_list>.
- For the latter two cases, the
- .Fl m
- and either the
- .Fl l
- or
- .Fl p
- options must be specified.
- The
- .Fl tlscertuser
- option also requires that the
- .Fl u
- option on this daemon be specified.
- .Pp
- Also, if the IP address used by the client cannot be trusted,
- the rules in
- .Xr exports 5
- cannot be applied safely.
- As such, the
- .Fl h
- option can be used along with
- .Fl m
- and either the
- .Fl l
- or
- .Fl p
- options to require that the client certificate have the correct
- Fully Qualified Domain Name (FQDN) in it.
- .Pp
- A certificate and associated key must exist in /etc/rpc.tlsservd
- (or the
- .Dq certdir
- specified by the
- .Fl D
- option)
- in files named
- .Dq cert.pem
- and
- .Dq certkey.pem .
- .Pp
- If a SIGHUP signal is sent to the daemon it will reload the
- .Dq CRLfile
- and will shut down any extant connections that presented certificates
- during TLS handshake that have been revoked.
- If the
- .Fl r
- option was not specified, the SIGHUP signal will be ignored.
- .Pp
- The daemon will log failed certificate verifications via
- .Xr syslogd 8
- using LOG_INFO | LOG_DAEMON when the
- .Fl m
- option has been specified.
- .Pp
- The options are as follows:
- .Bl -tag -width indent
- .It Fl 2 , Fl Fl allowtls1_2
- Permit clients to mount using TLS version 1.2.
- By default, the daemon will only allow mounts
- using TLS version 1.3, as required by the RFC.
- However, early
- .Fx
- .Pq 13.0 and 13.1
- clients require
- this option, since they use TLS version 1.2.
- .It Fl C Ar available_ciphers , Fl Fl ciphers= Ns Ar available_ciphers
- Specify which ciphers are available during TLS handshake.
- If this option is specified,
- .Dq SSL_CTX_set_ciphersuites()
- will be called with
- .Dq available_ciphers
- as the argument.
- If this option is not specified, the cipher will be chosen by
- .Xr ssl 7 ,
- which should be adequate for most cases.
- The format for the available ciphers is a simple
- .So
- :
- .Sc
- separated list, in order of preference.
- The command
- .Dq openssl ciphers -s -tls1_3
- lists available ciphers.
- .It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir
- Use
- .Dq certdir
- instead of /etc/rpc.tlsservd as the location for the
- certificate in a file called
- .Dq cert.pem
- and associated key in
- .Dq certkey.pem .
- .It Fl d , Fl Fl debuglevel
- Run in debug mode.
- In this mode,
- .Nm
- will not fork when it starts.
- .It Fl h , Fl Fl checkhost
- This option specifies that the client must provide a certificate
- that both verifies and has a FQDN that matches the reverse
- DNS name for the IP address that
- the client uses to connect to the server.
- The FQDN should be
- in the DNS field of the subjectAltName, but is also allowed
- to be in the CN field of the
- subjectName in the certificate.
- By default, a wildcard "*" in the FQDN is not allowed.
- With this option, a failure to verify the client certificate
- or match the FQDN will result in the
- server sending AUTH_REJECTEDCRED replies to all client RPCs.
- This option requires the
- .Fl m
- and either the
- .Fl l
- or
- .Fl p
- options.
- .It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile
- This option specifies the path name of a CA certificate(s) file
- in pem format, which is used to verify client certificates and to
- set the list of CA(s) sent to the client so that it knows which
- certificate to send to the server during the TLS handshake.
- This path name is used in
- .Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL)
- and
- .Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file(CAfile))
- openssl library calls.
- Note that this is a path name for the file and is not assumed to be
- in
- .Dq certdir .
- Either this option or the
- .Fl p
- option must be specified when the
- .Fl m
- option is specified so that the daemon can verify the client's
- certificate.
- .It Fl m , Fl Fl mutualverf
- This option specifies that the server is to request a certificate
- from the client during the TLS handshake.
- It does not require that the client provide a certificate.
- It should be specified unless no client doing RPC over TLS is
- required to have a certificate.
- For NFS, either the
- .Xr exports 5
- option
- .Fl tlscert
- or
- .Fl tlscertuser
- may be used to require a client to provide a certificate
- that verifies.
- See
- .Xr exports 5 .
- .It Fl N Ar num_servers , Fl Fl numdaemons= Ns Ar num_servers
- For a server with a large number of NFS-over-TLS client mounts,
- this daemon might get overloaded after a reboot, when many
- clients attempt to do a TLS handshake at the same time.
- This option may be used to specify that
- .Dq num_servers
- daemons are to be run instead of a single daemon.
- When this is done, the TLS handshakes are spread across the
- .Dq num_servers
- daemons in a round robin fashion to spread out the load.
- .It Fl n Ar domain , Fl Fl domain= Ns Ar domain
- This option specifies what the
- .Dq domain
- is for use with the
- .Fl u
- option, overriding the domain taken from the
- .Xr gethostname 2
- of the server this daemon is running on.
- If you have specified the
- .Fl domain
- command line option for
- .Xr nfsuserd 8
- then you should specify this option with the same
- .Dq domain
- that was specified for
- .Xr nfsuserd 8 .
- This option is only meaningful when used with the
- .Fl u
- option.
- .It Fl p Ar CApath , Fl Fl verifydir= Ns Ar CApath
- This option is similar to the
- .Fl l
- option, but specifies the path of a directory with CA
- certificates in it.
- When this option is used,
- .Dq SSL_CTX_set_client_CA_list(ctx,SSL_load_client_CA_file())
- is not called, so a list of CA names might not be passed
- to the client during the TLS handshake.
- .It Fl r Ar CRLfile , Fl Fl crl= Ns Ar CRLfile
- This option specifies a Certificate Revocation List (CRL) file
- that is to be loaded into the verify certificate store and
- checked during verification.
- This option is only meaningful when either the
- .Fl l
- or
- .Fl p
- have been specified.
- .It Fl u , Fl Fl certuser
- This option specifies that if the client provides a certificate
- that both verifies and has a subjectAltName with an otherName
- component of the form
- .Dq otherName:1.3.6.1.4.1.2238.1.1.1;UTF8:user@domain
- where
- .Dq domain
- matches the one for this server,
- then the daemon will attempt to map
- .Dq user
- in the above
- to a user credential <uid, gid_list>.
- There should only be one of these otherName components for each
- .Dq domain .
- If
- .Dq user
- is a valid username in the password database,
- then the <uid, gid_list> for
- .Dq user
- will be used for all
- RPCs on the mount instead of the credentials in the RPC request
- header.
- This option requires the
- .Fl m
- and either the
- .Fl l
- or
- .Fl p
- options.
- Use of this option might not conform to RFC-9289, which does
- not allow certificates to be used for user authentication.
- .It Fl v , Fl Fl verbose
- Run in verbose mode.
- In this mode,
- .Nm
- will log activity messages to
- .Xr syslogd 8
- using LOG_INFO | LOG_DAEMON or to
- stderr, if the
- .Fl d
- option has also been specified.
- .It Fl W , Fl Fl multiwild
- This option is used with the
- .Fl h
- option to allow use of a wildcard
- .Dq *
- that matches multiple
- components of the reverse DNS name for the client's IP
- address.
- For example, the FQDN
- .Dq *.uoguelph.ca
- would match both
- .Dq laptop21.uoguelph.ca
- and
- .Dq laptop3.cis.uoguelph.ca .
- .It Fl w , Fl Fl singlewild
- Similar to
- .Fl W
- but allows the wildcard
- .Dq *
- to match a single component of the reverse DNS name.
- For example, the FQDN
- .Dq *.uoguelph.ca
- would match
- .Dq laptop21.uoguelph.ca
- but not
- .Dq laptop3.cis.uoguelph.ca .
- Only one of the
- .Fl W
- and
- .Fl w
- options is allowed.
- .El
- .Sh EXIT STATUS
- .Ex -std
- .Sh SEE ALSO
- .Xr openssl 1 ,
- .Xr ktls 4 ,
- .Xr exports 5 ,
- .Xr ssl 7 ,
- .Xr mount_nfs 8 ,
- .Xr nfsuserd 8 ,
- .Xr rpc.tlsclntd 8 ,
- .Xr syslogd 8
- .Sh STANDARDS
- The implementation is based on the specification in
- .Rs
- .%B "RFC 9289"
- .%T "Towards Remote Procedure Call Encryption By Default"
- .Re
- .Sh HISTORY
- The
- .Nm
- manual page first appeared in
- .Fx 13.0 .
- .Sh BUGS
- This daemon cannot be safely shut down and restarted if there are
- any active RPC-over-TLS connections.
- Doing so will orphan the KERNEL_TLS connections, so that they
- can no longer do upcalls successfully, since the
- .Dq SSL *
- structures in userspace have been lost.
|