[v1,4/4] exports.man: Add description of xprtsec= to exports(5)

Commit Message

Chuck Lever March 20, 2023, 2:35 p.m. UTC

From: Chuck Lever <[e-mail]>

Signed-off-by: Chuck Lever <[e-mail]>
---
 utils/exportfs/exports.man |   45 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

Comments

Jeff Layton March 21, 2023, 12:06 p.m. UTC | #1

On Mon, 2023-03-20 at 10:35 -0400, Chuck Lever wrote:
> From: Chuck Lever <[e-mail]>
> 
> Signed-off-by: Chuck Lever <[e-mail]>
> ---
>  utils/exportfs/exports.man |   45 +++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 44 insertions(+), 1 deletion(-)
> 
> diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
> index 54b3f8776ea6..cca9bb7b4aeb 100644
> --- a/utils/exportfs/exports.man
> +++ b/utils/exportfs/exports.man
> @@ -125,7 +125,49 @@ In that case you may include multiple sec= options, and following options
>  will be enforced only for access using flavors listed in the immediately
>  preceding sec= option.  The only options that are permitted to vary in
>  this way are ro, rw, no_root_squash, root_squash, and all_squash.
> +.SS Transport layer security
> +The Linux NFS server supports the use of transport layer security to
> +protect RPC traffic between itself and its clients.
> +This can be in the form of a VPN, an ssh tunnel, or via RPC-with-TLS,
> +which uses TLSv1.3.

This is a little awkward, as the NFS server really isn't involved at all
at that level in the case of a VPN or ssh tunnel. How about:

The Linux NFS server supports transport layer security (TLS) to protect
RPC traffic between itself and its clients via RPC-with-TLS which uses
TLSv1.3. Alternately, RPC traffic can be secured via a VPN, ssh tunnel
or similar mechanism that encrypts traffic in a way that is transparent
to the server.

>  .PP
> +Administrators may choose to require the use of
> +RPC-with-TLS to protect access to individual exports.
> +This is particularly useful when using non-cryptographic security
> +flavors such as
> +.IR sec=sys .
> +The
> +.I xprtsec=
> +option, followed by a colon-delimited list of security policies,
> +can restrict access to the export to only clients that have negotiated
> +transport-layer security.
> +Currently supported transport layer security policies include:
> +.TP
> +.IR none
> +The server permits clients to access the export
> +without the use of transport layer security.
> +.TP
> +.IR tls
> +The server permits clients that have negotiated an RPC-with-TLS session
> +without peer authentication (confidentiality only) to access the export.
> +Clients are not required to offer an x.509 certificate
> +when establishing a transport layer security session.
> +.TP
> +.IR mtls
> +The server permits clients that have negotiated an RPC-with-TLS session
> +with peer authentication to access the export.
> +The server requires clients to offer an x.509 certificate
> +when establishing a transport layer security session.
> +.PP
> +The default setting is
> +.IR xprtsec=none:tls:mtls .

Shouldn't that list order be reversed? IOW, shouldn't we default to mtls
first since it's more secure?

It might also be good to spell out what the kernel does with an ordered
list here. In what order are these methods attempted and at what point
does the server give up?


> +This is also known as "opportunistic mode".
> +The server permits clients to use any transport layer security mechanism
> +to access the export.
> +.PP
> +The server administrator must install and configure
> +.BR tlshd
> +to handle transport layer security handshake requests from the local kernel.

In the event that tlshd isn't running, what happens? I assume we give up
on TLS at that point, but how long does it take for the kernel to
realize that it's not there?

>  .SS General Options
>  .BR exportfs
>  understands the following export options:
> @@ -581,7 +623,8 @@ a character class wildcard match.
>  .BR netgroup (5),
>  .BR mountd (8),
>  .BR nfsd (8),
> -.BR showmount (8).
> +.BR showmount (8),
> +.BR tlshd (8).
>  .\".SH DIAGNOSTICS
>  .\"An error parsing the file is reported using syslogd(8) as level NOTICE from
>  .\"a DAEMON whenever
> 
>

Chuck Lever March 21, 2023, 2:08 p.m. UTC | #2

> On Mar 21, 2023, at 8:06 AM, Jeff Layton <[e-mail]> wrote:
> 
> On Mon, 2023-03-20 at 10:35 -0400, Chuck Lever wrote:
>> From: Chuck Lever <[e-mail]>
>> 
>> Signed-off-by: Chuck Lever <[e-mail]>
>> ---
>> utils/exportfs/exports.man |   45 +++++++++++++++++++++++++++++++++++++++++++-
>> 1 file changed, 44 insertions(+), 1 deletion(-)
>> 
>> diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
>> index 54b3f8776ea6..cca9bb7b4aeb 100644
>> --- a/utils/exportfs/exports.man
>> +++ b/utils/exportfs/exports.man
>> @@ -125,7 +125,49 @@ In that case you may include multiple sec= options, and following options
>> will be enforced only for access using flavors listed in the immediately
>> preceding sec= option.  The only options that are permitted to vary in
>> this way are ro, rw, no_root_squash, root_squash, and all_squash.
>> +.SS Transport layer security
>> +The Linux NFS server supports the use of transport layer security to
>> +protect RPC traffic between itself and its clients.
>> +This can be in the form of a VPN, an ssh tunnel, or via RPC-with-TLS,
>> +which uses TLSv1.3.
> 
> This is a little awkward, as the NFS server really isn't involved at all
> at that level in the case of a VPN or ssh tunnel. How about:
> 
> The Linux NFS server supports transport layer security (TLS) to protect
> RPC traffic between itself and its clients via RPC-with-TLS which uses
> TLSv1.3. Alternately, RPC traffic can be secured via a VPN, ssh tunnel
> or similar mechanism that encrypts traffic in a way that is transparent
> to the server.

Sure, that expresses what I was after.


>> .PP
>> +Administrators may choose to require the use of
>> +RPC-with-TLS to protect access to individual exports.
>> +This is particularly useful when using non-cryptographic security
>> +flavors such as
>> +.IR sec=sys .
>> +The
>> +.I xprtsec=
>> +option, followed by a colon-delimited list of security policies,
>> +can restrict access to the export to only clients that have negotiated
>> +transport-layer security.
>> +Currently supported transport layer security policies include:
>> +.TP
>> +.IR none
>> +The server permits clients to access the export
>> +without the use of transport layer security.
>> +.TP
>> +.IR tls
>> +The server permits clients that have negotiated an RPC-with-TLS session
>> +without peer authentication (confidentiality only) to access the export.
>> +Clients are not required to offer an x.509 certificate
>> +when establishing a transport layer security session.
>> +.TP
>> +.IR mtls
>> +The server permits clients that have negotiated an RPC-with-TLS session
>> +with peer authentication to access the export.
>> +The server requires clients to offer an x.509 certificate
>> +when establishing a transport layer security session.
>> +.PP
>> +The default setting is
>> +.IR xprtsec=none:tls:mtls .
> 
> Shouldn't that list order be reversed? IOW, shouldn't we default to mtls
> first since it's more secure?
> 
> It might also be good to spell out what the kernel does with an ordered
> list here. In what order are these methods attempted and at what point
> does the server give up?

There's no order to this list. It's simply a list of
transport layer security settings that the server will
permit clients to use on this transport.

The "ordered list" concept is from the MNT protocol.
For xprtsec, there's no communication or negotiation
of preferences with clients.


>> +This is also known as "opportunistic mode".
>> +The server permits clients to use any transport layer security mechanism
>> +to access the export.
>> +.PP
>> +The server administrator must install and configure
>> +.BR tlshd
>> +to handle transport layer security handshake requests from the local kernel.
> 
> In the event that tlshd isn't running, what happens? I assume we give up
> on TLS at that point, but how long does it take for the kernel to
> realize that it's not there?

If tlshd is not running, the handshake request fails immediately.
There's no timeout needed thanks to netlink multi-cast.


>> .SS General Options
>> .BR exportfs
>> understands the following export options:
>> @@ -581,7 +623,8 @@ a character class wildcard match.
>> .BR netgroup (5),
>> .BR mountd (8),
>> .BR nfsd (8),
>> -.BR showmount (8).
>> +.BR showmount (8),
>> +.BR tlshd (8).
>> .\".SH DIAGNOSTICS
>> .\"An error parsing the file is reported using syslogd(8) as level NOTICE from
>> .\"a DAEMON whenever
>> 
>> 
> 
> -- 
> Jeff Layton <[e-mail]>

--
Chuck Lever

Jeff Layton March 21, 2023, 3:11 p.m. UTC | #3

On Tue, 2023-03-21 at 14:08 +0000, Chuck Lever III wrote:
> 
> > On Mar 21, 2023, at 8:06 AM, Jeff Layton <[e-mail]> wrote:
> > 
> > On Mon, 2023-03-20 at 10:35 -0400, Chuck Lever wrote:
> > > From: Chuck Lever <[e-mail]>
> > > 
> > > Signed-off-by: Chuck Lever <[e-mail]>
> > > ---
> > > utils/exportfs/exports.man |   45 +++++++++++++++++++++++++++++++++++++++++++-
> > > 1 file changed, 44 insertions(+), 1 deletion(-)
> > > 
> > > diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
> > > index 54b3f8776ea6..cca9bb7b4aeb 100644
> > > --- a/utils/exportfs/exports.man
> > > +++ b/utils/exportfs/exports.man
> > > @@ -125,7 +125,49 @@ In that case you may include multiple sec= options, and following options
> > > will be enforced only for access using flavors listed in the immediately
> > > preceding sec= option.  The only options that are permitted to vary in
> > > this way are ro, rw, no_root_squash, root_squash, and all_squash.
> > > +.SS Transport layer security
> > > +The Linux NFS server supports the use of transport layer security to
> > > +protect RPC traffic between itself and its clients.
> > > +This can be in the form of a VPN, an ssh tunnel, or via RPC-with-TLS,
> > > +which uses TLSv1.3.
> > 
> > This is a little awkward, as the NFS server really isn't involved at all
> > at that level in the case of a VPN or ssh tunnel. How about:
> > 
> > The Linux NFS server supports transport layer security (TLS) to protect
> > RPC traffic between itself and its clients via RPC-with-TLS which uses
> > TLSv1.3. Alternately, RPC traffic can be secured via a VPN, ssh tunnel
> > or similar mechanism that encrypts traffic in a way that is transparent
> > to the server.
> 
> Sure, that expresses what I was after.
> 
> 
> > > .PP
> > > +Administrators may choose to require the use of
> > > +RPC-with-TLS to protect access to individual exports.
> > > +This is particularly useful when using non-cryptographic security
> > > +flavors such as
> > > +.IR sec=sys .
> > > +The
> > > +.I xprtsec=
> > > +option, followed by a colon-delimited list of security policies,
> > > +can restrict access to the export to only clients that have negotiated
> > > +transport-layer security.
> > > +Currently supported transport layer security policies include:
> > > +.TP
> > > +.IR none
> > > +The server permits clients to access the export
> > > +without the use of transport layer security.
> > > +.TP
> > > +.IR tls
> > > +The server permits clients that have negotiated an RPC-with-TLS session
> > > +without peer authentication (confidentiality only) to access the export.
> > > +Clients are not required to offer an x.509 certificate
> > > +when establishing a transport layer security session.
> > > +.TP
> > > +.IR mtls
> > > +The server permits clients that have negotiated an RPC-with-TLS session
> > > +with peer authentication to access the export.
> > > +The server requires clients to offer an x.509 certificate
> > > +when establishing a transport layer security session.
> > > +.PP
> > > +The default setting is
> > > +.IR xprtsec=none:tls:mtls .
> > 
> > Shouldn't that list order be reversed? IOW, shouldn't we default to mtls
> > first since it's more secure?
> > 
> > It might also be good to spell out what the kernel does with an ordered
> > list here. In what order are these methods attempted and at what point
> > does the server give up?
> 
> There's no order to this list. It's simply a list of
> transport layer security settings that the server will
> permit clients to use on this transport.
> 
> The "ordered list" concept is from the MNT protocol.
> For xprtsec, there's no communication or negotiation
> of preferences with clients.
> 

Duh, of course. That makes sense.

> 
> > > +This is also known as "opportunistic mode".
> > > +The server permits clients to use any transport layer security mechanism
> > > +to access the export.
> > > +.PP
> > > +The server administrator must install and configure
> > > +.BR tlshd
> > > +to handle transport layer security handshake requests from the local kernel.
> > 
> > In the event that tlshd isn't running, what happens? I assume we give up
> > on TLS at that point, but how long does it take for the kernel to
> > realize that it's not there?
> 
> If tlshd is not running, the handshake request fails immediately.
> There's no timeout needed thanks to netlink multi-cast.
> 

Good, thanks!

> 
> > > .SS General Options
> > > .BR exportfs
> > > understands the following export options:
> > > @@ -581,7 +623,8 @@ a character class wildcard match.
> > > .BR netgroup (5),
> > > .BR mountd (8),
> > > .BR nfsd (8),
> > > -.BR showmount (8).
> > > +.BR showmount (8),
> > > +.BR tlshd (8).
> > > .\".SH DIAGNOSTICS
> > > .\"An error parsing the file is reported using syslogd(8) as level NOTICE from
> > > .\"a DAEMON whenever
> > > 
> > > 
> > 
> > -- 
> > Jeff Layton <[e-mail]>
> 
> --
> Chuck Lever
> 
>

Patch

diff --git a/utils/exportfs/exports.man b/utils/exportfs/exports.man
index 54b3f8776ea6..cca9bb7b4aeb 100644
--- a/utils/exportfs/exports.man
+++ b/utils/exportfs/exports.man
@@ -125,7 +125,49 @@  In that case you may include multiple sec= options, and following options
 will be enforced only for access using flavors listed in the immediately
 preceding sec= option.  The only options that are permitted to vary in
 this way are ro, rw, no_root_squash, root_squash, and all_squash.
+.SS Transport layer security
+The Linux NFS server supports the use of transport layer security to
+protect RPC traffic between itself and its clients.
+This can be in the form of a VPN, an ssh tunnel, or via RPC-with-TLS,
+which uses TLSv1.3.
 .PP
+Administrators may choose to require the use of
+RPC-with-TLS to protect access to individual exports.
+This is particularly useful when using non-cryptographic security
+flavors such as
+.IR sec=sys .
+The
+.I xprtsec=
+option, followed by a colon-delimited list of security policies,
+can restrict access to the export to only clients that have negotiated
+transport-layer security.
+Currently supported transport layer security policies include:
+.TP
+.IR none
+The server permits clients to access the export
+without the use of transport layer security.
+.TP
+.IR tls
+The server permits clients that have negotiated an RPC-with-TLS session
+without peer authentication (confidentiality only) to access the export.
+Clients are not required to offer an x.509 certificate
+when establishing a transport layer security session.
+.TP
+.IR mtls
+The server permits clients that have negotiated an RPC-with-TLS session
+with peer authentication to access the export.
+The server requires clients to offer an x.509 certificate
+when establishing a transport layer security session.
+.PP
+The default setting is
+.IR xprtsec=none:tls:mtls .
+This is also known as "opportunistic mode".
+The server permits clients to use any transport layer security mechanism
+to access the export.
+.PP
+The server administrator must install and configure
+.BR tlshd
+to handle transport layer security handshake requests from the local kernel.
 .SS General Options
 .BR exportfs
 understands the following export options:
@@ -581,7 +623,8 @@  a character class wildcard match.
 .BR netgroup (5),
 .BR mountd (8),
 .BR nfsd (8),
-.BR showmount (8).
+.BR showmount (8),
+.BR tlshd (8).
 .\".SH DIAGNOSTICS
 .\"An error parsing the file is reported using syslogd(8) as level NOTICE from
 .\"a DAEMON whenever