]> Independent

United States of America cel-ietf@chucklever.net

Web and Internet Transport Network File System Version 4 NFS ACL This Informational document describes the NFS_ACL protocol. NFS_ACL is a legacy member of the Network File System family of protocols that NFS clients use to view and update Access Control Lists stored on an NFS version 2 or version 3 server. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Network File System Version 4 Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The Network File System protocol (NFS) was introduced by Sun Microsystems in the 1980s. This protocol enabled applications to access and modify files, via local POSIX system interfaces, that reside on a remote host . Traditionally, permission to access files stored in NFS file systems is granted by permission bits, mimicking . Permission bits provide coarse-grained access control. The file owner can control only whether members of her group can read, write, or execute the file contents, or whether anyone else (without exception) has those rights. An Access Control List, or ACL, is a mechanism that enables file owners to grant specific users fine-grained access rights to file content . Version 2 of NFS is described in , and version 3 in . Neither of these protocols include a method for managing ACLs associated with files shared via the NFS protocol, even though the local file systems shared via NFS often implemented ACLs and gave local users mechanisms to read and update them. Sun created the NFS_ACL protocol to provide that mechanism for files accessed remotely via NFS. Later, other operating systems, including Linux, implemented NFS_ACL for similar reasons. This document describes the protocol based on the nfs_acl.x file that is publicly available in the OpenSolaris code base . The editor has attempted to introduce no changes to the protocol as it is implemented in OpenSolaris and in Linux. The document assumes readers are already familiar with the NFS version 2 or 3 protocols and at least one implementation of them. Issues of compatibility between the protocol described in this document and NFSv4 ACLs (as described by ) are considered out of scope. More information on this topic is available in . Local file systems on NFSv2 and NFSv3 servers determine the particular semantics of each Access Control List -- in other words, how the server uses each Access Control List to authorize access to file content. This document serves only as a description of the network protocol used to exchange ACLs between NFS clients and servers.

Conventions and Definitions As an Informational document, this RFC does not make compliance mandates on implementations of the protocol described herein. Therefore it does not make use of the conformance language described in BCP 14 . A capitalized key word that appears in text quoted from another document carries the meaning that document gives it.

Glossary The following are a set of foundational terms used throughout this document.

application:

A program that executes on a client system.

client:

A computer system that utilizes compute resources provided by one or more servers.

file:

A unit of data storage consisting of an ordered stream of bytes and a set of metadata attributes.

gid:

A 32-bit unsigned integer that represents a group of users.

server:

A computer system that provides compute resources to network peers.

uid:

A 32-bit unsigned integer that represents a specific user.

user:

A person logged in on a client system.

General Concepts

Remote Procedure Call The Sun Remote Procedure Call (SunRPC) protocol provides a procedure-oriented interface to remote services. Each server supplies a program, which is a set of procedures. The NFS service is one such program. The combination of host address, program number, version number, and procedure number specify one remote service procedure. Servers can support multiple versions of a program that are accessed using different protocol version numbers. The NFS and NFS_ACL protocols are both based on SunRPC. The remainder of this document assumes an NFS environment that is implemented on top of SunRPC, as it is specified in .

External Data Representation The eXternal Data Representation (XDR) specification provides a standard way of representing a set of data types on a network. XDR addresses the problem of communication between network peers with different byte orders, structure alignment, and data type representation. This document utilizes the RPC Data Description Language to specify the XDR format arguments and results to each of the RPC service procedures that an NFS_ACL server provides. Readers can find a full guide to XDR and the RPC Data Description Language in .

XDR Types Not Defined in RFC 4506 The original NFS_ACL RPC language specification uses the "unsigned short" and "unsigned long" types. describes neither, though most current implementations of the rpcgen program accept both. This section describes the "unsigned short" and "unsigned long" integer types as used in this document, based on those implementations, so that the NFS_ACL RPC language specification appearing here accurately reflects the wire behavior of existing implementations. It does not add these types to the RPC Data Description Language. The XDR wire representation of each of these types is a network-endian 32-bit integer. This maintains XDR's consistent 4-octet alignment for all basic integer types while allowing applications to use narrower types internally. The subsections below describe how a value of each type occupies that 32-bit field.

unsigned short The unsigned short type is zero-extended, with the high-order two octets each containing zeroes on the wire. The value range of this type is zero to 65,535, inclusive. Example: 0xFFFF (65535) appears as 0x0000FFFF on the wire.

unsigned long The unsigned long type occupies all four octets of the 32-bit field and requires no extension. Its wire representation is identical to that of the "unsigned int" type described in . The value range of this type is zero to 4,294,967,295, inclusive. The NFS version 3 protocol specification uses this type name for 32-bit unsigned quantities, and this document retains it in the data types that it inherits from that protocol.

Authentication and Authorization The RPC protocol includes fields in every procedure call for user authentication parameters. The specific content of the authentication parameters is determined by the type of authentication used by the server and client. A discussion of the mechanics of RPC user authentication appears in , in particular Sections 9 and 10. For NFS ACLs, the user ID carried in RPC calls is used for two purposes:

• When setting an ACL via the SETACL procedure, the NFS_ACL service verifies that the calling user has been granted permission to perform the procedure. The GETACL procedure carries no such check of its own. The server passes the calling user's credential to the local file system, which may or may not restrict who can read an object's ACL.
• Each Access Control Entry (see below) contains an element that identifies the user to which the ACE applies. That user is represented by a 32-bit user ID. The value of the user ID in each ACE has the same meaning and mapping as the value of incoming RPC calls.

Using user ids and group ids implies that the client and server either share the same ID list or do local user and group ID mapping. Servers and clients must agree on the mapping from user to uid and from group to gid, for those sites that do not implement a consistent user ID and group ID number space. In practice, such mapping is typically performed on the server, following a static mapping scheme or a mapping established by the user from a client at mount time. RPCSEC_GSS authentication provides stronger security through the use of cryptographic authentication. The server and client must agree on the mapping of the user's GSS principal to a local UID on the server, but the name to identity mapping is more operating system independent than the uid and gid mapping in AUTH_SYS.

File Access Control This section describes the abstractions that an NFS server uses to determine whether an access or modification to a file is permitted. The exact behavior of a server implementation may vary.

File Ownership A file's "owner" is the designated user that is always granted permission to update that file's security attributes. As part of creating a file, the NFS server assigns the file's owner. Under normal circumstances the initial file owner is the RPC user who issued the NFS CREATE procedure. However, server security policies can mandate replacement of that user (also known as user squashing) as part of processing a CREATE procedure. An existing file's designated owner can subsequently be changed by an NFS SETATTR procedure. After that change, the new owner is granted permission to update the file's security attributes and the old owner is no longer treated specially. A file's "owner group" is a short list of users that have similar privileges as the file's owner, but are treated as a separate category for the purpose of permission checking. Any user who is not a file's owner or a member of its owner group falls into the third category, known as "everyone" or "other".

Superuser Access On most operating systems, there is a category of users known as privileged users or superusers. These users can bypass most or all access controls on files.

Categories of Access In NFS versions 2 and 3, there are three rudimentary categories of access:

Read access:

Read access grants permission for a user to read a file or directory.

Write access:

Write access grants permission for a user to modify a file or directory.

Execute access:

For a file, execute access grants permission for the user to treat the file content as executable. For a directory object, execute access grants permission for the user to perform a lookup in that directory.

Traditional Permission Bits Permission bits, or mode bits, are the simplest and perhaps oldest form of access control. Each file object has a set of mode bits . Each of the user categories is given a set of three access type bits. Altogether there are then nine bit flags for every file object.

Access Control Lists An Access Control Entry, or ACE, represents a set of access categories and a specific user or group. An Access Control List is a list of ACEs. Mode bits, as explained in the previous section, are essentially an ACL that always contains exactly three ACEs: one for the file's owner, one for the file's owner group, and one for everyone else.

Interpreting Access Control Lists NFS clients do not perform access checks based on their interpretation of an ACL read from the server. NFS servers are solely responsible for authorizing and restricting access to file content via the NFS protocol. An NFS Access Control List is a list of three or more Access Control Entries (ACEs) associated with one file system object. Each Access Control Entry in this list specifies a user and a set of access types granted to that user. Only ACEs that match the requester are considered. Each ACE is processed until all of the bits of the requester's access have been ALLOWED. Once a bit has been ALLOWED, that bit is no longer considered in the processing of subsequent ACEs in the list. When the ACL has been fully processed, if there are bits in the requester's mask that have not been ALLOWED, access of that type is denied. Note that an ACL might not be the sole determiner of access. For example:

• In the case of a file system exported as read-only, the server may deny write access even though an object's ACL grants it.
• Server implementations can grant some limited permission to update an ACL in order to prevent a situation from arising in which there is no valid way to ever modify the ACL.
• Server implementations can allow a user to read the data of a file when only the execute permission is granted (that is, when the ACL denies the user NA_READ but allows NA_EXEC), since a server has to read the file to execute it.
• Some server implementations have the notion of owner-override, in which the owner of the object is allowed to override accesses that are denied by the ACL. This can be helpful, for example, to allow users continued access to open files on which the permissions have changed.
• Some server implementations have the notion of a "superuser" that has privileges beyond an ordinary user. The superuser may be able to read or write data or metadata in ways that would otherwise not be permitted by the object's ACL.

NFS clients can use either the NFS_ACL version 2 ACCESS procedure or the NFS version 3 ACCESS procedure to ask the server to perform an access check based on the requesting user and the ACL present on a file system object. Clients are also free to simply try an operation to see what works, then recover if the server denies access.

ACLs in Operation The SETACL procedure sets two types of Access Control Lists:

Access:

An NFS access ACL specifies the access permission for a file object. Access Control Entries in an ACL's "aclent" field comprise the object's access ACL.

Default:

An NFS default ACL specifies the default ACL that is set on objects that are children of a directory. Access Control Entries in an ACL's "dfaclent" comprise an object's default ACL. The default ACL does not affect access to the object on which it is set.

An access ACL, and a default ACL that has any ACEs, must have one ACE for each of NA_USER_OBJ, NA_GROUP_OBJ, and NA_OTHER_OBJ. An NFS ACL that consists only of these three ACEs is referred to as a minimal NFS ACL. A default ACL with no ACEs means the directory has no default ACL. An NFS ACL may have zero or more NA_USER and/or NA_GROUP ACEs. On the wire, a minimal NFS ACL is represented as either three or four Access Control Entries.

• A sender can send the list as the file system stores it. Such a sender sends three entries for an object whose ACL has no mask entry, and four for a manufactured ACL (), which always occupies four entries in the "aclent" array and none in the "dfaclent" array and whose NA_CLASS_OBJ entry is not always formed as described above. A receiver accepts either representation in either array.
• A sender can expand a three-entry list to four. Such a sender adds an NA_CLASS_OBJ entry to the NA_USER_OBJ, NA_GROUP_OBJ, and NA_OTHER_OBJ entries, and derives that entry's "perm" element from the permission bits of the object's owning group, in both the "aclent" and the "dfaclent" array.

The two representations are not interchangeable in every case. Implementations follow different drafts of POSIX 1003.1e, and the drafts differ in their treatment of the mask entry in a four-entry ACL; describes the difference. A receiver that follows draft 17 removes the NA_CLASS_OBJ entry from a four-entry list when its "perm" element equals that of the NA_GROUP_OBJ entry, restoring the three-entry form, and keeps the entry when the two differ. The Access Control Entries in the "aclent" and "dfaclent" arrays can appear in any order. A receiver does not depend on the order in which the entries arrive. When a client presents a SETACL operation that a server finds is invalid or it cannot process, the server responds with ACL2ERR_INVAL or ACL3ERR_INVAL, depending on the version of NFS_ACL that is in use. ACLs that are not valid include:

• The presented ACL does not contain one ACE for each of NA_USER_OBJ, NA_GROUP_OBJ, and NA_OTHER_OBJ
• The presented ACL contains an NA_GROUP ACE but no NA_CLASS_OBJ ACE
• The presented ACL is a default ACL but the target object is not a directory
• The presented ACL contains an ACE whose "type" field sets more than one of the base type values NA_USER_OBJ, NA_USER, NA_GROUP_OBJ, NA_GROUP, NA_CLASS_OBJ, and NA_OTHER_OBJ (the NA_ACL_DEFAULT flag may accompany exactly one such value)
• The presented ACL contains an ACE whose type or perm field has a bit set that is not defined by this protocol
• The count for a non-empty "aclent" or "dfaclent" array differs from the number of entries in that array

Whether an ACL that contains an NA_USER ACE but no NA_CLASS_OBJ ACE is valid depends on the exported file system. A server responds with ACL2ERR_INVAL or ACL3ERR_INVAL when the exported file system rejects such an ACL. An ACL that has no more than NFS_ACL_MAX_ENTRIES entries in each array can still exceed what the exported file system stores in one ACL. A server reports that with ACL2ERR_NOSPC or ACL3ERR_NOSPC, or with ACL2ERR_INVAL or ACL3ERR_INVAL when the file system rejects the list as invalid. The NA_ACL_DEFAULT bit is a flag that a sender combines with one of the base type values (for example, NA_ACL_DEFAULT | NA_USER_OBJ) to mark an Access Control Entry as a default entry: one that a directory contributes to its newly created children rather than one that controls access to the directory itself. Every entry in the "dfaclent" array has the NA_ACL_DEFAULT bit set in its "type" field, and no entry in the "aclent" array has it set. Segregating default entries into the separate "dfaclent" array makes the flag redundant on the wire; a sender nonetheless sets it on every "dfaclent" entry so that a receiver can reconstruct the single, flag-tagged Access Control list that some file access APIs present to applications. The "id" field in an Access Control Entry is interpreted as follows:

• For an ACE that specifies an NA_USER_OBJ, NA_USER, NA_GROUP, and NA_GROUP_OBJ, the "id" field contains a UID or GID value that identifies the user on the server whose access permission is being set.
• For an ACE that specifies other types of permission (for example, NA_CLASS_OBJ or NA_OTHER_OBJ), the "id" field is undefined. A sender sets this field to zero, and a receiver ignores its value.

Relationship Between ACLs and Other File Attributes When an ACL is present on a file, the ACL controls the requesting user's access to the file. Typically the NFS server ignores the file's mode bits. Depending on the behavior of the local file system implementation, changing the file's ACL via the SETACL procedure may alter the file's mode bits, and changing the mode bits via the SETATTR procedure may alter the content of the ACL in any way. NFS clients should refresh cached ACLs or file modes after one of these operations. When an ACL is present on a file, changing the file's owner (say, via the SETATTR operation) may alter the server's interpretation of any ACE that targets NA_USER_OBJ. When an ACL is present on a file, changing the file's group (say, via the SETATTR operation) may alter the server's interpretation of any ACE that targets NA_GROUP_OBJ. If an NFS client observes that a file's ctime attribute has changed, it should assume that any ACLs that are present might have been modified.

ACL Inheritance A directory's default ACL takes effect when a client uses one of the NFS CREATE, MKDIR, or MKNOD procedures to create an object in that directory. The exported file system derives the new object's access ACL and mode bits from the parent's default ACL and the mode the client requested, and gives a new directory the parent's default ACL as its own. That derivation is a property of the exported file system rather than of this protocol. describes the POSIX 1003.1e rules for that derivation, including how a default ACL takes the place of the umask. A client observes the result by retrieving the new object's ACL with GETACL.

Historical References The section entitled "The POSIX 1003.1e/1003.2c Working Group" in details the history of POSIX standards efforts with regard to file access control. The editor recommends that readers familiarize themselves with the extent to which POSIX specifies the content and behavior of ACLs.

Protocol Elements Common to Both Versions

RPC Authentication The NFS_ACL service uses AUTH_NONE in the NULL procedure. All RPC authentication flavors may be used for other procedures. That records what implementations accept, not what a deployment should use; see and .

Constants These are the RPC constants needed to call the NFS_ACL service. They are given in decimal.

100227

The RPC program number for the NFS_ACL protocol

This document describes versions 2 and 3 of this RPC program. Version 4 was used by a Solaris prototype and is not available for reuse (see ).

Transport address The NFS_ACL protocol can operate over the TCP and UDP transport protocols, on port 2049, and over RPC-over-RDMA version 1 , on port 20049. In each case this is the port of the NFS service that NFS_ACL accompanies. gives the upper-layer binding for NFS_ACL on RPC-over-RDMA.

Sizes The maximum number of Access Control Entries allowed in one Access Control List array.

Basic Data Types The following XDR definitions are basic scalar types that are used in other structures.

Structured Data types The following XDR definitions are common structured data types that are used in all versions of the NFS_ACL protocol.

aclent This structure represents a single entry in an Access Control List. The "type" element in an Access Control Entry is a bit mask. The bit field values in this mask are defined as follows: The "perm" element in an Access Control Entry is also a bit mask. The bit field values in this mask are defined as follows:

secattr The secattr structure represents, on the wire, the full Access Control List for one file system object. This list contains an array of Access Control Entries that apply to the object, plus an array of default Access Control Entries that are inherited by the object's children. ; int dfaclcnt; aclent dfaclent; }; ]]> The "aclcnt" and "dfaclcnt" elements carry the number of Access Control Entries in the object's access ACL and default ACL. A count is meaningful whether or not its array is present: a GETACL reply carries a count for an array whose count bit alone is set, and carries that array empty (see and ). The "mask" element of the secattr structure is a bit mask. The bit field values in this mask are defined as follows: These bit field values are also used in the "mask" element of the GETACL2args and GETACL3args structures. In a GETACL reply, the "mask" element of the returned secattr structure carries the same value as the "mask" element of the request. Because the server fills in fields as the request's "mask" selects them, the reply's "mask" also identifies which arrays the reply carries. A client decodes a GETACL reply according to the reply's "mask" and treats a reply whose "mask" lacks a bit the request set as an error. A sender sets no bit in a "mask" element other than the four defined here. A server that receives a request with an undefined bit set either responds with ACL2ERR_INVAL or ACL3ERR_INVAL or ignores the bit and processes the defined ones. Because a GETACL reply's "mask" echoes the request, the reply can carry the undefined bit.

The "mask" Element in a SETACL Request In a GETACL request the "mask" element selects which fields the server fills in, as described in and . In a SETACL request the element carries the same bit values, and a server interprets it in one of two ways. A server can treat the element as selective. Such a server replaces the object's access ACL only when NA_ACL is set and the object's default ACL only when NA_DFACL is set, and leaves an unselected list as it found it. A server can instead disregard the element and store the entries the request carries. Such a server rejects a request whose "mask" is zero with ACL2ERR_INVAL or ACL3ERR_INVAL, and otherwise replaces both of the object's lists on every SETACL, so the entries of a list the sender leaves empty are removed from the object rather than preserved. When the exported file system does not store the form of ACL that NFS_ACL carries, such a server responds with ACL2ERR_NOTSUPP or ACL3ERR_NOTSUPP as described in . A SETACL that sets one of NA_ACL and NA_DFACL and clears the other therefore has no single meaning. Sent to a directory that holds both an access ACL and a default ACL, it preserves the unselected list on a server that treats the element as selective and removes that list's entries on a server that stores what it receives. A client cannot tell from the SETACL reply which way the server behaved. A SETACL that sets both bits and carries both lists has the same effect on either server, so a client that reads back the list it does not intend to change and sends it unaltered is unaffected by the divergence. A client that discards its cached copy after a SETACL rather than caching what it sent is likewise unaffected by any difference between what it sent and what the server stored. A client that instead sends the "mask" element as the local application supplied it, without reading back the other list, can send a SETACL that carries one bit without the other. Such a request relies on the server storing exactly what it receives. A server that treats the element as selective leaves the unsent list as it found it, so the object ends up with a different ACL than the application supplied.

Interoperability Considerations Interoperability between NFS peers that do not implement the NFS_ACL protocol is what we already have today. Interoperability between peers that both implement the NFS_ACL protocol is described in the rest of this document. The following subsections briefly discuss three new interoperability scenarios.

Client Implements NFS_ACL, Server Does Not An NFS server that implements the NFS_ACL program can advertise it via an rpcbind registration . A client can query rpcbind before its first NFS_ACL procedure, or it can send a procedure and treat the outcome as a probe for service availability. When a client sends an NFS_ACL procedure to a server that does not implement the program, the server responds with an RPC accept_stat of PROG_UNAVAIL ().

Server Implements NFS_ACL, Client Does Not An NFS server that implements advanced access control can deny requests made by a client by responding with NFSERR_ACCES or NFS3ERR_ACCES status codes, and an NFS client has no visibility as to why the denial occurred. Neither can that client send operations to update the access control on file objects. This is a quality of implementation issue for the client.

Client Implements, Exported File System Does Not An NFS server that implements the NFS_ACL protocol might share both file systems that implement ACLs and file systems that do not. In this case, NFS clients detect the presence of an NFS_ACL service on the NFS server. A file system that implements access control lists of a different form than NFS_ACL carries behaves as this section describes for every object it holds. GETACL returns a manufactured ACL, and SETACL fails. For file objects that do not implement ACL support:

• The server responds to a GETACL procedure by returning a manufactured minimal ACL that reflects the current mode bits of the object. The manufactured ACL has four Access Control Entries in the "aclent" array and none in the "dfaclent" array; the server does not manufacture a default ACL. The "perm" element of the manufactured NA_CLASS_OBJ entry either reflects the permission bits of the object's owning group, as describes for an expanded list, or is 7 (NA_READ, NA_WRITE, and NA_EXEC) regardless of those bits. A receiver therefore cannot take a manufactured ACL whose NA_CLASS_OBJ and NA_GROUP_OBJ "perm" elements differ as evidence of an extended ACL.
• The server responds to a SETACL version 3 procedure by returning ACL3ERR_NOTSUPP.
• The server responds to a SETACL version 2 procedure by returning ACL2ERR_NOTSUPP.

NFS_ACL Version 2 Version 2 of the NFS_ACL protocol is used in conjunction only with version 2 of the NFS protocol.

Data types inherited from NFS version 2

ftype The enumeration "ftype" gives the type of an NFS version 2 file. This definition comes from :

fhandle NFS version 2 uses a fixed-size file handle. The following definition comes from :

timeval NFS version 2's "timeval" structure represents the number of seconds and microseconds since midnight January 1, 1970, Greenwich Mean Time. This definition comes from :

nfsfattr This document refers to NFS version 2's file attribute structure as "nfsfattr". This is the same as the fattr structure described in :

Defined Error Numbers describes an enumerated type called "stat" which provides a status code for NFS version 2 results. A matching type called "aclstat2" is defined in this document for the similar purpose of returning NFS_ACL version 2 procedure status codes. The numeric values of these two types match up, though aclstat2 omits some codes that are not relevant to the NFS_ACL protocol. The "stat" type in does not define a status code corresponding to the POSIX EINVAL error. However, existing NFS_ACL version 2 server implementations return the value 22 (the numeric value of EINVAL) when a client presents an invalid argument to a procedure. The aclstat2 type therefore defines ACL2ERR_INVAL with that value, even though the NFS version 2 "stat" type has no matching code. Similarly, the "stat" type does not define a status code that reports that a requested operation is not supported. The original NFS_ACL version 2 server implementation returns the value 45 (its NFSERR_OPNOTSUPP status code) when a client directs an operation at a file object whose file system does not support ACLs. The aclstat2 type therefore defines ACL2ERR_NOTSUPP with that value. A server returns ACL2ERR_NOTSUPP in NFS_ACL version 2 results; the numeric value 10004 that NFS version 3 assigns to NFS3ERR_NOTSUPP is not used in NFS_ACL version 2 results. These status codes carry the following meanings:

ACL2ERR_PERM

Not owner. The caller does not have correct ownership to perform the requested operation.

ACL2ERR_NOENT

No such file or directory. The file or directory name specified does not exist.

ACL2ERR_IO

Some sort of hard error occurred when the operation was in progress. This could be a disk error, for example.

ACL2ERR_ACCES

Permission denied. The caller does not have the correct permission to perform the requested operation.

ACL2ERR_INVAL

An invalid or unsupported argument was specified for procedure.

ACL2ERR_NOSPC

No space left on device. The operation caused the server's file system to reach its limit.

ACL2ERR_ROFS

Read-only file system. Write attempted on a read-only file system.

ACL2ERR_NOTSUPP

Operation is not supported.

ACL2ERR_DQUOT

Disk quota exceeded. The client's disk quota on the server has been exceeded.

ACL2ERR_STALE

The "fhandle" given in the arguments was invalid. That is, the file referred to by that file handle no longer exists, or access to it has been revoked.

Server Procedures The ERRORS subsection of each procedure enumerates the status values a server returns from that procedure.

Procedure 0: NULL - No Operation

ARGUMENTS

RESULTS

DESCRIPTION This is the usual NULL procedure with a void argument and void result.

IMPLEMENTATION It is important that this procedure do no work at all so that clients can use it to measure the overhead of processing a service request. By convention, the NULL procedure should never require any authentication. A server implementation may choose to ignore this convention, if responding to the NULL procedure call acknowledges the existence of a resource to an unauthenticated client.

ERRORS Since the NULL procedure returns no result, it can not return an NFS_ACL error status code. However, some server implementations may return RPC-level errors based on security or authentication policy settings.

Procedure 1: GETACL - Retrieve an Access Control List

ARGUMENTS

RESULTS

DESCRIPTION The GETACL procedure retrieves Access Control List information associated with the file system object specified by the GETACL2args.fh field. The client obtains this file handle using one of the NFS version 2 LOOKUP, CREATE, MKDIR, or SYMLINK procedures, or the MOUNT service, as described in . The GETACL2args.mask field specifies which information is to be returned in the response:

• If the NA_ACL bit is set, the server fills in the object's access ACL.
• If the NA_ACLCNT bit is set, the server fills in the number of ACEs that are in the object's access ACL.
• If the NA_DFACL bit is set, the server fills in the object's default ACL.
• If the NA_DFACLCNT bit is set, the server fills in the number of ACEs that are in the object's default ACL.

The server fills in a count whenever either bit for that array is set, and fills in the array itself only when the array's own bit is set. An array the server does not fill in is empty on the wire. The reply's "mask" element carries the request's value (see ). If the GETACL procedure is successful, the server sets the GETACL2res.status field to ACL2_OK. It fills in the GETACL2resok.attr field with the file object's current file attributes, as detailed in . Lastly, it fills in the GETACL2resok.acl field with two counted arrays of Access Control Entries (ACEs). Otherwise, GETACL2res.status contains an error status on failure and no other results are returned.

IMPLEMENTATION When GETACL2args.fh represents a file object that does not currently have an ACL associated with it or does not implement support for ACLs, the server responds by returning a manufactured minimal NFS ACL that reflects the current owner, group, and mode bits of the object (see ). A default ACL applies only to a directory object. When GETACL2args.fh represents an object that is not a directory, that object has no default ACL. If the request's NA_DFACL or NA_DFACLCNT bit is set, the server returns an empty dfaclent array and a dfaclcnt of zero rather than reporting an error.

ERRORS

• ACL2ERR_IO
• ACL2ERR_ACCES
• ACL2ERR_INVAL
• ACL2ERR_STALE

Procedure 2: SETACL - Set or replace an Access Control List

ARGUMENTS

RESULTS

DESCRIPTION The SETACL procedure replaces the Access Control Lists associated with the file system object specified by the SETACL2args.fh field with the ACLs specified by the SETACL2args.acl field. The client obtains the file handle using one of the NFS version 3 LOOKUP, CREATE, MKDIR, SYMLINK procedures, or the MOUNT service, as described in . To remove extended access control from a file object, a client uses SETACL to replace the object's ACL with a minimal NFS ACL (see ). To remove a directory's default ACL, a client sends a SETACL with both the NA_ACL and NA_DFACL bits set, an empty "dfaclent" array, and the directory's current access ACL in "aclent" (see ). If the SETACL procedure is successful, the server sets the SETACL2res.status field to ACL2_OK and fills in the SETACL2resok.attr field with the file object's new file attributes, as detailed in . Otherwise, SETACL2res.status contains an error status on failure and no other results are returned.

IMPLEMENTATION A successful reply means that the exported file system has verified the new ACL, but does not mean that the change has reached stable storage. Changing a file object's ACL changes the object's ctime. The ctime change is reflected in the attributes returned in the SETACL response. A high-quality server implementation ensures that a GETACL procedure running concurrently with a SETACL procedure does not return partially updated (torn) ACL contents. However, a failed SETACL may partially change a file's ACLs. When SETACL2args.fh represents a file object that does not implement support for ACLs, the server responds by setting SETACL2res.status to ACL2ERR_NOTSUPP. When the new ACL does not contain at least the minimal set of ACEs (as described in ), the server responds by setting SETACL2res.status to ACL2ERR_INVAL. Servers differ in how they treat the "mask" element of SETACL2args.acl. describes the divergence and how a client avoids it.

ERRORS

• ACL2ERR_ROFS
• ACL2ERR_PERM
• ACL2ERR_IO
• ACL2ERR_ACCES
• ACL2ERR_INVAL
• ACL2ERR_NOSPC
• ACL2ERR_NOTSUPP
• ACL2ERR_DQUOT
• ACL2ERR_STALE

Procedure 3: GETATTR - Get file attributes

ARGUMENTS

RESULTS

DESCRIPTION The GETATTR procedure retrieves the current file attributes associated with the file system object specified by the GETATTR2args.fh field. The client obtains this file handle using one of the NFS version 2 LOOKUP, CREATE, MKDIR, SYMLINK procedures, or the MOUNT service, as described in . If the GETATTR procedure is successful, the server sets the GETATTR2res.status field to ACL2_OK, and fills in the GETATTR2resok.attr field with the file object's current file attributes, as detailed in . Otherwise, GETATTR2res.status contains an error status on failure and no other results are returned.

IMPLEMENTATION Refer to for details about the content of the returned file attributes.

ERRORS

• ACL2ERR_IO
• ACL2ERR_STALE

Procedure 4: ACCESS - Check access permission

ARGUMENTS

RESULTS

DESCRIPTION The ACCESS procedure determines the access rights that a user, as identified by the RPC credentials in the request, has with respect to the file handle specified by the ACCESS2args.fh field. The client obtains this file handle using one of the NFS version 2 LOOKUP, CREATE, MKDIR, SYMLINK procedures, or the MOUNT service, as described in . The client encodes the set of permissions that are to be checked in the ACCESS2args.access field. The following access permissions may be requested:

ACCESS2_READ

Read data from file or read a directory.

ACCESS2_LOOKUP

Look up a name in a directory (no meaning for non-directory objects).

ACCESS2_MODIFY

Rewrite existing file data or modify existing directory entries.

ACCESS2_EXTEND

Write new data or add directory entries.

ACCESS2_DELETE

Delete an existing directory entry (no meaning for non-directory objects).

ACCESS2_EXECUTE

Execute file (no meaning for a directory).

A server grants no permission that this protocol does not define. A bit set in ACCESS2args.access that is not listed above is clear in ACCESS2resok.access. If the ACCESS procedure is successful, the server sets the ACCESS2res.status field to ACL2_OK. It fills in the ACCESS2resok.attr field with the file object's current file attributes, as detailed in . Lastly, it encodes the set of permissions that the requesting user is granted in the ACCESS2resok.access field.

IMPLEMENTATION In the NFS version 2 protocol, the only reliable way to determine whether an operation is allowed is to try it and see if it succeeded or failed. Using the ACCESS procedure in the NFS_ACL version 2 protocol, a client can ask the server to indicate whether or not one or more classes of operations are permitted. In general, it is not sufficient for a client to attempt to deduce access permissions by inspecting the uid, gid, and mode fields in the file attributes, since the server may perform uid or gid mapping or enforce additional access control restrictions. It is also possible that the NFS version 2 protocol server may not be in the same ID space as the NFS version 2 protocol client. In these cases, the NFS version 2 protocol client can not reliably perform an access check with only current file attributes. The information returned by the server in response to an ACCESS call is advisory only. It was correct at the exact time that the server performed the checks, but not necessarily afterwards. The server can revoke access permission to a file object at any time. The NFS_ACL version 2 protocol client should use the effective credentials of the user to build the authentication information in the ACCESS request used to determine access rights. It is the effective user and group credentials that are used in subsequent read and write operations. Many implementations do not directly support the ACCESS2_DELETE permission. Operating systems like UNIX may ignore the ACCESS2_DELETE bit if set on an access request on a non-directory object. In these systems, delete permission on a file is determined by the access permissions on the directory in which the file resides, instead of being determined by the permissions of the file itself. Thus, the bit mask returned for such a request will have the ACCESS2_DELETE bit set to 0, indicating that the client does not have this permission. The server should return a status of ACL2_OK if no errors occurred that prevented the server from making the required access checks.

ERRORS

• ACL2ERR_IO
• ACL2ERR_STALE

Procedure 5: GETXATTRDIR - Get named attribute directory

ARGUMENTS

RESULTS

DESCRIPTION defines a set of generic file attributes known as "named attributes". The GETXATTRDIR procedure extends this facility into the NFSv2 protocol. The GETXATTRDIR procedure obtains the file handle of the named attribute directory associated with the file handle in the GETXATTRDIR2args.fh field. This directory contains only objects of type NFREG. If the GETXATTRDIR procedure is successful, the server sets the GETXATTRDIR2res.status field to ACL2_OK. It fills in the GETXATTRDIR2resok.fh field with a file handle that the client may use to look up the target file's named attributes. It fills in the GETXATTRDIR2resok.attr field with the named attribute directory's current file attributes, as detailed in . Using the file handle returned in GETXATTRDIR2resok.fh, a client can utilize the READDIR and LOOKUP procedures to obtain file handles for the named attributes associated with the target file system object. If the target file object does not currently have a named attribute directory associated with it and the GETXATTRDIR2args.create boolean field is set to false, the server returns ACL2ERR_NOENT. If the target file object does not currently have a named attribute directory associated with it and the GETXATTRDIR2args.create boolean field is set to true, the server attempts to create the named attribute directory before returning a result. If the target file currently has a named attribute directory associated with it and the GETXATTRDIR2args.create boolean is set to true, the server returns the file handle of that named attribute directory. If the RPC user does not have read access to the target file, or if the GETXATTRDIR operation is to create a named attribute directory and the RPC user does not have permission to do so, the server returns ACL2ERR_ACCES in the GETXATTRDIR2res.status field. If the target file handle designates an object not of type NFREG or NFDIR, the server returns the value ACL2ERR_INVAL in the GETXATTRDIR2res.status field. Neither named attributes nor named attribute directories have their own named attributes. Note: This operation is equivalent to the NFSv4 OPENATTR operation as specified in and .

IMPLEMENTATION Server implementers are free to choose not to implement this procedure. In this case, the server returns the RPC-level error PROC_UNAVAIL. If the server implementation does implement the GETXATTRDIR procedure but the shared file system containing the file object specified by the file handle in the GETXATTRDIR2args.fh field does not support named attributes, the server returns ACL2ERR_NOTSUPP in the GETXATTRDIR2res.status field.

ERRORS

• ACL2ERR_PERM
• ACL2ERR_NOENT
• ACL2ERR_IO
• ACL2ERR_ACCES
• ACL2ERR_INVAL
• ACL2ERR_NOSPC
• ACL2ERR_ROFS
• ACL2ERR_STALE
• ACL2ERR_NOTSUPP

NFS_ACL Version 3 Version 3 of the NFS_ACL protocol is used in conjunction only with version 3 of the NFS protocol.

Data types inherited from NFS version 3

Scalar Data types These are defined in .

ftype3 The enumeration "ftype3" represents the type of a file object. This definition is further explained in .

specdata3 The interpretation of the two words depends on the type of file system object. For a block special (NF3BLK) or character special (NF3CHR) file, specdata1 and specdata2 are the major and minor device numbers, respectively. For all other file types, these two elements should either be set to 0 or the values should be agreed upon by the client and server. Further detail is available in .

nfs_fh3 The nfs_fh3 data type is a variable-length opaque object returned by the NFS version 3 LOOKUP, CREATE, MKDIR, SYMLINK, MKNOD, or READDIRPLUS procedures. A client uses this handle during subsequent NFS operations to reference the file. This definition comes from . The maximum size in bytes of the opaque file handle. ; }; ]]> To the client, a file handle is opaque. The client stores file handles for use in a later request and can compare two file handles from the same server for equality by doing a byte-by-byte comparison, but cannot otherwise interpret the contents of file handles. Further, if two file handles from the same server are equal, they must refer to the same file, but if they are not equal, no conclusions can be drawn. Servers may revoke access provided by a file handle at any time. If the file handle passed in a call refers to a file system object that no longer exists on the server or access for that file handle has been revoked, the error, ACL3ERR_STALE, is returned.

nfstime3 NFS version 3's "nfstime3" structure represents the number of seconds and nanoseconds since midnight January 1, 1970 Greenwich Mean Time. Further details are in .

nfsfattr3 This document refers to NFS version 3's file attribute structure as "nfsfattr3". This is the same as the fattr3 structure described in . A definition of the bit fields in the "mode" element, which relate to traditional file system access permissions, can also be found there.

post_op_attr The NFS version 3 "post_op_attr" data type returns file attributes that are not directly involved in the requested procedure. See for more information. The format of this data type appears to make returning file attributes optional. However, server implementers are strongly encouraged to make a best effort to return attributes whenever possible, even when returning an error.

Error Values describes an enumerated type called "nfsstat3" which provides a status code for NFS version 3 procedure results. A matching type called "aclstat3" is defined in this document for the similar purpose of returning NFS_ACL version 3 procedure status codes. The numeric values of these two types match up, although aclstat3 omits some codes that are not relevant to the NFS_ACL protocol. These status codes carry the following meanings:

ACL3_OK

Indicates the call completed successfully.

ACL3ERR_PERM

Not owner. The operation was not allowed because the caller is either not a privileged user (root) or not the owner of the target of the operation.

ACL3ERR_NOENT

No such file or directory. The file or directory name specified does not exist.

ACL3ERR_IO

I/O error. A hard error (for example, a disk error) occurred while processing the requested operation.

ACL3ERR_ACCES

Permission denied. The caller does not have the correct permission to perform the requested operation. Contrast this with ACL3ERR_PERM, which restricts itself to owner or privileged user permission failures.

ACL3ERR_INVAL

An invalid or unsupported argument was specified for procedure.

ACL3ERR_NOSPC

No space left on device. The operation would have caused the server's file system to exceed its limit.

ACL3ERR_ROFS

Read-only file system. A modifying operation was attempted on a read-only file system.

ACL3ERR_DQUOT

Resource (quota) hard limit exceeded. The user's resource limit on the server has been exceeded.

ACL3ERR_STALE

Invalid file handle. The file handle given in the arguments was invalid. The file referred to by that file handle no longer exists or access to it has been revoked.

ACL3ERR_BADHANDLE

Illegal NFS file handle. The file handle failed internal consistency checks.

ACL3ERR_NOTSUPP

Operation is not supported.

ACL3ERR_SERVERFAULT

An error occurred on the server which does not map to any of the legal NFS version 3 protocol error values. The client should translate this into an appropriate error. UNIX clients may choose to translate this to EIO.

ACL3ERR_JUKEBOX

The server initiated the request, but was not able to complete it in a timely fashion. The client should wait and then try the request with a new RPC transaction ID. For example, this error should be returned from a server that supports hierarchical storage and receives a request to process a file that has been migrated. In this case, the server should start the immigration process and respond to client with this error.

Server Procedures The ERRORS subsection of each procedure enumerates the status values a server returns from that procedure.

Procedure 0: NULL - No Operation

ARGUMENTS

RESULTS

DESCRIPTION This is the usual NULL procedure with a void argument and void result.

IMPLEMENTATION It is important that this procedure do no work at all so that clients can use it to measure the overhead of processing a service request. By convention, the NULL procedure should never require any authentication. A server implementation may choose to ignore this convention, if responding to the NULL procedure call acknowledges the existence of a resource to an unauthenticated client.

ERRORS Since the NULL procedure takes no argument and returns no result, it can not return an NFS or NFS_ACL error status code. However, some server implementations may return RPC errors based on security or authentication policy settings.

Procedure 1: GETACL - Retrieve an Access Control List

ARGUMENTS

RESULTS

DESCRIPTION The GETACL procedure retrieves Access Control List information associated with the file system object specified by the GETACL3args.fh field. The client obtains this file handle using one of the NFS version 2 LOOKUP, CREATE, MKDIR, SYMLINK, MKNOD, or READDIRPLUS procedures, or the MOUNT service, as described in . The GETACL3args.mask field specifies which information is to be returned in the response:

• If the NA_ACL bit is set, the server fills in the object's access ACL.
• If the NA_ACLCNT bit is set, the server fills in the number of ACEs that are in the object's access ACL.
• If the NA_DFACL bit is set, the server fills in the object's default ACL.
• If the NA_DFACLCNT bit is set, the server fills in the number of ACEs that are in the object's default ACL.

The server fills in a count whenever either bit for that array is set, and fills in the array itself only when the array's own bit is set. An array the server does not fill in is empty on the wire. The reply's "mask" element carries the request's value (see ). If the GETACL procedure is successful, the server sets the GETACL3res.status field to ACL3_OK. It fills in the GETACL3resok.attr field with the file object's post operation file attributes, as detailed in . Lastly, it fills in the GETACL3resok.acl field with two counted arrays of Access Control Entries (ACEs). Otherwise, GETACL3res.status contains an error status on failure and no other results are returned.

IMPLEMENTATION When GETACL3args.fh represents a file object that does not currently have an ACL associated with it or does not implement support for ACLs, the server responds by returning a manufactured minimal NFS ACL that reflects the current owner, group, and mode bits of the object (see ). A default ACL applies only to a directory object. When GETACL3args.fh represents an object that is not a directory, that object has no default ACL. If the request's NA_DFACL or NA_DFACLCNT bit is set, the server returns an empty dfaclent array and a dfaclcnt of zero rather than reporting an error.

ERRORS

• ACL3ERR_IO
• ACL3ERR_ACCES
• ACL3ERR_INVAL
• ACL3ERR_STALE
• ACL3ERR_BADHANDLE
• ACL3ERR_SERVERFAULT
• ACL3ERR_JUKEBOX

Procedure 2: SETACL - Set or replace an Access Control List

ARGUMENTS

RESULTS

DESCRIPTION The SETACL procedure replaces the Access Control Lists associated with the file system object specified by the SETACL3args.fh field with the ACLs specified by the SETACL3args.acl field. The client obtains the file handle using one of the NFS version 3 LOOKUP, CREATE, MKDIR, MKNOD, SYMLINK, or READDIRPLUS procedures, or the MOUNT service, as described in . To remove extended access control from a file object, a client uses SETACL to replace the object's ACL with a minimal NFS ACL (see ). To remove a directory's default ACL, a client sends a SETACL with both the NA_ACL and NA_DFACL bits set, an empty "dfaclent" array, and the directory's current access ACL in "aclent" (see ). If the SETACL procedure is successful, the server sets the SETACL3res.status field to ACL3_OK and fills in the SETACL3resok.attr field with the file object's post operation file attributes, as detailed in . Otherwise, SETACL3res.status contains an error status on failure and no other results are returned.

IMPLEMENTATION A successful reply means that the exported file system has verified the new ACL, but does not mean that the change has reached stable storage. Changing a file object's ACL changes the object's ctime. The ctime change is reflected in the attributes returned in the SETACL response. A high-quality server implementation ensures that a GETACL procedure running concurrently with a SETACL procedure does not return partially updated (torn) ACL contents. However, a failed SETACL may partially change a file's ACLs. When SETACL3args.fh represents a file object that does not implement support for ACLs, the server responds by setting SETACL3res.status to ACL3ERR_NOTSUPP. When SETACL3args.acl does not contain at least the minimal set of ACEs (as described in ), the server responds by setting SETACL3res.status to ACL3ERR_INVAL. Servers differ in how they treat the "mask" element of SETACL3args.acl. describes the divergence and how a client avoids it.

ERRORS

• ACL3ERR_PERM
• ACL3ERR_IO
• ACL3ERR_ACCES
• ACL3ERR_INVAL
• ACL3ERR_NOSPC
• ACL3ERR_ROFS
• ACL3ERR_DQUOT
• ACL3ERR_STALE
• ACL3ERR_BADHANDLE
• ACL3ERR_NOTSUPP
• ACL3ERR_SERVERFAULT
• ACL3ERR_JUKEBOX

Procedure 3: GETXATTRDIR - Get named attribute directory

ARGUMENTS

RESULTS

DESCRIPTION defines a set of generic file attributes known as "named attributes". The GETXATTRDIR procedure extends this facility into the NFSv3 protocol. The GETXATTRDIR procedure obtains the file handle of the named attribute directory associated with the file handle in the GETXATTRDIR3args.fh field. This directory contains only objects of type NF3REG. If the GETXATTRDIR procedure is successful, the server sets the GETXATTRDIR3res.status field to ACL3_OK. It fills in the GETXATTRDIR3resok.fh field with a file handle that the client may use to look up the target file's named attributes. It fills in the GETXATTRDIR3resok.attr field with the named attribute directory's current file attributes, as detailed in . Using the file handle returned in GETXATTRDIR3resok.fh, a client can utilize the READDIR and LOOKUP procedures to obtain file handles for the named attributes associated with the target file system object. If the target file object does not currently have a named attribute directory associated with it and the GETXATTRDIR3args.create boolean field is set to false, the server returns ACL3ERR_NOENT. If the target file object does not currently have a named attribute directory associated with it and the GETXATTRDIR3args.create boolean field is set to true, the server attempts to create the named attribute directory before returning a result. If the target file currently has a named attribute directory associated with it and the GETXATTRDIR3args.create boolean is set to true, the server returns the file handle of that named attribute directory. If the RPC user does not have read access to the target file, or if the GETXATTRDIR operation is to create a named attribute directory and the RPC user does not have permission to do so, the server returns ACL3ERR_ACCES in the GETXATTRDIR3res.status field. If the target file handle designates an object not of type NF3REG or NF3DIR, the server returns the value ACL3ERR_INVAL in the GETXATTRDIR3res.status field. Neither named attributes nor named attribute directories have their own named attributes. Note: This operation is equivalent to the NFSv4 OPENATTR operation as specified in and .

IMPLEMENTATION Server implementers are free to choose not to implement this procedure. In this case, the server returns the RPC-level error PROC_UNAVAIL. If the server implementation does implement the GETXATTRDIR procedure but the shared file system containing the file object specified by the file handle in the GETXATTRDIR3args.fh field does not support named attributes, the server returns ACL3ERR_NOTSUPP in the GETXATTRDIR3res.status field.

ERRORS

• ACL3ERR_PERM
• ACL3ERR_NOENT
• ACL3ERR_IO
• ACL3ERR_ACCES
• ACL3ERR_INVAL
• ACL3ERR_NOSPC
• ACL3ERR_ROFS
• ACL3ERR_STALE
• ACL3ERR_BADHANDLE
• ACL3ERR_NOTSUPP
• ACL3ERR_SERVERFAULT
• ACL3ERR_JUKEBOX

Implementation Issues

Permission issues The NFS protocol, strictly speaking, does not define the permission checking used by NFS servers. However, it is expected that an NFS server will do normal operating system permission checking using AUTH_SYS style authentication as the basis of its protection mechanism, or another stronger form of authentication such as RPCSEC_GSS. With AUTH_SYS authentication, the server gets the client's effective uid, effective gid, and groups on each call and uses them to check permission. These are the so-called UNIX credentials. Using uid and gid implies that the client and server share the same uid list. Every server and client pair must have the same mapping from user to uid and from group to gid. Since every client can also be a server, this tends to imply that the whole network shares the same uid/gid space. If this is not the case, then it usually falls upon the server to perform some custom mapping of credentials from one authentication domain into another. A discussion of techniques for managing a shared user space or for providing mechanisms for user ID mapping is beyond the scope of this specification. In POSIX-based operating systems, a particular user (on UNIX, the uid 0) has access to all files, no matter what permission and ownership they have. This superuser permission may not be allowed on the server, since anyone who can become superuser on their client could gain access to all remote files. A POSIX-based NFS server by default maps uid 0 to a distinguished value (for instance, UID_NOBODY), as well as mapping the groups list, before doing its access checking. A server implementation may provide a mechanism to change this mapping.

Duplicate Request Cache The typical NFS protocol failure recovery model uses client time-out and retry to handle server crashes, network partitions, and lost server replies. A retried request is referred to as a duplicate of the original. When used in a file server context, the term idempotent can be used to distinguish between operation types. An idempotent request is one that a server can perform more than once with equivalent results (though it may in fact change, as a side effect, the access time on a file, say for READ). Some NFS operations are obviously non-idempotent. They cannot be reprocessed without special attention simply because they may fail if tried a second time. A CREATE request, for example, can be used to create a file for which the owner does not have write permission. A duplicate of this request cannot succeed if the original succeeded. Likewise, a file can be removed only once. The side effects caused by performing a duplicate non-idempotent request can be destructive. A duplicate file truncation can result in lost writes. It is the inherent stateless design of the NFS protocol on top of an unreliable RPC transport that yields the possibility of destructive replays of non-idempotent requests. Even in an implementation of the NFS protocol over a reliable connection-oriented transport, a connection break with automatic reestablishment requires duplicate request processing: the client retransmits requests that were pending before the connection loss, and the server needs to recognize and deal with potential duplicate non-idempotent requests. Most NFS server implementations maintain a cache of recent requests, called the duplicate request cache, for recognizing duplicate non-idempotent requests. If the server receives a request and recognizes it as a duplicate of a recently completed request, the server returns the original completion status instead of processing the duplicate request again. A description of an early implementation of a duplicate request cache can be found in . A retransmitted SETACL that a server processes after a later SETACL on the same object reinstates the older ACL. A duplicate request cache narrows that window but does not close it: the cache is finite, and an entry can age out before the retransmission arrives (see ). A client therefore cannot depend on whether a server caches SETACL replies.

Caching Policies The NFS protocol does not define a policy for caching on the client or server. In particular, there is no support for strict cache consistency between a client and server, nor between different clients. The NFS_ACL protocol does not mandate a specific caching policy for ACLs or information retrieved via the ACCESS procedure. However, a high-quality client implementation that seeks good performance might choose to revalidate cached access control information with the same regularity that it invalidates normal file attributes.

XDR Protocol Definition This section contains a description of the core features of the NFS_ACL protocol, version 2 and version 3, expressed in the XDR language . NFS_ACL version 2 and NFS_ACL version 3 are independent versions of a single RPC program. Their XDR definitions are given here as two separate specifications, one in and one in , and each version is intended to form its own XDR file. Presenting the two versions as separate files lets an implementer extract and compile only the protocol version of interest. The code component license and the data types common to both versions appear once, in . Prepending those common definitions to the definitions of a single version yields a complete, independently compilable XDR file for that version: nfs_acl2.x for version 2, and nfs_acl3.x for version 3. This description is provided in a way that makes it simple to extract into ready-to-compile form. In the sections that follow, each line of XDR text is preceded by the marker "///". A line of the form "/// @@FILE name" marks the start of the version-specific definitions belonging to the file "name"; the XDR text preceding the first such marker, in , is common to both files. The reader can apply the following shell script to this document to extract the two XDR files. f } ' ]]> That is, if the above script is stored in a file called "extract.sh" and this document is in a file called "spec.txt", then writes two files into the current directory: nfs_acl2.x, containing the common definitions followed by the NFS_ACL version 2 definitions of , and nfs_acl3.x, containing the common definitions followed by the NFS_ACL version 3 definitions of . Each file is a complete and independently compilable XDR description of one protocol version.

Code Component License Code components extracted from this document must include the following license text. When the extracted XDR code is combined with other complementary XDR code which itself has an identical license, only a single copy of the license text need be preserved. ; /// int dfaclcnt; /// aclent dfaclent; /// }; /// /// /* /// * The values for the mask element of the secattr struct as well /// * as for the mask element in the arguments in the GETACL2 and /// * GETACL3 procedures. /// */ /// const NA_ACL = 0x1; /* aclent contains a valid list */ /// const NA_ACLCNT = 0x2; /* number of entries in the */ /// /* aclent list */ /// const NA_DFACL = 0x4; /* dfaclent contains a valid list */ /// const NA_DFACLCNT = 0x8; /* number of entries in the */ /// /* dfaclent list */ /// /// /* /// * Share the ports with the NFS service. /// */ /// const NFS_ACL_PORT = 2049; /// const NFS_ACL_RDMA_PORT = 20049; ]]>

NFS_ACL Version 2 The following definitions, together with the common definitions in , form the file nfs_acl2.x.

NFS_ACL Version 3 The following definitions, together with the common definitions in , form the file nfs_acl3.x. ; /// }; /// /// struct nfstime3 { /// uint32 seconds; /// uint32 nseconds; /// }; /// /// struct fattr3 { /// ftype3 type; /// mode3 mode; /// uint32 nlink; /// uid3 uid; /// gid3 gid; /// size3 size; /// size3 used; /// specdata3 rdev; /// uint64 fsid; /// fileid3 fileid; /// nfstime3 atime; /// nfstime3 mtime; /// nfstime3 ctime; /// }; /// /// union post_op_attr switch (bool attributes_follow) { /// case TRUE: /// fattr3 attributes; /// case FALSE: /// void; /// }; /// /// /* /// * ACL error codes; the numeric values match codes with the same /// * name used in NFS version 3. /// */ /// enum aclstat3 { /// ACL3_OK = 0, /// ACL3ERR_PERM = 1, /// ACL3ERR_NOENT = 2, /// ACL3ERR_IO = 5, /// ACL3ERR_ACCES = 13, /// ACL3ERR_INVAL = 22, /// ACL3ERR_NOSPC = 28, /// ACL3ERR_ROFS = 30, /// ACL3ERR_DQUOT = 69, /// ACL3ERR_STALE = 70, /// ACL3ERR_BADHANDLE = 10001, /// ACL3ERR_NOTSUPP = 10004, /// ACL3ERR_SERVERFAULT = 10006, /// ACL3ERR_JUKEBOX = 10008 /// }; /// /// /* /// * NFS_ACL version 3 procedure arguments and results /// */ /// /// struct GETACL3args { /// nfs_fh3 fh; /// unsigned int mask; /// }; /// /// struct GETACL3resok { /// post_op_attr attr; /// secattr acl; /// }; /// /// struct GETACL3resfail { /// post_op_attr attr; /// }; /// /// union GETACL3res switch (aclstat3 status) { /// case ACL3_OK: /// GETACL3resok resok; /// default: /// GETACL3resfail resfail; /// }; /// /// struct SETACL3args { /// nfs_fh3 fh; /// secattr acl; /// }; /// /// struct SETACL3resok { /// post_op_attr attr; /// }; /// /// struct SETACL3resfail { /// post_op_attr attr; /// }; /// /// union SETACL3res switch (aclstat3 status) { /// case ACL3_OK: /// SETACL3resok resok; /// default: /// SETACL3resfail resfail; /// }; /// /// /* /// * This is the definition for the GETXATTRDIR procedure which /// * applies to NFS Version 3 files. /// */ /// struct GETXATTRDIR3args { /// nfs_fh3 fh; /// bool create; /// }; /// /// struct GETXATTRDIR3resok { /// nfs_fh3 fh; /// post_op_attr attr; /// }; /// /// union GETXATTRDIR3res switch (aclstat3 status) { /// case ACL3_OK: /// GETXATTRDIR3resok resok; /// default: /// void; /// }; /// /// program NFS_ACL_PROGRAM { /// version NFS_ACL_V3 { /// void /// ACLPROC3_NULL(void) = 0; /// GETACL3res /// ACLPROC3_GETACL(GETACL3args) = 1; /// SETACL3res /// ACLPROC3_SETACL(SETACL3args) = 2; /// GETXATTRDIR3res /// ACLPROC3_GETXATTRDIR(GETXATTRDIR3args) = 3; /// } = 3; /// } = 100227; ]]>

Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist.

Solaris NFS server and client Organization: Oracle URL: https://www.oracle.com Maturity: Complete. Coverage: All procedures are implemented. Licensing: CDDL Implementation experience: The Solaris implementation is the origin of the nfs_acl.x file from which this document is derived . Its server does not consult the "mask" element of a SETACL request, and what it stores and returns depends on the exported file system: UFS stores exactly the entries a SETACL carries, while ZFS rejects SETACL with ACL2ERR_NOTSUPP or ACL3ERR_NOTSUPP and answers GETACL with a manufactured ACL (see and ).

Linux NFS server and client Organization: The Linux Foundation URL: https://www.kernel.org Maturity: Complete. Coverage: The Linux NFS server implements all procedures except GETXATTRDIR in both versions of the protocol. The Linux NFS client implements the NFS_ACL protocol only for version 3; it does not implement NFS_ACL version 2. Licensing: GPLv2 Implementation experience: The initial Linux implementation of the NFS_ACL protocol is described in , and subsequent modifications can be found in the Linux kernel source code repository . notes several minor differences between the Linux and Solaris implementations of ACLs. The one visible on the wire, the treatment of the mask entry in a four-entry ACL, is described in . The Linux NFS_ACL implementation already builds the version 2 and version 3 protocols from two separate source files, presently maintained by hand. Work is underway to generate those files from the separate XDR descriptions in and instead.

Security Considerations NFS_ACL was designed for a single administrative domain on a physically protected network. This section considers a broader environment: deployment across the global Internet, spanning administrative boundaries, with no firewall assumed between a client and its server. NFS_ACL carries no security mechanism of its own. It inherits what the RPC layer provides, and it names the users and groups in an Access Control Entry using the identities that layer supplies (see ). What follows therefore turns on the choice of RPC authentication flavor and transport. Attacks on the NFS version 2 and version 3 protocols themselves are out of scope. An attacker who can read or alter file content directly through NFS gains nothing by attacking the ACL that governs it, and covers those protocols. Attacks on the local file system that stores an ACL, and on the mechanism by which a site maps users to uid and gid values, are out of scope as well: both are shared with the NFS service that NFS_ACL accompanies, and neither is reachable through the NFS_ACL protocol itself.

Attacks on an Unprotected Exchange Running NFS_ACL over AUTH_SYS on an unprotected transport defends against none of the following.

Eavesdropping:

A GETACL reply carries an object's full Access Control List. An observer learns which users and groups hold access to the object, and the uid and gid values that name them. The list is worth reading even when the file content is not.

Modification and man-in-the-middle:

Altering a SETACL argument changes the access control the server installs. Altering a GETACL reply gives the client a false view of it. Altering an ACCESS reply misleads a client that uses the result to decide whether to attempt an operation.

Message insertion:

AUTH_SYS supplies no verifier by which a credential can be validated (). An attacker who can reach the server and holds a file handle for an object can forge a SETACL request bearing the file owner's uid.

Replay:

SETACL is not idempotent. A replayed SETACL reinstates an ACL that the file owner has since replaced. The duplicate request cache () recognizes a retransmission, but it is finite: a replay delayed beyond its reach is processed as a new request.

Message deletion and denial of service:

Discarding NFS_ACL messages denies a client the ability to read or change an ACL. An attacker positioned to do this can discard the NFS traffic alongside it, so NFS_ACL neither adds to nor reduces the exposure.

states that AUTH_SYS should not be used for services that permit clients to modify data. SETACL modifies the data that governs every other access to the object. reports that implementations permit any authentication flavor on procedures other than NULL. That records what implementations accept; it does not recommend AUTH_SYS for SETACL. states what a deployment should do instead.

Protecting an Exchange Two mechanisms available to an NFS version 2 or version 3 deployment apply unchanged to NFS_ACL, which shares the transport and port of the NFS service it accompanies. RPCSEC_GSS replaces AUTH_SYS with a GSS-API mechanism. Its integrity service authenticates the RPC peer and detects alteration of each call and reply, addressing insertion, modification, and man-in-the-middle. Per-request sequence numbers detect replay within a window the server sizes. Integrity leaves ACL content readable on the wire; the privacy service encrypts arguments and results and closes that gap. describes how the NFS version 2 and version 3 protocols use RPCSEC_GSS and Kerberos V5. RPC-over-TLS protects the transport connection rather than the individual RPC message. It supplies confidentiality and integrity for everything on the connection and can authenticate the peer host. It does not authenticate the RPC user, so a server relying on it alone still takes on trust the uid and gid each request carries. A deployment that exposes NFS_ACL beyond a physically protected network should protect the exchange with a mechanism that detects alteration of each call and reply and that authenticates the source of each request, so that neither the uid and gid a request carries nor the ACL entries in its arguments and results can be altered by a man-in-the-middle, and so that a forged credential is detected.

Residual Risk Neither mechanism changes what an authenticated caller may do. GETACL carries no permission check of its own (see ), so a caller holding a file handle can often read the object's ACL and the user and group IDs it names. A deployment that treats ACL membership as sensitive cannot rely on the protocol to withhold it. A server that maps a privileged caller to a less privileged identity (see ) decides on the strength of the uid the request carries. Under AUTH_SYS the client supplies that value, so the mapping deters accident rather than attack. The "id" element of an Access Control Entry is a uid or gid in the server's numeric space. RPCSEC_GSS maps the caller's principal to a local identity (see ), but no authentication flavor translates the identities an ACL names. Across an administrative boundary, a client that writes an ACL names users and groups by numbers it cannot confirm are the server's, and a client that reads one cannot resolve the numbers it receives. An ACL a client has read, and the result of an ACCESS procedure, describe the server's decision at the moment it was made. The server alone authorizes access (see ) and can revoke it at any time. A client that caches either and relies on it later may be relying on information that no longer holds.

IANA Considerations In accordance with , the editor requests that IANA update the entry for the NFS ACL service in the RPC Program Numbers registry to add the current document as a Reference.

References Normative References This document describes the External Data Representation Standard (XDR) protocol as it is currently deployed and accepted. This document obsoletes RFC 1832. [STANDARDS-TRACK] This document describes the Open Network Computing (ONC) Remote Procedure Call (RPC) version 2 protocol as it is currently deployed and accepted. This document obsoletes RFC 1831. [STANDARDS-TRACK] Informative References This RFC describes a protocol that Sun Microsystems, Inc., and others are using. A new version of the protocol is under development, but others may benefit from the descriptions of the current protocol, and discussion of some of the design issues. This paper describes the NFS version 3 protocol. This paper is provided so that people can write compatible implementations. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. This memo describes an ONC/RPC security flavor that allows RPC protocols to access the Generic Security Services Application Programming Interface (referred to henceforth as GSS-API). [STANDARDS-TRACK] This memorandum clarifies various security issues involving the NFS protocol (Version 2 and Version 3 only) and then describes how the Version 2 and Version 3 of the NFS protocol use the RPCSEC_GSS security flavor protocol and Kerberos V5. [STANDARDS-TRACK] The Network File System (NFS) version 4 protocol is a distributed file system protocol that builds on the heritage of NFS protocol version 2 (RFC 1094) and version 3 (RFC 1813). Unlike earlier versions, the NFS version 4 protocol supports traditional file access while integrating support for file locking and the MOUNT protocol. In addition, support for strong security (and its negotiation), COMPOUND operations, client caching, and internationalization has been added. Of course, attention has been applied to making NFS version 4 operate well in an Internet environment. This document, together with the companion External Data Representation (XDR) description document, RFC 7531, obsoletes RFC 3530 as the definition of the NFS version 4 protocol. This document specifies version 3 of the Remote Procedure Call (RPC) security protocol (RPCSEC_GSS). This protocol provides support for multi-principal authentication of client hosts and user principals to a server (constructed by generic composition), security label assertions for multi-level security and type enforcement, structured privilege assertions, and channel bindings. This document updates RFC 5403. This document describes the Network File System (NFS) version 4 minor version 1, including features retained from the base protocol (NFS version 4 minor version 0, which is specified in RFC 7530) and protocol extensions made subsequently. The later minor version has no dependencies on NFS version 4 minor version 0, and is considered a separate protocol. This document obsoletes RFC 5661. It substantially revises the treatment of features relating to multi-server namespace, superseding the description of those features appearing in RFC 5661. This document describes a mechanism that, through the use of opportunistic Transport Layer Security (TLS), enables encryption of Remote Procedure Call (RPC) transactions while they are in transit. The proposed mechanism interoperates with Open Network Computing (ONC) RPC implementations that do not support it. This document updates RFC 5531. SuSE Labs Digital Equipment Corporation Institute of Electrical and Electronics Engineers Institute of Electrical and Electronics Engineers n.d. FreeBSD Project This document proposes four new optional file attributes for NFSv4.2 to support POSIX ACLs conforming to the withdrawn POSIX 1003.1e draft 17. Although never ratified, POSIX ACLs are implemented in widely deployed operating systems. Existing attempts to map between NFSv4 and POSIX ACL models have been unsuccessful due to semantic incompatibilities. These new attributes allow servers to expose POSIX ACLs directly, avoiding lossy mapping. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document specifies a protocol for conveying Remote Procedure Call (RPC) messages on physical transports capable of Remote Direct Memory Access (RDMA). This protocol is referred to as the RPC-over- RDMA version 1 protocol in this document. It requires no revision to application RPC protocols or the RPC protocol itself. This document obsoletes RFC 5666. This document specifies Upper-Layer Bindings of Network File System (NFS) protocol versions to RPC-over-RDMA version 1, thus enabling the use of Direct Data Placement. This document obsoletes RFC 5667. This document describes the binding protocols used in conjunction with the ONC Remote Procedure Call (ONC RPC Version 2) protocols. [STANDARDS-TRACK] This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice.

Source Material The on-the-wire protocol described here is intended to match existing de facto implementations of NFS_ACL. The source for the XDR specification provided in this document is the nfs_acl.x file as found in published versions of the OpenSolaris source code base , an open source descendant of Solaris. However, there are a few changes to the protocol as it was originally described in the OpenSolaris source code base.

Redaction of NFS_ACL Version 4 Version 4 of NFS_ACL is described in the original nfs_acl.x source file this way:

• This is a transitional interface to enable Solaris NFSv4 clients to manipulate ACLs on Solaris servers until the spec is complete enough to implement this inside the NFSv4 protocol itself. NFSv4 does handle extended attributes in-band.

Because the two non-NULL procedures in this version of the NFS_ACL protocol were used only as part of a Solaris prototype and there are no other implementations of NFS_ACL version 4, it is not included in the protocol description appearing in this document.

Extension of NFS_ACL Extension of this legacy protocol is out of scope for an Informational document whose purpose is to describe existing implementations.

Code Compilation Requirements The original nfs_acl.x file that appears in the OpenSolaris code base did not compile using the widely-available rpcgen tool.

• The file does not include a definition of the ACL2_OK or ACL3_OK constants used in definitions of result unions.
• The file does not include definitions of NFS protocol elements that are shared with the NFS_ACL protocol, such as fhandle and post_op_attr.

The XDR specification provided in this document rectifies those omissions to provide a complete and compilable XDR language description of the NFS_ACL protocol.

Acknowledgments The editor is grateful to Bill Baker, Frank Batschulat, Wim Coekaerts, Andreas Gruenbacher, Rick Macklem, Greg Marsden, Martin Thomson, Rob Thurlow, and Jim Wright for their input and support. Special thanks to Area Director Gorry Fairhurst, NFSV4 Working Group Chair Brian Pawlowski, and NFSV4 Working Group Secretary Thomas Haynes for their patience, guidance, and oversight.