Access Permissions Category

The functions in the Access Permissions category examine or modify user or group access permission records for resources on servers.

Function	Description
NetAccessCloseBuffer	Closes the self-relative access control information buffer.
NetAccessDel	Deletes all access control records for a specified resource.
NetAccessFillBuffer	Adds the new entry to the self-relative buffer which later will be used in the NetAccessSetInfoAny call.
NetAccessGetInfo	Retrieves LAN Manager-style information about the access permission record of a specified server resource.
NetAccessGetInfoAny	Retrieves access control information for a specified resource.
NetAccessInitBuffer	Initializes the self-relative buffer which will be used for storage of the ACCESS_INFO_2 structure.
NetAccessSetInfo	Modifies the access permission record for a specified server resource, LAN Manager-style.
NetAccessSetInfoAny	Changes the access control information for a specified resource.

An access control list (ACL) contains the name of a resource, an audit attribute field, and a list of access control entries. An access control entry (ACE) is a user name or group name and its corresponding access permissions.

If a user requires access to a resource, an access permission record must be defined for that user. An access permission record defines how a user or group can access a resource. It contains a set of access permissions for each user or group.

Advanced Server maintains security descriptors on all shared resources. These security descriptors are more sophisticated and powerful than LAN Manager-style access controls. Advanced Server performs the best possible translation to and from LAN Manager-style data structures to security descriptors.

However, a LAN Manager-style structure cannot represent all the information that can be in an Advanced Server security descriptor. For example, Advanced Server can assign access rights to users in other domains; in a LAN Manager environment, the LAN Manager system structures provide no mechanism to identify users in other domains.

An access permission record contains the following information:

the name of the resource

the owner of the resource

a list of users and/or groups permitted to use the resource and access permissions assigned to them

a list of users and/or groups whose access to the resource is audited and auditing settings specified for them

NetAccessGetInfoAny and NetAccessSetInfoAny can be used to retrieve and change information about the resource (except for the resource name).

NetAccessGetInfo and NetAccessSetInfo are being maintained only for LAN Manager compatibility. They can handle only the retrieving and setting of LAN Manager-style access permissions . This includes reporting and assigning ACCESS_CREATE and ACCESS_ATTRIB permissions which no longer are meaningful to Advanced Server, and the inability to handle ACCESS_OWNER permission. Auditing information is reported by these functions cumulatively, without differentiating between separate users and groups. These functions also are unable to handle users in other domains.

NetAccessInitBuffer, NetAccessFillBuffer and NetAccessCloseBuffer are the utility functions for setting the access control information into a self-relative buffer which is then passed as a parameter to NetAccessSetInfoAny.

NetAccessDel deletes the resource’s ACL. Note that deleting the resource’s ACL is not equivalent to denying to everyone access to the resource; in many cases, the resource without its own ACL will inherit the access control information from an ACL of a parent resource.

Note

It generally is recommended to use NetAccessGetInfoAny and NetAccessSetInfoAny for reporting and modifying access permissions on Advanced Server and Windows NT Server computers, and to issue NetAccessGetInfo and NetAccessSetInfo calls only to LAN Manager servers.

Access Permissions Data Structures

The sLevel parameter controls the level of information provided to or returned from the NetAccessGetInfo, NetAccessSetInfo, NetAccessGetInfoAny, and NetAccessSetInfoAny functions.

NetAccessGetInfo and NetAccessSetInfo use either level 0 or level 1 data structure. NetAccessGetInfoAny and NetAccessSetInfoAny use the level 2 data structure.

Access Permissions Information (level 0)

The access_info_0 data structure has the following format:

struct access_info_0 {

char * acc0_resource_name;

};

Within this structure, acc0_resource_name points to an ASCIIZ string containing the name of a resource type. acc0_resource_name uses the following formats:

Resource Type	Name Format	Comment
Drive	drive:	No path is specified; the drive must exist.
Path	\pathname	No drive is specified; the path need not exist.
Directory	drive:\pathname	The path must exist.
File	drive:\pathname	The file must exist.
UNC	\\server\sharename\pathname	The path must exist.
Pipe	\pipe\pipename
Printer queue	\print\queuename
Share	\sharename - or - \\server\sharename

Access Permissions Information (level 1)

The access_info_1 data structure has the following format:

struct access_info_1 {

char * acc1_resource_name;

short accl_attr;

short accl_count;

};

Within this structure, the parameters are defined as follows:

acc1_resource_name points to an ASCIIZ string specifying the name of a particular resource. (For more information, see acc0_resource_name.)

acc1_attr specifies the attributes of acc1_resource_name.

The bits of acc1_attr are defined as follows:

Bit	Files	Meaning
0	Audit all. When this bit is set, all access attempts are audited. No other bits in the field can be set at the same time.	Same
1-2	Reserved; must be 0.	Reserved; must be 0.
3	Ignored	Reserved
4	Successful opens	Reserved
5	Successful writes.	Successful creates
6	Successful deletes/truncates	Successful deletes
7	Successful ACL changes	Same
8	Failed opens	Reserved
9	Failed writes	Failed creates
10	Failed deletes/truncates	Failed deletes
11	Failed ACL changes	Same
12-15	Reserved; must be 0.	Reserved; must be 0.

Other resources that can be accessed over the network, including printer queues and pipes, are audited the same way as files.

When write auditing is enabled, the write audit record is generated the first time the record is opened with write permission.

File size changes (including truncation) are audited under the control of the write audit bits, 5 and 9.

acc1_count specifies the number of access_list data structures following the access_info_1 data structure.

In addition, the access_info_1 data structure can be followed by zero or more (up to a maximum of 64) access_list data structures. These structures are used to define resource permissions for individual users or groups.

Access Permissions Information (level 2)

The access_info_1 data structure has the following format:

typedef struct_ACCESS_INFO_2 {

LPTSTR acc2_resource_name;

LPTSTR acc2_owner;

DWORD acc2_access_count;

DWORD acc2_audit_count;

DWORD acc2_resource_type;

} ACCESS_INFO_2, *PACCESS_INFO_2, *LPACCESS_INFO_2;

Within this structure, the parameters are defined as follows:

acc2_resource_name points to an ASCIIZ string specifying the name of a particular resource. (For information, see acc0_resource_name).

acc2_owner points to an ASCIIZ string specifying the owner of acc2_resource_name.

acc2_access_count specifies the number of ACCESS_LIST_2 data structures with access permissions information following ACCESS_INFO_2 structure.

acc2_audit_count specifies the number of ACCESS_LIST_2 data structures with auditing information following ACCESS_INFO_2 structure.

acc2_resource_type describes the type of the resource for which permissions are specified. Possible values as defined in the unixapi.h file are as follows:

Manifest	Value
RESOURCE_TYPE_FILE	1
RESOURCE_TYPE_SHARE	2
RESOURCE_TYPE_PRINTQ	3
RESOURCE_TYPE_DIRECTORY	4

In addition, the ACCESS_INFO_2 data structure can be followed by zero or more ACCESS_LIST_2 data structures. These structures are used to define resource permissions and auditing settings for individual users or groups.

Resource Permissions (LAN Manager-Style)

The access_list data structure has the following format:

struct access_list {

char acl_ugname[LM20 UNLEN+1];

char acl_ugname_pad_1;

short acl_access;

};

Within this structure, the parameters are defined as follows:

acl_ugname is an ASCIIZ string specifying a user name or group name.

acl_ugname_pad_1 word-aligns the data structure components.

acl_access specifies the user name’s or group name’s permissions.

acl_access is defined in the access.h file as follows:

Manifest	Bit Mask	Meaning
ACCESS_READ	0x01	Permission to read data from a resource, and by default execute the resource.
ACCESS_WRITE	0x02	Permission to write data to the resource.
ACCESS_CREATE	0x04	Permission to create an instance of the resource; data may be written to it.
ACCESS_EXEC	0x08	Permission to execute resource.
ACCESS_DELETE	0x10	Permission to delete resource.
ACCESS_ATRIB	0x20	Permission to modify the resource’s attributes (such as the date and time).
ACCESS_PERM	0x40	Permission to modify assigned permissions (read, write, create, execute, and delete).
ACCESS_ALL	0x7F	Permission to read, write, create, execute, or delete a resource, or to modify attributes or permissions.
ACCESS_GROUP	0x8000	Permission for a group; if returned, entry is for a group.

Resource Permissions and Auditing Settings

The ACCESS_LIST_2 data structure has the following format:

typedef struct _ACCESS_LIST_2 {

LPTSTR acl2_ugname;

DWORD acl2_mask;

DWORD acl2_flags;

} ACCESS_LIST_2, *PACCESS_LIST_2, *LPACCESS_LIST_2;

Within this structure, the parameters are defined as follows:

acl2_ugname points to an ASCIIZ string specifying a user name or group name.

acl2_mask contains resource permissions mask or auditing mask.

Acl2_flags contains inheritance flags for the access list entry that are specified in the lmsec.h file.

Resource permissions mask is defined in the access.h and unixapi.h files as follows:

Manifest	Bit Mask	Meaning
ACCESS_READ	0x01	Permission to read data from a resource.
ACCESS_WRITE	0x02	Permission to write data to the resource.
ACCESS_EXEC	0x08	Permission to execute the resource.
ACCESS_DELETE	0x10	Permission to delete the resource.
ACCESS_PERM	0x40	Permission to modify the permissions assigned to a resource.
ACCESS_OWNER	0x80	Permission to change the owner of the resource.
ACCESS_FULL	0xDB	Permission to read, write, execute or delete a resource, or to modify the resource’s owner or permissions.
ACCESS_GROUP	0x8000	Permission for a particular group; if returned, the entry is for the group.

Auditing mask is defined in the unixapi.h file as follows:

Manifest	Bit Mask	Meaning
AU_S_READ	0x01	Audit successful read access to the resource.
AU_F_READ	0x100	Audit failed reads for the resource.
AU_S_WRITE	0x02	Audit successful writes for the resource.
AU_F_WRITE	0x0200	Audit failed writes for the resource.
AU_S_EXEC	0x08	Audit successful executes for the resource.
AU_F_EXEC	0x0800	Audit failed executes for the resource.
AU_S_DELETE	0x10	Audit successful deletes for the resource.
AU_F_DELETE	0x1000	Audit failed deletes for the resource.
AU_S_PERM	0x40	Audit successful permissions changes for the resource.
AU_F_PERM	0x4000	Audit failed permissions changes for the resource.
AU_S_OWNER	0x80	Audit successful changes to the ownership of the resource.
AU_F_OWNER	0x8000	Audit failed changes to the ownership of the resource.