Re: [PATCH v1] man: Update nfs(5) and rpc.gssd(8) discussion of keytab needs

[Steve Dickson <SteveD@RedHat.com>]

On 5/21/20 2:25 PM, Chuck Lever wrote:
> Because of the <anyname> wildcard feature in rpc.gssd, it's possible
> for a customer to deploy the same keytab on many of her NFSv4 clients
> to reduce the overhead of keytab distribution.
> 
> However, the practice of sharing the same service principal amongst
> NFSv4 clients brings with it some hazards. Add documentation of those
> exposures in our man pages.
> 
> The rpc.gssd(8) changes:
> - Remove some needless redundancy
> - Clarify the definition of "machine credentials"
> - Update the use of <anyname> to explicitly not recommend sharing
> service principals
> 
> The nfs(5) changes add two things:
> - A brief discussion of the primary security exposure of sharing
> service principals
> - A mention of the nfs4.nfs_unique_id module parameter
> 
> Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
Committed... (tag: nfs-utils-2-4-4-rc6)

steved.
> ---
>  utils/mount/nfs.man |   53 +++++++++++++++++++++++++++------------------------
>  1 file changed, 28 insertions(+), 25 deletions(-)
> 
> diff --git a/utils/gssd/gssd.man b/utils/gssd/gssd.man
> index cc3a210ab81e..3ec286b43c4d 100644
> --- a/utils/gssd/gssd.man
> +++ b/utils/gssd/gssd.man
> @@ -45,22 +45,20 @@ is known as a
>  .BR kerberos (1)
>  for more on principals).
>  .P
> -For certain operations, a credential is required
> -which represents no user,
> -is otherwise unprivileged,
> -and is always available.
> -This is referred to as a
> +Certain operations require a credential that
> +represents no particular user
> +or
> +represents the host itself.
> +This kind of credential is called a
>  .IR "machine credential" .
>  .P
> -Machine credentials are typically established using a
> -.IR "service principal" ,
> -whose encrypted password, called its
> -.IR key ,
> -is stored in a file, called a
> -.IR keytab ,
> -to avoid requiring a user prompt.
> -A machine credential effectively does not expire because the system
> -can renew it as needed without user intervention.
> +A host establishes its machine credential using a
> +.I "service principal"
> +whose encrypted password is stored in a local file known as a
> +.IR keytab .
> +A machine credential remains effective
> +without user intervention
> +as long as the host can renew it.
>  .P
>  Once obtained, credentials are typically stored in local temporary files
>  with well-known pathnames.
> @@ -93,30 +91,12 @@ See the description of the
>  .B -d
>  option for details.
>  .SS Machine Credentials
> -A user credential is established by a user and
> -is then shared with the kernel and
> -.BR rpc.gssd .
> -A machine credential is established by
> -.B rpc.gssd
> -for the kernel when there is no user.
> -Therefore
> -.B rpc.gssd
> -must already have the materials on hand to establish this credential
> -without requiring user intervention.
> -.P
> -.B rpc.gssd
> -searches the local system's keytab for a principal and key to use
> -to establish the machine credential.
> -By default,
> -.B rpc.gssd
> -assumes the file
> -.I /etc/krb5.keytab
> -contains principals and keys that can be used to obtain machine credentials.
> -.P
>  .B rpc.gssd
> -searches in the following order for a principal to use.
> -The first matching credential is used.
> -For the search, <hostname> and <REALM> are replaced with the local
> +searches the default keytab,
> +.IR /etc/krb5.keytab ,
> +in the following order for a principal and password to use
> +when establishing the machine credential.
> +For the search, rpc.gssd replaces <hostname> and <REALM> with the local
>  system's hostname and Kerberos realm.
>  .sp
>     <HOSTNAME>$@<REALM>
> @@ -133,15 +113,20 @@ system's hostname and Kerberos realm.
>  .br
>     host/<anyname>@<REALM>
>  .sp
> -The <anyname> entries match on the service name and realm, but ignore the hostname.
> -These can be used if a principal matching the local host's name is not found.
> +rpc.gssd selects one of the <anyname> entries if it does not find
> +a service principal matching the local hostname,
> +e.g. if DHCP assigns the local hostname dynamically.
> +The <anyname> facility enables the use of the same keytab on multiple systems.
> +However, using the same service principal to establish a machine credential
> +on multiple hosts can create unwanted security exposures
> +and is therefore not recommended.
>  .P
> -Note that the first principal in the search order is a user principal
> +Note that <HOSTNAME>$@<REALM> is a user principal
>  that enables Kerberized NFS when the local system is joined
>  to an Active Directory domain using Samba.
> -A password for this principal must be provided in the local system's keytab.
> +The keytab provides the password for this principal.
>  .P
> -You can specify another keytab by using the
> +You can specify a different keytab by using the
>  .B -k
>  option if
>  .I /etc/krb5.keytab
> diff --git a/utils/mount/nfs.man b/utils/mount/nfs.man
> index 6f79c63a7e9c..19fe22fb5411 100644
> --- a/utils/mount/nfs.man
> +++ b/utils/mount/nfs.man
> @@ -1639,52 +1639,55 @@ from a server's pseudo-fs
>  into one of the server's exported physical filesystems,
>  which often have more restrictive security settings than the pseudo-fs.
>  .SS "NFS version 4 Leases"
> -In NFS version 4, a lease is a period of time during which a server
> -irrevocably grants a file lock to a client.
> -If the lease expires, the server is allowed to revoke that lock.
> +In NFS version 4, a lease is a period during which a server
> +irrevocably grants a client file locks.
> +Once the lease expires, the server may revoke those locks.
>  Clients periodically renew their leases to prevent lock revocation.
>  .P
>  After an NFS version 4 server reboots, each client tells the
> -server about all file open and lock state under its lease
> +server about existing file open and lock state under its lease
>  before operation can continue.
> -If the client reboots, the server frees all open and lock state
> +If a client reboots, the server frees all open and lock state
>  associated with that client's lease.
>  .P
> -As part of establishing a lease, therefore,
> +When establishing a lease, therefore,
>  a client must identify itself to a server.
> -A fixed string is used to distinguish that client from
> -others, and a changeable verifier is used to indicate
> -when the client has rebooted.
> -.P
> -A client uses a particular security flavor and principal
> -when performing the operations to establish a lease.
> -If two clients happen to present the same identity string,
> -a server can use their principals to detect that they are
> -different clients, and prevent one client from interfering
> -with the other's lease.
> -.P
> -The Linux NFS client establishes one lease for each server.
> +Each client presents an arbitrary string
> +to distinguish itself from other clients.
> +The client administrator can
> +supplement the default identity string using the
> +.I nfs4.nfs4_unique_id
> +module parameter to avoid collisions
> +with other client identity strings.
> +.P
> +A client also uses a unique security flavor and principal
> +when it establishes its lease.
> +If two clients present the same identity string,
> +a server can use client principals to distinguish between them,
> +thus securely preventing one client from interfering with the other's lease.
> +.P
> +The Linux NFS client establishes one lease on each NFS version 4 server.
>  Lease management operations, such as lease renewal, are not
>  done on behalf of a particular file, lock, user, or mount
> -point, but on behalf of the whole client that owns that lease.
> -These operations must use the same security flavor and
> -principal that was used when the lease was established,
> -even across client reboots.
> +point, but on behalf of the client that owns that lease.
> +A client uses a consistent identity string, security flavor,
> +and principal across client reboots to ensure that the server
> +can promptly reap expired lease state.
>  .P
>  When Kerberos is configured on a Linux NFS client
>  (i.e., there is a
>  .I /etc/krb5.keytab
>  on that client), the client attempts to use a Kerberos
>  security flavor for its lease management operations.
> -This provides strong authentication of the client to
> -each server it contacts.
> +Kerberos provides secure authentication of each client.
>  By default, the client uses the
>  .I host/
>  or
>  .I nfs/
>  service principal in its
>  .I /etc/krb5.keytab
> -for this purpose.
> +for this purpose, as described in
> +.BR rpc.gssd (8).
>  .P
>  If the client has Kerberos configured, but the server
>  does not, or if the client does not have a keytab or
>