| TOC |
|
By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 28, 2008.
Copyright © The IETF Trust (2008).
This Internet-Draft describes NFS version 4 minor version one, including features retained from the base protocol and protocol extensions made subsequently. Major extensions introduced in NFS version 4 minor version one include: Sessions, Directory Delegations, and parallel NFS (pNFS).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [1].
1.
Introduction
1.1.
The NFS Version 4 Minor Version 1 Protocol
1.2.
Scope of this Document
1.3.
NFSv4 Goals
1.4.
NFSv4.1 Goals
1.5.
General Definitions
1.6.
Overview of NFSv4.1 Features
1.6.1.
RPC and Security
1.6.2.
Protocol Structure
1.6.3.
File System Model
1.6.4.
Locking Facilities
1.7.
Differences from NFSv4.0
2.
Core Infrastructure
2.1.
Introduction
2.2.
RPC and XDR
2.2.1.
RPC-based Security
2.3.
COMPOUND and CB_COMPOUND
2.4.
Client Identifiers and Client Owners
2.4.1.
Upgrade from NFSv4.0 to NFSv4.1
2.4.2.
Server Release of Client ID
2.4.3.
Resolving Client Owner Conflicts
2.5.
Server Owners
2.6.
Security Service Negotiation
2.6.1.
NFSv4.1 Security Tuples
2.6.2.
SECINFO and SECINFO_NO_NAME
2.6.3.
Security Error
2.7.
Minor Versioning
2.8.
Non-RPC-based Security Services
2.8.1.
Authorization
2.8.2.
Auditing
2.8.3.
Intrusion Detection
2.9.
Transport Layers
2.9.1.
REQUIRED and RECOMMENDED Properties of Transports
2.9.2.
Client and Server Transport Behavior
2.9.3.
Ports
2.10.
Session
2.10.1.
Motivation and Overview
2.10.2.
NFSv4 Integration
2.10.3.
Channels
2.10.4.
Trunking
2.10.5.
Exactly Once Semantics
2.10.6.
RDMA Considerations
2.10.7.
Sessions Security
2.10.8.
The SSV GSS Mechanism
2.10.9.
Session Mechanics - Steady State
2.10.10.
Session Inactivity Timer
2.10.11.
Session Mechanics - Recovery
2.10.12.
Parallel NFS and Sessions
3.
Protocol Constants and Data Types
3.1.
Basic Constants
3.2.
Basic Data Types
3.3.
Structured Data Types
4.
Filehandles
4.1.
Obtaining the First Filehandle
4.1.1.
Root Filehandle
4.1.2.
Public Filehandle
4.2.
Filehandle Types
4.2.1.
General Properties of a Filehandle
4.2.2.
Persistent Filehandle
4.2.3.
Volatile Filehandle
4.3.
One Method of Constructing a Volatile Filehandle
4.4.
Client Recovery from Filehandle Expiration
5.
File Attributes
5.1.
REQUIRED Attributes
5.2.
RECOMMENDED Attributes
5.3.
Named Attributes
5.4.
Classification of Attributes
5.5.
REQUIRED Attributes - List and Definition References
5.6.
RECOMMENDED Attributes - List and Definition References
5.7.
Attribute
Definitions
5.7.1.
Definitions of REQUIRED Attributes
5.7.2.
Definitions of Uncategorized RECOMMENDED Attributes
5.8.
Interpreting owner and owner_group
5.9.
Character Case Attributes
5.10.
Directory Notification Attributes
5.11.
pNFS Attribute Definitions
5.12.
Retention Attributes
6.
Access Control Attributes
6.1.
Goals
6.2.
File Attributes Discussion
6.2.1.
Attribute 12: acl
6.2.2.
Attribute 58: dacl
6.2.3.
Attribute 59: sacl
6.2.4.
Attribute 33: mode
6.2.5.
Attribute 74: mode_set_masked
6.3.
Common Methods
6.3.1.
Interpreting an ACL
6.3.2.
Computing a Mode Attribute from an ACL
6.4.
Requirements
6.4.1.
Setting the mode and/or ACL Attributes
6.4.2.
Retrieving the mode and/or ACL Attributes
6.4.3.
Creating New Objects
7.
Single-server Namespace
7.1.
Server Exports
7.2.
Browsing Exports
7.3.
Server Pseudo File System
7.4.
Multiple Roots
7.5.
Filehandle Volatility
7.6.
Exported Root
7.7.
Mount Point Crossing
7.8.
Security Policy and Namespace Presentation
8.
State Management
8.1.
Client and Session ID
8.2.
Stateid Definition
8.2.1.
Stateid Types
8.2.2.
Stateid Structure
8.2.3.
Special Stateids
8.2.4.
Stateid Lifetime and Validation
8.2.5.
Stateid Use for I/O Operations
8.3.
Lease Renewal
8.4.
Crash Recovery
8.4.1.
Client Failure and Recovery
8.4.2.
Server Failure and Recovery
8.4.3.
Network Partitions and Recovery
8.5.
Server Revocation of Locks
8.6.
Short and Long Leases
8.7.
Clocks, Propagation Delay, and Calculating Lease Expiration
8.8.
Obsolete Locking Infrastructure From NFSv4.0
9.
File Locking and Share Reservations
9.1.
Opens and Byte-range Locks
9.1.1.
State-owner Definition
9.1.2.
Use of the Stateid and Locking
9.2.
Lock Ranges
9.3.
Upgrading and Downgrading Locks
9.4.
Stateid Seqid Values and Byte-range Locks
9.5.
Issues with Multiple Open-owners
9.6.
Blocking Locks
9.7.
Share Reservations
9.8.
OPEN/CLOSE Operations
9.9.
Open Upgrade and Downgrade
9.10.
Parallel OPENs
9.11.
Reclaim of Open and Byte-range Locks
10.
Client-Side Caching
10.1.
Performance Challenges for Client-Side Caching
10.2.
Delegation and Callbacks
10.2.1.
Delegation Recovery
10.3.
Data Caching
10.3.1.
Data Caching and OPENs
10.3.2.
Data Caching and File Locking
10.3.3.
Data Caching and Mandatory File Locking
10.3.4.
Data Caching and File Identity
10.4.
Open Delegation
10.4.1.
Open Delegation and Data Caching
10.4.2.
Open Delegation and File Locks
10.4.3.
Handling of CB_GETATTR
10.4.4.
Recall of Open Delegation
10.4.5.
Clients that Fail to Honor Delegation Recalls
10.4.6.
Delegation Revocation
10.4.7.
Delegations via WANT_DELEGATION
10.5.
Data Caching and Revocation
10.5.1.
Revocation Recovery for Write Open Delegation
10.6.
Attribute Caching
10.7.
Data and Metadata Caching and Memory Mapped Files
10.8.
Name and Directory Caching without Directory Delegations
10.8.1.
Name Caching
10.8.2.
Directory Caching
10.9.
Directory Delegations
10.9.1.
Introduction to Directory Delegations
10.9.2.
Directory Delegation Design
10.9.3.
Attributes in Support of Directory Notifications
10.9.4.
Directory Delegation Recall
10.9.5.
Directory Delegation Recovery
11.
Multi-Server Namespace
11.1.
Location Attributes
11.2.
File System Presence or Absence
11.3.
Getting Attributes for an Absent File System
11.3.1.
GETATTR Within an Absent File System
11.3.2.
READDIR and Absent File Systems
11.4.
Uses of Location Information
11.4.1.
File System Replication
11.4.2.
File System Migration
11.4.3.
Referrals
11.5.
Location Entries and Server Identity
11.6.
Additional Client-side Considerations
11.7.
Effecting File System Transitions
11.7.1.
File System Transitions and Simultaneous Access
11.7.2.
Simultaneous Use and Transparent Transitions
11.7.3.
Filehandles and File System Transitions
11.7.4.
Fileids and File System Transitions
11.7.5.
Fsids and File System Transitions
11.7.6.
The Change Attribute and File System Transitions
11.7.7.
Lock State and File System Transitions
11.7.8.
Write Verifiers and File System Transitions
11.7.9.
Readdir Cookies and Verifiers and File System Transitions
11.7.10.
File System Data and File System Transitions
11.8.
Effecting File System Referrals
11.8.1.
Referral Example (LOOKUP)
11.8.2.
Referral Example (READDIR)
11.9.
The Attribute fs_locations
11.10.
The Attribute fs_locations_info
11.10.1.
The fs_locations_server4 Structure
11.10.2.
The fs_locations_info4 Structure
11.10.3.
The fs_locations_item4 Structure
11.11.
The Attribute fs_status
12.
Parallel NFS (pNFS)
12.1.
Introduction
12.2.
pNFS Definitions
12.2.1.
Metadata
12.2.2.
Metadata Server
12.2.3.
pNFS Client
12.2.4.
Storage Device
12.2.5.
Storage Protocol
12.2.6.
Control Protocol
12.2.7.
Layout Types
12.2.8.
Layout
12.2.9.
Layout Iomode
12.2.10.
Device IDs
12.3.
pNFS Operations
12.4.
pNFS Attributes
12.5.
Layout Semantics
12.5.1.
Guarantees Provided by Layouts
12.5.2.
Getting a Layout
12.5.3.
Layout Stateid
12.5.4.
Committing a Layout
12.5.5.
Recalling a Layout
12.5.6.
Revoking Layouts
12.5.7.
Metadata Server Write Propagation
12.6.
pNFS Mechanics
12.7.
Recovery
12.7.1.
Recovery from Client Restart
12.7.2.
Dealing with Lease Expiration on the Client
12.7.3.
Dealing with Loss of Layout State on the Metadata Server
12.7.4.
Recovery from Metadata Server Restart
12.7.5.
Operations During Metadata Server Grace Period
12.7.6.
Storage Device Recovery
12.8.
Metadata and Storage Device Roles
12.9.
Security Considerations for pNFS
13.
PNFS: NFSv4.1 File Layout Type
13.1.
Client ID and Session Considerations
13.1.1.
Sessions Considerations for Data Servers
13.2.
File Layout Definitions
13.3.
File Layout Data Types
13.4.
Interpreting the File Layout
13.4.1.
Determining the Stripe Unit Number
13.4.2.
Interpreting the File Layout Using Sparse Packing
13.4.3.
Interpreting the File Layout Using Dense Packing
13.4.4.
Sparse and Dense Stripe Unit Packing
13.5.
Data Server Multipathing
13.6.
Operations Sent to NFSv4.1 Data Servers
13.7.
COMMIT Through Metadata Server
13.8.
The Layout Iomode
13.9.
Metadata and Data Server State Coordination
13.9.1.
Global Stateid Requirements
13.9.2.
Data Server State Propagation
13.10.
Data Server Component File Size
13.11.
Layout Revocation and Fencing
13.12.
Security Considerations for the File Layout Type
14.
Internationalization
14.1.
Stringprep profile for the utf8str_cs type
14.2.
Stringprep profile for the utf8str_cis type
14.3.
Stringprep profile for the utf8str_mixed type
14.4.
UTF-8 Capabilities
14.5.
UTF-8 Related Errors
15.
Error Values
15.1.
Error Definitions
15.1.1.
General Errors
15.1.2.
Filehandle Errors
15.1.3.
Compound Structure Errors
15.1.4.
File System Errors
15.1.5.
State Management Errors
15.1.6.
Security Errors
15.1.7.
Name Errors
15.1.8.
Locking Errors
15.1.9.
Reclaim Errors
15.1.10.
pNFS Errors
15.1.11.
Session Use Errors
15.1.12.
Session Management Errors
15.1.13.
Client Management Errors
15.1.14.
Delegation Errors
15.1.15.
Attribute Handling Errors
15.1.16.
Obsoleted Errors
15.2.
Operations and their valid errors
15.3.
Callback operations and their valid errors
15.4.
Errors and the operations that use them
16.
NFSv4.1 Procedures
16.1.
Procedure 0: NULL - No Operation
16.2.
Procedure 1: COMPOUND - Compound Operations
17.
Operations: REQUIRED, RECOMMENDED, or OPTIONAL
18.
NFSv4.1 Operations
18.1.
Operation 3: ACCESS - Check Access Rights
18.2.
Operation 4: CLOSE - Close File
18.3.
Operation 5: COMMIT - Commit Cached Data
18.4.
Operation 6: CREATE - Create a Non-Regular File Object
18.5.
Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery
18.6.
Operation 8: DELEGRETURN - Return Delegation
18.7.
Operation 9: GETATTR - Get Attributes
18.8.
Operation 10: GETFH - Get Current Filehandle
18.9.
Operation 11: LINK - Create Link to a File
18.10.
Operation 12: LOCK - Create Lock
18.11.
Operation 13: LOCKT - Test For Lock
18.12.
Operation 14: LOCKU - Unlock File
18.13.
Operation 15: LOOKUP - Lookup Filename
18.14.
Operation 16: LOOKUPP - Lookup Parent Directory
18.15.
Operation 17: NVERIFY - Verify Difference in Attributes
18.16.
Operation 18: OPEN - Open a Regular File
18.17.
Operation 19: OPENATTR - Open Named Attribute Directory
18.18.
Operation 21: OPEN_DOWNGRADE - Reduce Open File Access
18.19.
Operation 22: PUTFH - Set Current Filehandle
18.20.
Operation 23: PUTPUBFH - Set
Public Filehandle
18.21.
Operation 24: PUTROOTFH - Set Root Filehandle
18.22.
Operation 25: READ - Read from File
18.23.
Operation 26: READDIR - Read Directory
18.24.
Operation 27: READLINK - Read Symbolic Link
18.25.
Operation 28: REMOVE - Remove File System Object
18.26.
Operation 29: RENAME - Rename Directory Entry
18.27.
Operation 31: RESTOREFH - Restore Saved Filehandle
18.28.
Operation 32: SAVEFH - Save Current Filehandle
18.29.
Operation 33: SECINFO - Obtain Available Security
18.30.
Operation 34: SETATTR - Set Attributes
18.31.
Operation 37: VERIFY - Verify Same Attributes
18.32.
Operation 38: WRITE - Write to File
18.33.
Operation 40: BACKCHANNEL_CTL - Backchannel control
18.34.
Operation 41: BIND_CONN_TO_SESSION
18.35.
Operation 42: EXCHANGE_ID - Instantiate Client ID
18.36.
Operation 43: CREATE_SESSION - Create New Session and Confirm Client ID
18.37.
Operation 44: DESTROY_SESSION - Destroy existing session
18.38.
Operation 45: FREE_STATEID - Free stateid with no locks
18.39.
Operation 46: GET_DIR_DELEGATION - Get a directory delegation
18.40.
Operation 47: GETDEVICEINFO - Get Device Information
18.41.
Operation 48: GETDEVICELIST - Get All Device Mappings for a File System
18.42.
Operation 49: LAYOUTCOMMIT - Commit writes made using a layout
18.43.
Operation 50: LAYOUTGET - Get Layout Information
18.44.
Operation 51: LAYOUTRETURN - Release Layout Information
18.45.
Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object
18.46.
Operation 53: SEQUENCE - Supply per-procedure sequencing and control
18.47.
Operation 54: SET_SSV - Update SSV for a Client ID
18.48.
Operation 55: TEST_STATEID - Test stateids for validity
18.49.
Operation 56: WANT_DELEGATION - Request Delegation
18.50.
Operation 57: DESTROY_CLIENTID - Destroy existing client ID
18.51.
Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished
18.52.
Operation 10044: ILLEGAL - Illegal operation
19.
NFSv4.1 Callback Procedures
19.1.
Procedure 0: CB_NULL - No Operation
19.2.
Procedure 1: CB_COMPOUND - Compound Operations
20.
NFSv4.1 Callback Operations
20.1.
Operation 3: CB_GETATTR - Get Attributes
20.2.
Operation 4: CB_RECALL - Recall an Open Delegation
20.3.
Operation 5: CB_LAYOUTRECALL - Recall Layout from Client
20.4.
Operation 6: CB_NOTIFY - Notify directory changes
20.5.
Operation 7: CB_PUSH_DELEG - Offer Delegation to Client
20.6.
Operation 8: CB_RECALL_ANY - Keep any N delegations
20.7.
Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for Recallable Objects
20.8.
Operation 10: CB_RECALL_SLOT - change flow control limits
20.9.
Operation 11: CB_SEQUENCE - Supply backchannel sequencing and control
20.10.
Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation Wants
20.11.
Operation 13: CB_NOTIFY_LOCK - Notify of possible lock availability
20.12.
Operation 14: CB_NOTIFY_DEVICEID - Notify device ID changes
20.13.
Operation 10044: CB_ILLEGAL - Illegal Callback Operation
21.
Security Considerations
22.
IANA Considerations
22.1.
Named Attribute Definitions
22.2.
ONC RPC Network Identifiers (netids)
22.3.
Defining New Notifications
22.4.
Defining New Layout Types
22.5.
Path Variable Definitions
22.5.1.
Path Variable Values
22.5.2.
Path Variable Names
23.
References
23.1.
Normative References
23.2.
Informative References
Appendix A.
Acknowledgments
§
Authors' Addresses
§
Intellectual Property and Copyright Statements
| TOC |
| TOC |
The NFS version 4 minor version 1 (NFSv4.1) protocol is the second minor version of the NFS version 4 (NFSv4) protocol. The first minor version, NFSv4.0 is described in [21] (Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, C., Eisler, M., and D. Noveck, “Network File System (NFS) version 4 Protocol,” April 2003.). It generally follows the guidelines for minor versioning model listed in Section 10 of RFC 3530. However, it diverges from guidelines 11 ("a client and server that supports minor version X must support minor versions 0 through X-1"), and 12 ("no features may be introduced as mandatory in a minor version"). These divergences are due to the introduction of the sessions model for managing non-idempotent operations and the RECLAIM_COMPLETE operation. These two new features are infrastructural in nature and simplify implementation of existing and other new features. Making them anything but REQUIRED would add undue complexity to protocol definition and implementation. NFSv4.1 accordingly updates the Minor Versioning guidelines (Minor Versioning).
As a minor version, NFSv4.1 is consistent with the overall goals for NFSv4, but extends the protocol so as to better meet those goals, based on experiences with NFSv4.0. In addition, NFSv4.1 has adopted some additional goals, which motivate some of the major extensions in NFSv4.1.
| TOC |
This document describes the NFSv4.1 protocol. With respect to NFSv4.0, this document does not:
| TOC |
The NFSv4 protocol is a further revision of the NFS protocol defined already by NFSv3 [22] (Callaghan, B., Pawlowski, B., and P. Staubach, “NFS Version 3 Protocol Specification,” June 1995.). It retains the essential characteristics of previous versions: easy recovery; independence of transport protocols, operating systems and file systems; simplicity; and good performance. NFSv4 has the following goals:
| TOC |
NFSv4.1 has the following goals, within the framework established by the overall NFSv4 goals.
| TOC |
The following definitions are provided for the purpose of providing an appropriate context for the reader.
- Byte
- This document defines a byte as an octet, i.e. a datum exactly 8 bits in length.
- Client
- The "client" is the entity that accesses the NFS server's resources. The client may be an application which contains the logic to access the NFS server directly. The client may also be the traditional operating system client that provides remote file system services for a set of applications.
A client is uniquely identified by a Client Owner.
With reference to file locking, the client is also the entity that maintains a set of locks on behalf of one or more applications. This client is responsible for crash or failure recovery for those locks it manages.
Note that multiple clients may share the same transport and connection and multiple clients may exist on the same network node.- Client ID
- A 64-bit quantity used as a unique, short-hand reference to a client supplied Verifier and client owner. The server is responsible for supplying the client ID.
- Client Owner
- The client owner is a unique string, opaque to the server, which identifies a client. Multiple network connections and source network addresses originating from those connections may share a client owner. The server is expected to treat requests from connnections with the same client owner as coming from the same client.
- File System
- The collection of objects on a server (as identified by the major identifier of a Server Owner, which is defined later in this section), that share the same fsid attribute (see Section 5.7.1.9 (Attribute 8: fsid)).
- Lease
- An interval of time defined by the server for which the client is irrevocably granted a lock. At the end of a lease period the lock may be revoked if the lease has not been extended. The lock must be revoked if a conflicting lock has been granted after the lease interval.
All leases granted by a server have the same fixed interval. Note that the fixed interval was chosen to alleviate the expense a server would have in maintaining state about variable length leases across server failures.- Lock
- The term "lock" is used to refer to record (byte-range) locks, share reservations, delegations, or layouts unless specifically stated otherwise.
- Server
- The "Server" is the entity responsible for coordinating client access to a set of file systems and is identified by a Server owner. A server can span multiple network addresses.
- Server Owner
- The "Server Owner" identifies the server to the client. The server owner consists of a major and minor identifier. When the client has two connections each to a peer with the same major identifier, the client assumes both peers are the same server (the server namespace is the same via each connection), and assumes and lock state is sharable across both connections. When each peer has both the same major and minor identifier, the client assumes each connection might be associatable with the same session.
- Stable Storage
- NFSv4.1 servers must be able to recover without data loss from multiple power failures (including cascading power failures, that is, several power failures in quick succession), operating system failures, and hardware failure of components other than the storage medium itself (for example, disk, nonvolatile RAM).
Some examples of stable storage that are allowable for an NFS server include:
- Media commit of data, that is, the modified data has been successfully written to the disk media, for example, the disk platter.
- An immediate reply disk drive with battery-backed on- drive intermediate storage or uninterruptible power system (UPS).
- Server commit of data with battery-backed intermediate storage and recovery software.
- Cache commit with uninterruptible power system (UPS) and recovery software.
- Stateid
- A 128-bit quantity returned by a server that uniquely defines the open and locking state provided by the server for a specific open-owner or lock-owner/open-owner pair for a specific file and type of lock.
- Verifier
- A 64-bit quantity generated by the client that the server can use to determine if the client has restarted and lost all previous lock state.
| TOC |
To provide a reasonable context for the reader, the major features of the NFSv4.1 protocol will be reviewed in brief. This will be done to provide an appropriate context for both the reader who is familiar with the previous versions of the NFS protocol and the reader that is new to the NFS protocols. For the reader new to the NFS protocols, there is still a set of fundamental knowledge that is expected. The reader should be familiar with the XDR and RPC protocols as described in [2] (Eisler, M., “XDR: External Data Representation Standard,” May 2006.) and [3] (Srinivasan, R., “RPC: Remote Procedure Call Protocol Specification Version 2,” August 1995.). A basic knowledge of file systems and distributed file systems is expected as well.
In general this specification of NFSv4.1 will not distinguish those added in minor version one from those present in the base protocol but will treat NFSv4.1 as a unified whole. See Section 1.7 (Differences from NFSv4.0) for a summary of the differences between NFSv4.0 and NFSv4.1.
| TOC |
As with previous versions of NFS, the External Data Representation (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4.1 protocol are those defined in [2] (Eisler, M., “XDR: External Data Representation Standard,” May 2006.) and [3] (Srinivasan, R., “RPC: Remote Procedure Call Protocol Specification Version 2,” August 1995.). To meet end-to-end security requirements, the RPCSEC_GSS framework [4] (Eisler, M., Chiu, A., and L. Ling, “RPCSEC_GSS Protocol Specification,” September 1997.) will be used to extend the basic RPC security. With the use of RPCSEC_GSS, various mechanisms can be provided to offer authentication, integrity, and privacy to the NFSv4 protocol. Kerberos V5 will be used as described in [5] (Zhu, L., Jaganathan, K., and S. Hartman, “The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism Version 2,” July 2005.) to provide one security framework. The LIPKEY and SPKM-3 GSS-API mechanisms described in [6] (Eisler, M., “LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM,” June 2000.) will be used to provide for the use of user password and client/server public key certificates by the NFSv4 protocol. With the use of RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4.1 security.
To enable in-band security negotiation, the NFSv4.1 protocol has operations which provide the client a method of querying the server about its policies regarding which security mechanisms must be used for access to the server's file system resources. With this, the client can securely match the security mechanism that meets the policies specified at both the client and server.
| TOC |
| TOC |
Unlike NFSv3, which used a series of ancillary protocols (e.g. NLM, NSM, MOUNT), within all minor versions of NFSv4 a single RPC protocol is used to make requests to the server. Facilities that had been separate protocols, such as locking, are now integrated within a single unified protocol.
| TOC |
Minor version one supports high-performance data access to a clustered server implementation by enabling a separation of metadata access and data access, with the latter done to multiple servers in parallel.
Such parallel data access is controlled by recallable objects known as "layouts", which are integrated into the protocol locking model. Clients direct requests for data access to a set of data servers specified by the layout via a data storage protocol which may be NFSv4.1 or may be another protocol.
| TOC |
The general file system model used for the NFSv4.1 protocol is the same as previous versions. The server file system is hierarchical with the regular files contained within being treated as opaque byte streams. In a slight departure, file and directory names are encoded with UTF-8 to deal with the basics of internationalization.
The NFSv4.1 protocol does not require a separate protocol to provide for the initial mapping between path name and filehandle. All file systems exported by a server are presented as a tree so that all file systems are reachable from a special per-server global root filehandle. This allows LOOKUP operations to be used to perform functions previously provided by the MOUNT protocol. The server provides any necessary pseudo file systems to bridge any gaps that arise due to unexported gaps between exported file systems.
| TOC |
As in previous versions of the NFS protocol, opaque filehandles are used to identify individual files and directories. Lookup-type and create operations translate file and directory names to filehandles which are then used to identify objects in subsequent operations.
The NFSv4.1 protocol provides support for persistent filehandles, guaranteed to be valid for the lifetime of the file system object designated. In addition it provides support to servers to provide filehandles with more limited validity guarantees, called volatile filehandles.
| TOC |
The NFSv4.1 protocol has a rich and extensible attribute structure, which is divided into REQUIRED, RECOMMENDED, and named attributes.
The acl, sacl, and dacl attributes compose a set of RECOMMENDED file attributes that make up the Access Control List (ACL) of a file (Section 6 (Access Control Attributes)). These attributes provide for directory and file access control beyond the model used in NFSv3. The ACL definition allows for specification of specific sets of permissions for individual users and groups. In addition, ACL inheritance allows propagation of access permissions and restriction down a directory tree as file system objects are created.
A named attribute is an opaque byte stream that is associated with a directory or file and referred to by a string name. Named attributes are meant to be used by client applications as a method to associate application-specific data with a regular file or directory. NFSv4.1 modifies named attributes relative to NFSv4.0 by tightening the allowed operations in order to prevent the development of non-interoperable implementation. See Section 5.3 (Named Attributes) for details.
| TOC |
NFSv4.1 contains a number of features to allow implementation of namespaces that cross server boundaries and that allow and facilitate a non-disruptive transfer of support for individual file systems between servers. They are all based upon attributes that allow one file system to specify alternate or new locations for that file system.
These attributes may be used together with the concept of absent file systems, which provide specifications for additional locations but no actual file system content. This allows a number of important facilities:
| TOC |
As mentioned previously, NFS v4.1 is a single protocol which includes locking facilities. These locking facilities include support for many types of locks including a number of sorts of recallable locks. Recallable locks such as delegations allow the client to be assured that certain events will not occur so long as that lock is held. When circumstances change, the lock is recalled via a callback request. The assurances provided by delegations allow more extensive caching to be done safely when circumstances allow it.
The types of locks are:
All locks for a given client are tied together under a single client-wide lease. All requests made on sessions associated with the client renew that lease. When leases are not promptly renewed locks are subject to revocation. In the event of server restart, clients have the opportunity to safely reclaim their locks within a special grace period.
| TOC |
The following summarizes the major differences between minor version one and the base protocol:
| TOC |
| TOC |
NFSv4.1 relies on core infrastructure common to nearly every operation. This core infrastructure is described in the remainder of this section.
| TOC |
The NFSv4.1 protocol is a Remote Procedure Call (RPC) application that uses RPC version 2 and the corresponding eXternal Data Representation (XDR) as defined in [3] (Srinivasan, R., “RPC: Remote Procedure Call Protocol Specification Version 2,” August 1995.) and [2] (Eisler, M., “XDR: External Data Representation Standard,” May 2006.).
| TOC |
Previous NFS versions have been thought of as having a host-based authentication model, where the NFS server authenticates the NFS client, and trusts the client to authenticate all users. Actually, NFS has always depended on RPC for authentication. One of the first forms of RPC authentication, AUTH_SYS, had no strong authentication, and required a host-based authentication approach. NFSv4.1 also depends on RPC for basic security services, and mandates RPC support for a user-based authentication model. The user-based authentication model has user principals authenticated by a server, and in turn the server authenticated by user principals. RPC provides some basic security services which are used by NFSv4.1.
| TOC |
As described in section 7.2 "Authentication" of [3] (Srinivasan, R., “RPC: Remote Procedure Call Protocol Specification Version 2,” August 1995.), RPC security is encapsulated in the RPC header, via a security or authentication flavor, and information specific to the specified security flavor. Every RPC header conveys information used to identify and authenticate a client and server. As discussed in Section 2.2.1.1.1 (RPCSEC_GSS and Security Services), some security flavors provide additional security services.
NFSv4.1 clients and servers MUST implement RPCSEC_GSS. (This requirement to implement is not a requirement to use.) Other flavors, such as AUTH_NONE, and AUTH_SYS, MAY be implemented as well.
| TOC |
RPCSEC_GSS ([4] (Eisler, M., Chiu, A., and L. Ling, “RPCSEC_GSS Protocol Specification,” September 1997.)) uses the functionality of GSS-API [7] (Linn, J., “Generic Security Service Application Program Interface Version 2, Update 1,” January 2000.). This allows for the use of various security mechanisms by the RPC layer without the additional implementation overhead of adding RPC security flavors.
| TOC |
Via the GSS-API, RPCSEC_GSS can be used to identify and authenticate users on clients to servers, and servers to users. It can also perform integrity checking on the entire RPC message, including the RPC header, and the arguments or results. Finally, privacy, usually via encryption, is a service available with RPCSEC_GSS. Privacy is performed on the arguments and results. Note that if privacy is selected, integrity, authentication, and identification are enabled. If privacy is not selected, but integrity is selected, authentication and identification are enabled. If integrity and privacy are not selected, but authentication is enabled, identification is enabled. RPCSEC_GSS does not provide identification as a separate service.
Although GSS-API has an authentication service distinct from its privacy and integrity services, GSS-API's authentication service is not used for RPCSEC_GSS's authentication service. Instead, each RPC request and response header is integrity protected with the GSS-API integrity service, and this allows RPCSEC_GSS to offer per-RPC authentication and identity. See [4] (Eisler, M., Chiu, A., and L. Ling, “RPCSEC_GSS Protocol Specification,” September 1997.) for more information.
NFSv4.1 client and servers MUST support RPCSEC_GSS's integrity and authentication service. NFSv4.1 servers MUST support RPCSEC_GSS's privacy service.
| TOC |
RPCSEC_GSS, via GSS-API, normalizes access to mechanisms that provide security services. Therefore NFSv4.1 clients and servers MUST support three security mechanisms: Kerberos V5, SPKM-3, and LIPKEY.
The use of RPCSEC_GSS requires selection of: mechanism, quality of protection (QOP), and service (authentication, integrity, privacy). For the mandated security mechanisms, NFSv4.1 specifies that a QOP of zero (0) is used, leaving it up to the mechanism or the mechanism's configuration to use an appropriate level of protection that QOP zero maps to. Each mandated mechanism specifies minimum set of cryptographic algorithms for implementing integrity and privacy. NFSv4.1 clients and servers MUST be implemented on operating environments that comply with the REQUIRED cryptographic algorithms of each REQUIRED mechanism.
| TOC |
The Kerberos V5 GSS-API mechanism as described in [5] (Zhu, L., Jaganathan, K., and S. Hartman, “The Kerberos Version 5 Generic Security Service Application Program Interface (GSS-API) Mechanism Version 2,” July 2005.) MUST be implemented with the RPCSEC_GSS services as specified in the following table:
column descriptions: 1 == number of pseudo flavor 2 == name of pseudo flavor 3 == mechanism's OID 4 == RPCSEC_GSS service 5 == NFSv4.1 clients MUST support 6 == NFSv4.1 servers MUST support 1 2 3 4 5 6 ------------------------------------------------------------------ 390003 krb5 1.2.840.113554.1.2.2 rpc_gss_svc_none yes yes 390004 krb5i 1.2.840.113554.1.2.2 rpc_gss_svc_integrity yes yes 390005 krb5p 1.2.840.113554.1.2.2 rpc_gss_svc_privacy no yes
Note that the number and name of the pseudo flavor is presented here as a mapping aid to the implementor. Because the NFSv4.1 protocol includes a method to negotiate security and it understands the GSS-API mechanism, the pseudo flavor is not needed. The pseudo flavor is needed for the NFSv3 since the security negotiation is done via the MOUNT protocol as described in [23] (Eisler, M., “NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use of RPCSEC_GSS and Kerberos V5,” June 1999.).
| TOC |
The LIPKEY V5 GSS-API mechanism as described in [6] (Eisler, M., “LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM,” June 2000.) MUST be implemented with the RPCSEC_GSS services as specified in the following table:
1 2 3 4 5 6 ------------------------------------------------------------------ 390006 lipkey 1.3.6.1.5.5.9 rpc_gss_svc_none yes yes 390007 lipkey-i 1.3.6.1.5.5.9 rpc_gss_svc_integrity yes yes 390008 lipkey-p 1.3.6.1.5.5.9 rpc_gss_svc_privacy no yes
| TOC |
The SPKM-3 GSS-API mechanism as described in [6] (Eisler, M., “LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM,” June 2000.) MUST be implemented with the RPCSEC_GSS services as specified in the following table:
1 2 3 4 5 6 ------------------------------------------------------------------ 390009 spkm3 1.3.6.1.5.5.1.3 rpc_gss_svc_none yes yes 390010 spkm3i 1.3.6.1.5.5.1.3 rpc_gss_svc_integrity yes yes 390011 spkm3p 1.3.6.1.5.5.1.3 rpc_gss_svc_privacy no yes
| TOC |
Regardless of what security mechanism under RPCSEC_GSS is being used, the NFS server, MUST identify itself in GSS-API via a GSS_C_NT_HOSTBASED_SERVICE name type. GSS_C_NT_HOSTBASED_SERVICE names are of the form:
service@hostname
For NFS, the "service" element is
nfs
Implementations of security mechanisms will convert nfs@hostname to various different forms. For Kerberos V5, LIPKEY, and SPKM-3, the following form is RECOMMENDED:
nfs/hostname
| TOC |
A significant departure from the versions of the NFS protocol before NFSv4 is the introduction of the COMPOUND procedure. For the NFSv4 protocol, in all minor versions, there are exactly two RPC procedures, NULL and COMPOUND. The COMPOUND procedure is defined as a series of individual operations and these operations perform the sorts of functions performed by traditional NFS procedures.
The operations combined within a COMPOUND request are evaluated in order by the server, without any atomicity guarantees. A limited set of facilities exist to pass results from one operation to another. Once an operation returns a failing result, the evaluation ends and the results of all evaluated operations are returned to the client.
With the use of the COMPOUND procedure, the client is able to build simple or complex requests. These COMPOUND requests allow for a reduction in the number of RPCs needed for logical file system operations. For example, multi-component lookup requests can be constructed by combining multiple LOOKUP operations. Those can be further combined with operations such as GETATTR, READDIR, or OPEN plus READ to do more complicated sets of operation without incurring additional latency.
NFSv4.1 also contains a considerable set of callback operations in which the server makes an RPC directed at the client. Callback RPC's have a similar structure to that of the normal server requests. In all minor versions of the NFSv4 protocol there are two callback RPC procedures, NULL and CB_COMPOUND. The CB_COMPOUND procedure is defined in an analogous fashion to that of COMPOUND with its own set of callback operations.
The addition of new server and callback operations within the COMPOUND and CB_COMPOUND request framework provides a means of extending the protocol in subsequent minor versions.
Except for a small number of operations needed for session creation, server requests and callback requests are performed within the context of a session. Sessions provide a client context for every request and support robust reply protection for non-idempotent requests.
| TOC |
For each operation that obtains or depends on locking state, the specific client must be identifiable by the server.
Each distinct client instance is represented by a client ID. A client ID is a 64-bit identifier representing a specific client at a given time. The client ID is changed whenever the client re-initializes, and may change when the server re-initializes. Client IDs are used to support lock identification and crash recovery.
During steady state operation, the client ID associated with each operation is derived from the session (see Section 2.10 (Session)) on which the operation is sent. A session is associated with a client ID when the session is created.
Unlike NFSv4.0, the only NFSv4.1 operations possible before a client ID is established are those needed to establish the client ID.
A sequence of an EXCHANGE_ID operation followed by a CREATE_SESSION operation using that client ID (eir_clientid as returned from EXCHANGE_ID) is required to establish and confirm the client ID on the server. Establishment of identification by a new incarnation of the client also has the effect of immediately releasing any locking state that a previous incarnation of that same client might have had on the server. Such released state would include all lock, share reservation, layout state, and where the server is not supporting the CLAIM_DELEGATE_PREV claim type, all delegation state associated with the same client with the same identity. For discussion of delegation state recovery, see Section 10.2.1 (Delegation Recovery). For discussion of layout state recovery see Section 12.7.1 (Recovery from Client Restart).
Releasing such state requires that the server be able to determine that one client instance is the successor of another. Where this cannot be done, for any of a number of reasons, the locking state will remain for a time subject to lease expiration (see Section 8.3 (Lease Renewal)) and the new client will need to wait for such state to be removed, if it makes conflicting lock requests.
Client identification is encapsulated in the following Client Owner data type:
struct client_owner4 {
verifier4 co_verifier;
opaque co_ownerid<NFS4_OPAQUE_LIMIT>;
};
The first field, co_verifier, is a client incarnation verifier. The server will start the process of canceling the client's leased state if co_verifier is different than what the server has previously recorded for the identified client (as specified in the co_ownerid field).
The second field, co_ownerid is a variable length string that uniquely defines the client so that subsequent instances of the same client bear the same co_ownerid with a different verifier.
There are several considerations for how the client generates the co_ownerid string:
Given the above considerations, an example of a well generated co_ownerid string is one that includes:
The client ID is assigned by the server (the eir_clientid result from EXCHANGE_ID) and should be chosen so that it will not conflict with a client ID previously assigned by the server. This applies across server restarts.
In the event of a server restart, a client may find out that its current client ID is no longer valid when it receives a NFS4ERR_STALE_CLIENTID error. The precise circumstances depend on the characteristics of the sessions involved, specifically whether the session is persistent (see Section 2.10.5.5 (Persistence)), but in each case the client will receive this error when it attempts to establish a new session with the existing client ID and receives the error NFS4ERR_STALE_CLIENTID, indicating that a new client ID must be obtained via EXCHANGE_ID and the new session established with that client ID.
When a session is not persistent, the client will find out that it needs to create a new session as a result of getting an NFS4ERR_BADSESSION, since the session in question was lost as part of a server restart. When the existing client ID is presented to a server as part of creating a session and that client ID is not recognized, as would happen after a server restart, the server will reject the request with the error NFS4ERR_STALE_CLIENTID.
In the case of the session being persistent, the client will re-establish communication using the existing session after the restart. This session will be associated with the existing client ID but may only be used to retransmit operations that the client previously transmitted and did not see replies to. Replies to operations that the server previously performed will come from the reply cache, otherwise NFS4ERR_DEADSESSION will be returned. Hence, such a session is referred to as "dead". In this situation, in order to perform new operations, the client must establish a new session. If an attempt is made to establish this new session with the existing client ID, the server will reject the request with NFS4ERR_STALE_CLIENTID.
When NFS4ERR_STALE_CLIENTID is received in either of these situations, the client must obtain a new client ID by use of the EXCHANGE_ID operation, then use that client ID as the basis of a new session, and then proceed to any other necessary recovery for the server restart case (See Section 8.4.2 (Server Failure and Recovery)).
See the descriptions of EXCHANGE_ID (Section 18.35 (Operation 42: EXCHANGE_ID - Instantiate Client ID)) and CREATE_SESSION (Section 18.36 (Operation 43: CREATE_SESSION - Create New Session and Confirm Client ID)) for a complete specification of these operations.
| TOC |
To facilitate upgrade from NFSv4.0 to NFSv4.1, a server may compare a client_owner4 in an EXCHANGE_ID with an nfs_client_id4 established using the SETCLIENTID operation of NFSv4.0. A server that does so will allow an upgraded client to avoid waiting until the lease (i.e. the lease established by the NFSv4.0 instance client) expires. This requires the client_owner4 be constructed the same way as the nfs_client_id4. If the latter's contents included the server's network address (per the recommendations of the NFSv4.0 specification [21] (Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, C., Eisler, M., and D. Noveck, “Network File System (NFS) version 4 Protocol,” April 2003.)), and the NFSv4.1 client does not wish to use a client ID that prevents trunking, it should send two EXCHANGE_ID operations. The first EXCHANGE_ID will have a client_owner4 equal to the nfs_client_id4. This will clear the state created by the NFSv4.0 client. The second EXCHANGE_ID will not have the server's network address. The state created for the second EXCHANGE_ID will not have to wait for lease expiration, because there will be no state to expire.
| TOC |
NFSv4.1 introduces a new operation called DESTROY_CLIENTID (Section 18.50 (Operation 57: DESTROY_CLIENTID - Destroy existing client ID)) which the client SHOULD use to destroy a client ID it no longer needs. This permits graceful, bilateral release of a client ID. The operation cannot be used if there are sessions associated with the client ID, or state with an unexpired lease.
If the server determines that the client holds no associated state for its client ID (including sessions, opens, locks, delegations, layouts, and wants), the server may choose to unilaterally release the client ID in order to conserve resources. If the client contacts the server after this release, the server must ensure the client receives the appropriate error so that it will use the EXCHANGE_ID/CREATE_SESSION sequence to establish a new client ID. The server ought to be very hesitant to release a client ID since the resulting work on the client to recover from such an event will be the same burden as if the server had failed and restarted. Typically a server would not release a client ID unless there had been no activity from that client for many minutes. As long as there are sessions, opens, locks, delegations, layouts, or wants, the server MUST NOT release the client ID. See Section 2.10.11.1.4 (Loss of Session) for discussion on releasing inactive sessions.
| TOC |
When the server gets an EXCHANGE_ID for a client owner that currently has no state, or that has state, but the lease has expired, the server MUST allow the EXCHANGE_ID, and confirm the new client ID if followed by the appropriate CREATE_SESSION.
When the server gets an EXCHANGE_ID for a new incarnation of a client owner that currently has an old incarnation with state and an unexpired lease, the server is allowed to dispose of the state of the previous incarnation of the client owner if one of the following are true:
If none of the above situations apply, the server MUST return NFS4ERR_CLID_INUSE.
If the server accepts the principal and co_ownerid as matching that which created the client ID, and the co_verifier in the EXCHANGE_ID differs from the co_verifier used when the client ID was created, then after the server receives a CREATE_SESSION that confirms the client ID, the server deletes state. If the co_verifier values are the same, (e.g. the client is either updating properties of the client ID (Section 18.35 (Operation 42: EXCHANGE_ID - Instantiate Client ID)), or the client is attempting trunking (Section 2.10.4 (Trunking)) the server MUST NOT delete state.
| TOC |
The Server Owner is similar to a Client Owner (Section 2.4 (Client Identifiers and Client Owners)), but unlike the Client Owner, there is no shorthand server ID. The Server Owner is defined in the following data type:
struct server_owner4 {
uint64_t so_minor_id;
opaque so_major_id<NFS4_OPAQUE_LIMIT>;
};
The Server Owner is returned from EXCHANGE_ID. When the so_major_id fields are the same in two EXCHANGE_ID results, the connections each EXCHANGE_ID were sent over can be assumed to address the same Server (as defined in Section 1.5 (General Definitions)). If the so_minor_id fields are also the same, then not only do both connections connect to the same server, but the session can be shared across both connections. The reader is cautioned that multiple servers may deliberately or accidentally claim to have the same so_major_id or so_major_id/so_minor_id; the reader should examine Section 2.10.4 (Trunking) and Section 18.35 (Operation 42: EXCHANGE_ID - Instantiate Client ID) in order to avoid acting on falsely matching Server Owner values.
The considerations for generating a so_major_id are similar to that for generating a co_ownerid string (see Section 2.4 (Client Identifiers and Client Owners)). The consequences of two servers generating conflicting so_major_id values are less dire than they are for co_ownerid conflicts because the client can use RPCSEC_GSS to compare the authenticity of each server (see Section 2.10.4 (Trunking)).
| TOC |
With the NFSv4.1 server potentially offering multiple security mechanisms, the client needs a method to determine or negotiate which mechanism is to be used for its communication with the server. The NFS server may have multiple points within its file system namespace that are available for use by NFS clients. These points can be considered security policy boundaries, and in some NFS implementations are tied to NFS export points. In turn the NFS server may be configured such that each of these security policy boundaries may have different or multiple security mechanisms in use.
The security negotiation between client and server must be done with a secure channel to eliminate the possibility of a third party intercepting the negotiation sequence and forcing the client and server to choose a lower level of security than required or desired. See Section 21 (Security Considerations) for further discussion.
| TOC |
An NFS server can assign one or more "security tuples" to each security policy boundary in its namespace. Each security tuple consists of a security flavor (see Section 2.2.1.1 (RPC Security Flavors)), and if the flavor is RPCSEC_GSS, a GSS-API mechanism OID, a GSS-API quality of protection, and an RPCSEC_GSS service.
| TOC |
The SECINFO and SECINFO_NO_NAME operations allow the client to determine, on a per filehandle basis, what security tuple is to be used for server access. In general, the client will not have to use either operation except during initial communication with the server or when the client crosses security policy boundaries at the server. However, the server's policies may also change at any time and force the client to negotiate a new security tuple.
Where the use of different security tuples would affect the type of access that would be allowed if a request was sent over the same connection used for the SECINFO or SECINFO_NO_NAME operation (e.g. read-only vs. read-write) access, security tuples that allow greater access should be presented first. Where the general level of access is the same and different security flavors limit the range of principals whose privileges are recognized (e.g. allowing or disallowing root access), flavors supporting the greatest range of principals should be listed first.
| TOC |
Based on the assumption that each NFSv4.1 client and server must support a minimum set of security (i.e., LIPKEY, SPKM-3, and Kerberos-V5 all under RPCSEC_GSS), the NFS client will initiate file access to the server with one of the minimal security tuples. During communication with the server, the client may receive an NFS error of NFS4ERR_WRONGSEC. This error allows the server to notify the client that the security tuple currently being used contravenes the server's security policy. The client is then responsible for determining (see Section 2.6.3.1 (Using NFS4ERR_WRONGSEC, SECINFO, and SECINFO_NO_NAME)) what security tuples are available at the server and choosing one which is appropriate for the client.
| TOC |
This section explains of the mechanics of NFSv4.1 security negotiation. The term "put filehandle operation" refers to PUTROOTFH, PUTPUBFH, PUTFH, and RESTOREFH.
| TOC |
The client is saving a filehandle for a future RESTOREFH. The server MUST NOT return NFS4ERR_WRONGSEC to either the put filehandle operation or SAVEFH.
| TOC |
For a series of N put filehandle operations, the server MUST NOT return NFS4ERR_WRONGSEC to the first N-1 put filehandle operations. The N'th put filehandle operation is handled as if it is the first in a subseries of operations. For example if the server received PUTFH, PUTROOTFH, LOOKUP, then the PUTFH is ignored for NFS4ERR_WRONGSEC purposes, and the PUTROOTFH, LOOKUP subseries is processed as according to Section 2.6.3.1.3 (Put Filehandle Operation + LOOKUP (or OPEN by Name)).
| TOC |
This situation also applies to a put filehandle operation followed by a LOOKUP or an OPEN operation that specifies a component name.
In this situation, the client is potentially crossing a security policy boundary, and the set of security tuples the parent directory supports may differ from those of the child. The server implementation may decide whether to impose any restrictions on security policy administration. There are at least three approaches (sec_policy_child is the tuple set of the child export, sec_policy_parent is that of the parent).
- a)
- sec_policy_child <= sec_policy_parent (<= for subset). This means that the set of security tuples specified on the security policy of a child directory is always a subset of that of its parent directory.
- b)
- sec_policy_child ^ sec_policy_parent != {} (^ for intersection, {} for the empty set). This means that the security tuples specified on the security policy of a child directory always has a non empty intersection with that of the parent.
- c)
- sec_policy_child ^ sec_policy_parent == {}. This means that the set of tuples specified on the security policy of a child directory may not intersect with that of the parent. In other words, there are no restrictions on how the system administrator may set up these tuples.
For a server to support approach (b) (when client chooses a flavor that is not a member of sec_policy_parent) and (c), the put filehandle operation must NOT return NFS4ERR_WRONGSEC when there is a security tuple mismatch. Instead, it should be returned from the LOOKUP (or OPEN by component name) that follows.
Since the above guideline does not contradict approach (a), it should be followed in general. Even if approach (a) is implemented, it is possible for the security tuple used to be acceptable for the target of LOOKUP but not for the filehandles used in the put filehandle operation. The put filehandle operation could be a PUTROOTFH or PUTPUBFH, where the client cannot know the security tuples for the root or public filehandle. Or the security policy for the filehandle used by the put filehandle operation could have changed since the time the filehandle was obtained.
Therefore, an NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC in response to the put filehandle operation if the operation is immediately followed by a LOOKUP or an OPEN by component name.
| TOC |
Since SECINFO only works its way down, there is no way LOOKUPP can return NFS4ERR_WRONGSEC without SECINFO_NO_NAME. SECINFO_NO_NAME solves this issue via style SECINFO_STYLE4_PARENT, which works in the opposite direction as SECINFO. As with Section 2.6.3.1.3 (Put Filehandle Operation + LOOKUP (or OPEN by Name)), a put filehandle operation that is followed by a LOOKUPP MUST NOT return NFS4ERR_WRONGSEC. If the server does not support SECINFO_NO_NAME, the client's only recourse is to send the put filehandle operation, LOOKUPP, GETFH sequence of operations with every security tuple it supports.
Regardless of whether SECINFO_NO_NAME is supported, an NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC in response to a put filehandle operation if the operation is immediately followed by a LOOKUPP.
| TOC |
A security sensitive client is allowed to choose a strong security tuple when querying a server to determine a file object's permitted security tuples. The security tuple chosen by the client does not have to be included in the tuple list of the security policy of the either parent directory indicated in the put filehandle operation, or the child file object indicated in SECINFO (or any parent directory indicated in SECINFO_NO_NAME). Of course the server has to be configured for whatever security tuple the client selects, otherwise the request will fail at RPC layer with an appropriate authentication error.
In theory, there is no connection between the security flavor used by SECINFO or SECINFO_NO_NAME and those supported by the security policy. But in practice, the client may start looking for strong flavors from those supported by the security policy, followed by those in the REQUIRED set.
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC to a put filehandle operation that is immediately followed by SECINFO or SECINFO_NO_NAME. The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC from SECINFO or SECINFO_NO_NAME.
| TOC |
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC.
| TOC |
"Anything Else" includes OPEN by filehandle.
The security policy enforcement applies to the filehandle specified in the put filehandle operation. Therefore the put filehandle operation must return NFS4ERR_WRONGSEC when there is a security tuple mismatch. This avoids the complexity adding NFS4ERR_WRONGSEC as an allowable error to every other operation.
A COMPOUND containing the series put filehandle operation + SECINFO_NO_NAME (style SECINFO_STYLE4_CURRENT_FH) is an efficient way for the client to recover from NFS4ERR_WRONGSEC.
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC to any operation other than a put filehandle operation, LOOKUP, LOOKUPP, and OPEN (by component name).
| TOC |
Suppose a client sends a COMPOUND procedure containing the series SEQUENCE, PUTFH, SECINFO_NONAME, READ, and suppose the security tuple used does not match that required for the target file. By rule (see Section 2.6.3.1.5 (Put Filehandle Operation + SECINFO/SECINFO_NO_NAME)), neither PUTFH nor SECINFO_NO_NAME can return NFS4ERR_WRONGSEC. By rule (see Section 2.6.3.1.7 (Put Filehandle Operation + Anything Else)), READ cannot return NFS4ERR_WRONGSEC. The issue is resolved by the fact that SECINFO and SECINFO_NO_NAME consume the current filehandle (note that this is a change from NFSv4.0). This leaves no current filehandle for READ to use, and READ returns NFS4ERR_NOFILEHANDLE.
| TOC |
To address the requirement of an NFS protocol that can