cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

client-identifier.rst (8939B)


      1.. SPDX-License-Identifier: GPL-2.0
      2
      3=======================
      4NFSv4 client identifier
      5=======================
      6
      7This document explains how the NFSv4 protocol identifies client
      8instances in order to maintain file open and lock state during
      9system restarts. A special identifier and principal are maintained
     10on each client. These can be set by administrators, scripts
     11provided by site administrators, or tools provided by Linux
     12distributors.
     13
     14There are risks if a client's NFSv4 identifier and its principal
     15are not chosen carefully.
     16
     17
     18Introduction
     19------------
     20
     21The NFSv4 protocol uses "lease-based file locking". Leases help
     22NFSv4 servers provide file lock guarantees and manage their
     23resources.
     24
     25Simply put, an NFSv4 server creates a lease for each NFSv4 client.
     26The server collects each client's file open and lock state under
     27the lease for that client.
     28
     29The client is responsible for periodically renewing its leases.
     30While a lease remains valid, the server holding that lease
     31guarantees the file locks the client has created remain in place.
     32
     33If a client stops renewing its lease (for example, if it crashes),
     34the NFSv4 protocol allows the server to remove the client's open
     35and lock state after a certain period of time. When a client
     36restarts, it indicates to servers that open and lock state
     37associated with its previous leases is no longer valid and can be
     38destroyed immediately.
     39
     40In addition, each NFSv4 server manages a persistent list of client
     41leases. When the server restarts and clients attempt to recover
     42their state, the server uses this list to distinguish amongst
     43clients that held state before the server restarted and clients
     44sending fresh OPEN and LOCK requests. This enables file locks to
     45persist safely across server restarts.
     46
     47NFSv4 client identifiers
     48------------------------
     49
     50Each NFSv4 client presents an identifier to NFSv4 servers so that
     51they can associate the client with its lease. Each client's
     52identifier consists of two elements:
     53
     54  - co_ownerid: An arbitrary but fixed string.
     55
     56  - boot verifier: A 64-bit incarnation verifier that enables a
     57    server to distinguish successive boot epochs of the same client.
     58
     59The NFSv4.0 specification refers to these two items as an
     60"nfs_client_id4". The NFSv4.1 specification refers to these two
     61items as a "client_owner4".
     62
     63NFSv4 servers tie this identifier to the principal and security
     64flavor that the client used when presenting it. Servers use this
     65principal to authorize subsequent lease modification operations
     66sent by the client. Effectively this principal is a third element of
     67the identifier.
     68
     69As part of the identity presented to servers, a good
     70"co_ownerid" string has several important properties:
     71
     72  - The "co_ownerid" string identifies the client during reboot
     73    recovery, therefore the string is persistent across client
     74    reboots.
     75  - The "co_ownerid" string helps servers distinguish the client
     76    from others, therefore the string is globally unique. Note
     77    that there is no central authority that assigns "co_ownerid"
     78    strings.
     79  - Because it often appears on the network in the clear, the
     80    "co_ownerid" string does not reveal private information about
     81    the client itself.
     82  - The content of the "co_ownerid" string is set and unchanging
     83    before the client attempts NFSv4 mounts after a restart.
     84  - The NFSv4 protocol places a 1024-byte limit on the size of the
     85    "co_ownerid" string.
     86
     87Protecting NFSv4 lease state
     88----------------------------
     89
     90NFSv4 servers utilize the "client_owner4" as described above to
     91assign a unique lease to each client. Under this scheme, there are
     92circumstances where clients can interfere with each other. This is
     93referred to as "lease stealing".
     94
     95If distinct clients present the same "co_ownerid" string and use
     96the same principal (for example, AUTH_SYS and UID 0), a server is
     97unable to tell that the clients are not the same. Each distinct
     98client presents a different boot verifier, so it appears to the
     99server as if there is one client that is rebooting frequently.
    100Neither client can maintain open or lock state in this scenario.
    101
    102If distinct clients present the same "co_ownerid" string and use
    103distinct principals, the server is likely to allow the first client
    104to operate normally but reject subsequent clients with the same
    105"co_ownerid" string.
    106
    107If a client's "co_ownerid" string or principal are not stable,
    108state recovery after a server or client reboot is not guaranteed.
    109If a client unexpectedly restarts but presents a different
    110"co_ownerid" string or principal to the server, the server orphans
    111the client's previous open and lock state. This blocks access to
    112locked files until the server removes the orphaned state.
    113
    114If the server restarts and a client presents a changed "co_ownerid"
    115string or principal to the server, the server will not allow the
    116client to reclaim its open and lock state, and may give those locks
    117to other clients in the meantime. This is referred to as "lock
    118stealing".
    119
    120Lease stealing and lock stealing increase the potential for denial
    121of service and in rare cases even data corruption.
    122
    123Selecting an appropriate client identifier
    124------------------------------------------
    125
    126By default, the Linux NFSv4 client implementation constructs its
    127"co_ownerid" string starting with the words "Linux NFS" followed by
    128the client's UTS node name (the same node name, incidentally, that
    129is used as the "machine name" in an AUTH_SYS credential). In small
    130deployments, this construction is usually adequate. Often, however,
    131the node name by itself is not adequately unique, and can change
    132unexpectedly. Problematic situations include:
    133
    134  - NFS-root (diskless) clients, where the local DCHP server (or
    135    equivalent) does not provide a unique host name.
    136
    137  - "Containers" within a single Linux host.  If each container has
    138    a separate network namespace, but does not use the UTS namespace
    139    to provide a unique host name, then there can be multiple NFS
    140    client instances with the same host name.
    141
    142  - Clients across multiple administrative domains that access a
    143    common NFS server. If hostnames are not assigned centrally
    144    then uniqueness cannot be guaranteed unless a domain name is
    145    included in the hostname.
    146
    147Linux provides two mechanisms to add uniqueness to its "co_ownerid"
    148string:
    149
    150    nfs.nfs4_unique_id
    151      This module parameter can set an arbitrary uniquifier string
    152      via the kernel command line, or when the "nfs" module is
    153      loaded.
    154
    155    /sys/fs/nfs/client/net/identifier
    156      This virtual file, available since Linux 5.3, is local to the
    157      network namespace in which it is accessed and so can provide
    158      distinction between network namespaces (containers) when the
    159      hostname remains uniform.
    160
    161Note that this file is empty on name-space creation. If the
    162container system has access to some sort of per-container identity
    163then that uniquifier can be used. For example, a uniquifier might
    164be formed at boot using the container's internal identifier:
    165
    166    sha256sum /etc/machine-id | awk '{print $1}' \\
    167        > /sys/fs/nfs/client/net/identifier
    168
    169Security considerations
    170-----------------------
    171
    172The use of cryptographic security for lease management operations
    173is strongly encouraged.
    174
    175If NFS with Kerberos is not configured, a Linux NFSv4 client uses
    176AUTH_SYS and UID 0 as the principal part of its client identity.
    177This configuration is not only insecure, it increases the risk of
    178lease and lock stealing. However, it might be the only choice for
    179client configurations that have no local persistent storage.
    180"co_ownerid" string uniqueness and persistence is critical in this
    181case.
    182
    183When a Kerberos keytab is present on a Linux NFS client, the client
    184attempts to use one of the principals in that keytab when
    185identifying itself to servers. The "sec=" mount option does not
    186control this behavior. Alternately, a single-user client with a
    187Kerberos principal can use that principal in place of the client's
    188host principal.
    189
    190Using Kerberos for this purpose enables the client and server to
    191use the same lease for operations covered by all "sec=" settings.
    192Additionally, the Linux NFS client uses the RPCSEC_GSS security
    193flavor with Kerberos and the integrity QOS to prevent in-transit
    194modification of lease modification requests.
    195
    196Additional notes
    197----------------
    198The Linux NFSv4 client establishes a single lease on each NFSv4
    199server it accesses. NFSv4 mounts from a Linux NFSv4 client of a
    200particular server then share that lease.
    201
    202Once a client establishes open and lock state, the NFSv4 protocol
    203enables lease state to transition to other servers, following data
    204that has been migrated. This hides data migration completely from
    205running applications. The Linux NFSv4 client facilitates state
    206migration by presenting the same "client_owner4" to all servers it
    207encounters.
    208
    209========
    210See Also
    211========
    212
    213  - nfs(5)
    214  - kerberos(7)
    215  - RFC 7530 for the NFSv4.0 specification
    216  - RFC 8881 for the NFSv4.1 specification.