Index: projects/nfs-over-tls/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 =================================================================== --- projects/nfs-over-tls/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 (revision 365826) +++ projects/nfs-over-tls/usr.sbin/rpc.tlsclntd/rpc.tlsclntd.8 (revision 365827) @@ -1,178 +1,184 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" 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. .\" .\" $FreeBSD$ .\" .\" Modified from gssd.8 for rpc.tlsclntd.8 by Rick Macklem. -.Dd September 3, 2020 +.Dd September 16, 2020 .Dt RPC.TLSCLNTD 8 .Os .Sh NAME .Nm rpc.tlsclntd .Nd "Sun RPC over TLS Client Daemon" .Sh SYNOPSIS .Nm .Op Fl D Ar certdir .Op Fl d .Op Fl l Ar CAfile .Op Fl m .Op Fl p Ar CApath .Op Fl r Ar CRLfile .Op Fl v .Sh DESCRIPTION The .Nm program provides support for the client side of the kernel Sun RPC over TLS implementation. This daemon must be running for the kernel RPC to be able to do a TLS connection to a server for an NFS over TLS mount. 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). .Pp If either of the .Fl l or .Fl p options have been specified, the daemon will require the server's certificate to verify and have a Fully Qualified Domain Name (FQDN) in it. This FQDN must match the reverse DNS name for the IP address that the server is using for the TCP connection. The FQDN may be in either the DNS field of the subjectAltName or the CN field of the subjectName in the certificate and cannot have a wildcard .Dq * in it. .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 l or .Fl p option has been specified. .Pp The options are as follows: .Bl -tag -width indent .It Fl D Ar certdir , Fl Fl certdir= Ns Ar certdir Use .Dq certdir instead of /etc/rpc.tlsclntd for the .Fl m option. .It Fl d , Fl Fl debuglevel Run in debug mode. In this mode, .Nm will not fork when it starts. .It Fl l Ar CAfile , Fl Fl verifylocs= Ns Ar CAfile This specifies the path name of a CAfile which holds the information for server certificate verification. This path name is used in .Dq SSL_CTX_load_verify_locations(ctx,CAfile,NULL) and .Dq SSL_CTX_set0_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 . .It Fl m , Fl Fl mutualverf Enable support for mutual authentication. A certificate and associated key must be found in /etc/rpc.tlsclntd (or the directory specified by the .Fl D option) in case a server requests a peer certificate. The certificate needs to be in a file named .Dq cert.pem and the key in a file named .Dq key.pem . If there is a passphrase on the .Dq key.pem file, this daemon will prompt for the passphrase during startup. .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_set0_CA_list(ctx,SSL_load_client_CA_file()) is not called, so a list of CA names is not be passed to the server during the TLS handshake. The openssl documentation indicates this call is rarely needed. (However, I was not able to determine if/when this matters, so if in doubt, use the .Fl l option instead of this option.) .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 of the server's certificate. This option is meaningless unless either the .Fl l or .Fl p have been specified. .It Fl v , Fl Fl verbose Run in verbose mode. In this mode, .Nm will log activity messages to syslog using LOG_INFO | LOG_DAEMON or to stderr, if the .Fl d option has also been specified. .El .Sh EXIT STATUS .Ex -std .Sh SEE ALSO .Xr openssl 1 , .Xr mount_nfs 8 , .Xr rpc.tlsservd 8 , .Xr syslogd 8 +.Sh STANDARDS +The implementation is based on the specification in +.Rs +.%B "RFC NNNN" +.%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. -.Sh HISTORY -The -.Nm -manual page first appeared in -.Fx 13.0 . Index: projects/nfs-over-tls/usr.sbin/rpc.tlsservd/rpc.tlsservd.8 =================================================================== --- projects/nfs-over-tls/usr.sbin/rpc.tlsservd/rpc.tlsservd.8 (revision 365826) +++ projects/nfs-over-tls/usr.sbin/rpc.tlsservd/rpc.tlsservd.8 (revision 365827) @@ -1,334 +1,340 @@ .\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/ .\" Authors: Doug Rabson .\" Developed with Red Inc: Alfred Perlstein .\" .\" 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. .\" .\" $FreeBSD$ .\" .\" Modified from gssd.8 for rpc.tlsservd.8 by Rick Macklem. -.Dd September 3, 2020 +.Dd September 16, 2020 .Dt RPC.TLSSERVD 8 .Os .Sh NAME .Nm rpc.tlsservd .Nd "Sun RPC over TLS Server Daemon" .Sh SYNOPSIS .Nm .Op Fl D Ar certdir .Op Fl d .Op Fl h .Op Fl l Ar CAfile .Op Fl m .Op Fl n Ar domain_name .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). 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@dns_domain that maps to a . 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 key.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 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 key in .Dq key.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 export 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 domain_name , Fl Fl domain= Ns Ar domain_name This option specifies what the .Dq domain_name is for use with the .Fl u option, overriding the domain_name 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_name that was specified for .Xr nfsuserd 8 . .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. (I was not able to determine if/when this matters, but if in doubt, use the .Fl l option instead of this option.) .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 meaningless unless 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 of the form .Dq otherName:1.3.6.1.4.1.2238.1.1.1;UTF8:user@dns_domain the daemon will attempt to map .Dq user@dns_domain in the above to a . The mapping of .Dq user@dns_domain is done in the same manner as the .Xr nfsuserd 8 daemon, where .Dq dns_domain is the domain of the NFS server (or the one set via the .Fl n option) and .Dq user is a valid username in the password database. If this mapping is successful, then the 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 does not conform to RFC-X, 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 exports 5 , .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 NNNN" +.%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. -.Sh HISTORY -The -.Nm -manual page first appeared in -.Fx 13.0 .