Name

NFSPROC3_ACCESS - Check Access Permission

Call Arguments

 

const ACCESS3_READ    = 0x0001;
const ACCESS3_LOOKUP  = 0x0002;
const ACCESS3_MODIFY  = 0x0004;
const ACCESS3_EXTEND  = 0x0008;
const ACCESS3_DELETE  = 0x0010;
const ACCESS3_EXECUTE = 0x0020;

struct ACCESS3args {
    nfs_fh3 object;
    uint32 access;
};

Return Arguments

 

struct ACCESS3resok {
    post_op_attr obj_attributes;
    uint32 access;
};

struct ACCESS3resfail {
    post_op_attr obj_attributes;
};

union ACCESS3res switch (nfsstat3 status) {
    case NFS3_OK:
        ACCESS3resok resok;
    default:
        ACCESS3resfail resfail;
};

RPC Procedure Description

 

ACCESS3res
NFSPROC3_ACCESS(ACCESS3args) = 4;

Description

Procedure ACCESS determines the access rights that a user, as identified by the credentials in the request, has with respect to a file system object. The client encodes the set of permissions that are to be checked in a bit mask. The server checks the permissions encoded in the bit mask. A status of NFS3_OK is returned along with a bit mask encoded with the permissions that the client is allowed.

The results of this procedure are necessarily advisory in nature. That is, a return status of NFS3_OK and the appropriate bit set in the bit mask does not imply that such access will be allowed to the file system object in the future, because access rights can be revoked by the server at any time.

On entry, the arguments in ACCESS3args are:

object

The file handle for the file system object to which access is to be checked.

access

A bit mask of access permissions to check. The following access permissions may be requested:

ACCESS3_READ

Read data from file or read a directory.

ACCESS3_LOOKUP

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

ACCESS3_MODIFY

Rewrite existing file data or modify existing directory entries.

ACCESS3_EXTEND

Write new data or add directory entries.

ACCESS3_DELETE

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

ACCESS3_EXECUTE

Execute file (no meaning for a directory).

Upon successful return, ACCESS3res.status is NFS3_OK. The server should return a status of NFS3_OK if no errors occurred that prevented the server from making the required access checks. The results in ACCESS3res.resok are:

obj_attributes

The post-operation attributes of object.

access

A bit mask of access permissions indicating access rights for the authentication credentials provided with the request.

Otherwise, ACCESS3res.status contains the error on failure and ACCESS3res.resfail contains the following:

obj_attributes

The attributes of object, if access to attributes is permitted.

Implementation Guidance

In general, it is not sufficient for the client to attempt to deduce access permissions by inspecting the uid, gid and mode fields in the file attributes, since the server may perform user ID or group ID mapping or enforce additional access control restrictions. It is also possible that the NFS Version 3 protocol server may not be in the same ID space as the NFS Version 3 protocol client. In these cases (and perhaps others), the NFS Version 3 protocol client can not reliably perform an access check with only the current file attributes.

In the NFS Version 2 protocol, the only reliable way to determine whether an operation was allowed was to try it and see if it succeeded or failed. Using the ACCESS procedure in the NFS Version 3 protocol, the client can ask the server to indicate whether or not one or more classes of operations are permitted. The ACCESS operation is provided to allow clients to check before doing a series of operations. This is useful in operating systems (such as UNIX) where permission checking is done only when a file or directory is opened. This procedure is also invoked by the NFS client access procedure (called possibly through access()). The intent is to make the behaviour of opening a remote file more consistent with the behaviour of opening a local file.

The information returned by the server in response to an ACCESS call is not permanent. It was correct at the exact time that the server performed the checks, but not necessarily afterwards. The server can revoke access permission at any time.

The NFS Version 3 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. See the comments in Permission Issues for more information on this topic.

Many implementations do not directly support the ACCESS3_DELETE permission. Operating systems like the UNIX system will ignore the ACCESS3_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 ACCESS3_DELETE bit set to zero, indicating that the client does not have this permission.

Return Codes

NFS3ERR_IO

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

NFS3ERR_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.

NFS3ERR_BADHANDLE

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

NFS3ERR_SERVERFAULT

An error occurred on the server, which does not map to any of the valid NFS Version 3 protocol error values. The client should translate this into an appropriate error. Clients based on an XPG system may choose to translate this to EIO.