| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |


 

 

 

 

 

WINDOWS ACCESS CONTROLS: A SUPPLEMENTARY NOTE

 

 

 

 

 

This supplementary note provides information for structure, enumeration, macro and type used in program examples of the Windows Access Control 1, Windows Access Control 2 and Windows Access Control 3 tutorials. Struct, enum, macro and typedef are dumped in struct, enum, typedef etc. The information compiled for NT 5 (Windows 2000 and above).

 

The Page Index

 

Enumerations:

  1. ACCESS_MODE

  2. ACL_INFORMATION_CLASS

  3. WELL_KNOWN_SID_TYPE

  4. MULTIPLE_TRUSTEE_OPERATION

  5. TRUSTEE_FORM

  6. TRUSTEE_TYPE

  7. SE_OBJECT_TYPE

  8. TOKEN_TYPE

  9. TOKEN_INFORMATION_CLASS

  10. SECURITY_IMPERSONATION_LEVEL

 

Macros:

  1. ZeroMemory()

  2. TEXT

 

Types:

  1. SECURITY_INFORMATIO

  2. SECURITY_DESCRIPTOR_CONTROL

  3. ACE

 

Structures:

  1. SECURITY_ATTRIBUTES

  2. SID

  3. SECURITY_DESCRIPTOR

  4. OBJECTS_AND_NAME

  5. TRUSTEE

  6. OBJECTS_AND_SID

  7. EXPLICIT_ACCESS

  8. ACE_HEADER

  9. TOKEN_GROUPS_AND_PRIVILEGES

  10. TOKEN_PRIVILEGES

  11. TOKEN_ORIGIN

  12. TOKEN_SOURCE

  13. TOKEN_STATISTICS

  14. TOKEN_USER

  15. TOKEN_CONTROL

  16. TOKEN_DEFAULT_DACL

  17. TOKEN_GROUPS

  18. TOKEN_OWNER

  19. TOKEN_PRIMARY_GROUP

  20. ACL_REVISION_INFORMATION

  21. ACL_SIZE_INFORMATION

  22. LUID

  23. LUID_AND_ATTRIBUTES

  24. PRIVILEGE_SET

  25. SECURITY_ATTRIBUTES

  26. GENERIC_MAPPING

  27. SYSTEM_AUDIT_OBJECT_ACE

  28. SYSTEM_AUDIT_ACE

  29. ACE_HEADER

  30. ACL

 

 

 

 

 

 

 

 

 

Enumeration

 

ACCESS_MODE

 

Item

Description

Enumeration type

ACCESS_MODE.

Info

The ACCESS_MODE enumeration type contains values that indicate how the access rights in an EXPLICIT_ACCESS structure apply to the trustee.  Functions such as SetEntriesInAcl() and GetExplicitEntriesFromAcl() use these values to set or retrieve information in an access control entry (ACE).

Definition

typedef enum _ACCESS_MODE

{

  NOT_USED_ACCESS = 0,

  GRANT_ACCESS,

  SET_ACCESS,

  DENY_ACCESS,

  REVOKE_ACCESS,

  SET_AUDIT_SUCCESS,

  SET_AUDIT_FAILURE

} ACCESS_MODE;

Constants

NOT_USED_ACCESS - Value not used.

GRANT_ACCESS - An input flag that creates an ACCESS_ALLOWED_ACE structure.  The new ACE combines the specified rights with any existing allowed or denied rights of the trustee.

SET_ACCESS - Indicates an ACCESS_ALLOWED_ACE structure that allows the specified rights.  On input, this flag discards any existing access control information for the trustee.

DENY_ACCESS - Indicates an ACCESS_DENIED_ACE structure that denies the specified rights.  On input, this flag denies the specified rights in addition to any currently denied rights of the trustee.

REVOKE_ACCESS - An input flag that removes all existing ACCESS_ALLOWED_ACE or SYSTEM_AUDIT_ACE structures for the specified trustee.

SET_AUDIT_SUCCESS - Indicates a SYSTEM_AUDIT_ACE structure that generates audit messages for successful attempts to use the specified access rights. You can combine this value with the SET_AUDIT_FAILURE member.  On input, this flag combines the specified rights with any existing audited access rights for the trustee.

SET_AUDIT_FAILURE - Indicates a SYSTEM_AUDIT_ACE structure that generates audit messages for failed attempts to use the specified access rights. You can combine this value with the SET_AUDIT_SUCCESS member.  On input, this flag combines the specified rights with any existing audited access rights for the trustee.

Header file

<accctrl.h>

Remark

-

 

Table 1

 

ACL_INFORMATION_CLASS

 

Item

Description

Enumeration type

ACL_INFORMATION_CLASS.

Info

Contains values that specify the type of information being assigned to or retrieved from an ACL.

Definition

typedef enum _ACL_INFORMATION_CLASS

{ AclRevisionInformation = 1,

  AclSizeInformation

} ACL_INFORMATION_CLASS;

Constants

AclRevisionInformation - Indicates ACL revision information.

AclSizeInformation - Indicates ACL size information.

Header file

<windows.h>

Remark

-

 

Table 2

 

WELL_KNOWN_SID_TYPE

 

Item

Description

Enumeration type

WELL_KNOWN_SID_TYPE.

Info

Is a list of commonly used SIDs.  Programs can pass these values to the CreateWellKnownSid() function to create a SID from this list.

Definition

typedef enum

{

  WinNullSid = 0,

  WinWorldSid = 1,

  WinLocalSid = 2,

  WinCreatorOwnerSid = 3,

  WinCreatorGroupSid = 4,

  WinCreatorOwnerServerSid = 5,

  WinCreatorGroupServerSid = 6,

  WinNtAuthoritySid = 7,

  WinDialupSid = 8,

  WinNetworkSid = 9,

  WinBatchSid = 10,

  WinInteractiveSid = 11,

  WinServiceSid = 12,

  WinAnonymousSid = 13,

  WinProxySid = 14,

  WinEnterpriseControllersSid = 15,

  WinSelfSid = 16,

  WinAuthenticatedUserSid = 17,

  WinRestrictedCodeSid = 18,

  WinTerminalServerSid = 19,

  WinRemoteLogonIdSid = 20,

  WinLogonIdsSid = 21,

  WinLocalSystemSid = 22,

  WinLocalServiceSid = 23,

  WinNetworkServiceSid = 24,

  WinBuiltinDomainSid = 25,

  WinBuiltinAdministratorsSid = 26,

  WinBuiltinUsersSid = 27,

  WinBuiltinGuestsSid = 28,

  WinBuiltinPowerUsersSid = 29,

  WinBuiltinAccountOperatorsSid = 30,

  WinBuiltinSystemOperatorsSid = 31,

  WinBuiltinPrintOperatorsSid = 32,

  WinBuiltinBackupOperatorsSid = 33,

  WinBuiltinReplicatorSid = 34,

  WinBuiltinPreWindows2000CompatibleAccessSid = 35,

  WinBuiltinRemoteDesktopUsersSid = 36,

  WinBuiltinNetworkConfigurationOperatorsSid = 37,

  WinAccountAdministratorSid = 38,

  WinAccountGuestSid = 39,

  WinAccountKrbtgtSid = 40,

  WinAccountDomainAdminsSid = 41,

  WinAccountDomainUsersSid = 42,

  WinAccountDomainGuestsSid = 43,

  WinAccountComputersSid = 44,

  WinAccountControllersSid = 45,

  WinAccountCertAdminsSid = 46,

  WinAccountSchemaAdminsSid = 47,

  WinAccountEnterpriseAdminsSid = 48,

  WinAccountPolicyAdminsSid = 49,

  WinAccountRasAndIasServersSid = 50,

  WinNTLMAuthenticationSid = 51,

  WinDigestAuthenticationSid = 52,

  WinSChannelAuthenticationSid = 53,

  WinThisOrganizationSid = 54,

  WinOtherOrganizationSid = 55,

  WinBuiltinIncomingForestTrustBuildersSid = 56,

  WinBuiltinPerfMonitoringUsersSid = 57,

  WinBuiltinPerfLoggingUsersSid = 58,

  WinBuiltinAuthorizationAccessSid = 59,

  WinBuiltinTerminalServerLicenseServersSid = 60

} WELL_KNOWN_SID_TYPE;

Constants

WinNullSid -Indicates a null SID.

WinWorldSid - Indicates a SID that matches everyone.

WinLocalSid - Indicates a local SID.

WinCreatorOwnerSid - Indicates a SID that matches the owner or creator of an object.

WinCreatorGroupSid - Indicates a SID that matches the creator group of an object.

WinCreatorOwnerServerSid - Indicates a creator owner server SID.

WinCreatorGroupServerSid - Indicates a creator group server SID.

WinNtAuthoritySid - Indicates a SID for the Windows NT authority.

WinDialupSid - Indicates a SID for a dial-up account.

WinNetworkSid - Indicates a SID for a network account.  This SID is added to the process of a token when it logs on across a network.  The corresponding logon type is LOGON32_LOGON_NETWORK.

WinBatchSid - Indicates a SID for a batch process.  This SID is added to the process of a token when it logs on as a batch job.  The corresponding logon type is LOGON32_LOGON_BATCH.

WinInteractiveSid - Indicates a SID for an interactive account. This SID is added to the process of a token when it logs on interactively.  The corresponding logon type is LOGON32_LOGON_INTERACTIVE.

WinServiceSid - Indicates a SID for a service.  This SID is added to the process of a token when it logs on as a service.  The corresponding logon type is LOGON32_LOGON_SERVICE.

WinAnonymousSid - Indicates a SID for the anonymous account.

WinProxySid - Indicates a proxy SID.

WinEnterpriseControllersSid - Indicates a SID for an enterprise controller.

WinSelfSid - Indicates a SID for self.

WinAuthenticatedUserSid - Indicates a SID that matches any authenticated user.

WinRestrictedCodeSid - Indicates a SID for restricted code.

WinTerminalServerSid - Indicates a SID that matches a terminal server account.

WinRemoteLogonIdSid - Indicates a SID that matches remote logons.

WinLogonIdsSid - Indicates a SID that matches logon IDs.

WinLocalSystemSid - Indicates a SID that matches the local system.

WinLocalServiceSid - Indicates a SID that matches a local service.

WinNetworkServiceSid - Indicates a SID that matches a network service.

WinBuiltinDomainSid - Indicates a SID that matches the domain account.

WinBuiltinAdministratorsSid - Indicates a SID that matches the administrator account.

WinBuiltinUsersSid - Indicates a SID that matches built-in user accounts.

WinBuiltinGuestsSid - Indicates a SID that matches the guest account.

WinBuiltinPowerUsersSid - Indicates a SID that matches the power users group.

WinBuiltinAccountOperatorsSid - Indicates a SID that matches the account operators account.

WinBuiltinSystemOperatorsSid - Indicates a SID that matches the system operators group.

WinBuiltinPrintOperatorsSid - Indicates a SID that matches the print operators group.

WinBuiltinBackupOperatorsSid - Indicates a SID that matches the backup operators group.

WinBuiltinReplicatorSid - Indicates a SID that matches the replicator account.

WinBuiltinPreWindows2000CompatibleAccessSid - Indicates a SID that matches pre-Windows 2000 compatible accounts.

WinBuiltinRemoteDesktopUsersSid - Indicates a SID that matches remote desktop users.

WinBuiltinNetworkConfigurationOperatorsSid - Indicates a SID that matches the network operators group.

WinAccountAdministratorSid - Indicates a SID that matches the account administrators group.

WinAccountGuestSid - Indicates a SID that matches the account guest group.

WinAccountKrbtgtSid - Indicates a SID that matches account Kerberos target group.

WinAccountDomainAdminsSid - Indicates a SID that matches the account domain administrator group.

WinAccountDomainUsersSid - Indicates a SID that matches the account domain users group.

WinAccountDomainGuestsSid - Indicates a SID that matches the account domain guests group.

WinAccountComputersSid - Indicates a SID that matches the account computer group.

WinAccountControllersSid - Indicates a SID that matches the account controller group.

WinAccountCertAdminsSid - Indicates a SID that matches the certificate administrators group.

WinAccountSchemaAdminsSid - Indicates a SID that matches the schema administrators group.

WinAccountEnterpriseAdminsSid - Indicates a SID that matches the enterprise administrators group.

WinAccountPolicyAdminsSid - Indicates a SID that matches the policy administrators group.

WinAccountRasAndIasServersSid - Indicates a SID that matches the RAS and IAS server account.

WinNTLMAuthenticationSid - Indicates a SID present when the Microsoft NTLM authentication package authenticated the client.

WinDigestAuthenticationSid - Indicates a SID present when the Microsoft Digest authentication package authenticated the client.

WinSChannelAuthenticationSid - Indicates a SID present when the Secure Channel (SSL/TLS) authentication package authenticated the client.

WinThisOrganizationSid - Indicates a SID present when the user authenticated from within the forest or across a trust that does not have the selective authentication option enabled.  If this SID is present, then WinOtherOrganizationSid cannot be present.

WinOtherOrganizationSid - Indicates a SID present when the user authenticated across a forest with the selective authentication option enabled.  If this SID is present, then WinThisOrganizationSid cannot be present.

WinBuiltinIncomingForestTrustBuildersSid - Indicates a SID that allows a user to create incoming forest trusts. It is added to the token of users who are a member of the Incoming Forest Trust Builders built-in group in the root domain of the forest.

WinBuiltinPerfMonitoringUsersSid - Indicates a SID that matches the performance monitor user group.

WinBuiltinPerfLoggingUsersSid - Indicates a SID that matches the performance log user group.

WinBuiltinAuthorizationAccessSid - Indicates a SID that matches the Windows Authorization Access group.

WinBuiltinTerminalServerLicenseServersSid - Indicates a SID is present in a server that can issue Terminal Server licenses.

Header file

<windows.h>

Remark

Require Win Xp and Win Server 2003.

 

Table 3

 

MULTIPLE_TRUSTEE_OPERATION

 

Item

Description

Enumeration type

MULTIPLE_TRUSTEE_OPERATION.

Info

Contains values that indicate whether a TRUSTEE structure is an impersonation trustee.

Definition

typedef enum _MULTIPLE_TRUSTEE_OPERATION

{

  NO_MULTIPLE_TRUSTEE,

  TRUSTEE_IS_IMPERSONATE

} MULTIPLE_TRUSTEE_OPERATION;

Constants

NO_MULTIPLE_TRUSTEE - The trustee is not an impersonation trustee.

TRUSTEE_IS_IMPERSONATE - The trustee is an impersonation trustee.  The pMultipleTrustee member of the TRUSTEE structure points to a trustee for a server that can impersonate the client trustee.

Header file

<accctrl.h>

Remark

-

 

Table 21

 

TRUSTEE_FORM

 

Item

Description

Enumeration type

TRUSTEE_FORM.

Info

Contains values that indicate the type of data pointed to by the ptstrName member of the TRUSTEE structure.

Definition

typedef enum _TRUSTEE_FORM

{

  TRUSTEE_IS_SID,

  TRUSTEE_IS_NAME,

  TRUSTEE_BAD_FORM,

  TRUSTEE_IS_OBJECTS_AND_SID,

  TRUSTEE_IS_OBJECTS_AND_NAME

} TRUSTEE_FORM;

Constants

TRUSTEE_IS_SID - The ptstrName member is a pointer to a security identifier (SID) that identifies the trustee.

TRUSTEE_IS_NAME - The ptstrName member is a pointer to a null-terminated string that identifies the trustee.

TRUSTEE_BAD_FORM - Indicates an invalid trustee form.

TRUSTEE_IS_OBJECTS_AND_SID - The ptstrName member is a pointer to an OBJECTS_AND_SID structure that contains the SID of the trustee and the GUIDs of the object types in an object-specific access control entry (ACE).

TRUSTEE_IS_OBJECTS_AND_NAME - The ptstrName member is a pointer to an OBJECTS_AND_NAME structure that contains the name of the trustee and the names of the object types in an object-specific ACE.

Header file

<accctrl.h>

Remark

-

 

Table 22

 

TRUSTEE_TYPE

 

Item

Description

Enumeration type

TRUSTEE_TYPE.

Info

Contains values that indicate the type of trustee identified by a TRUSTEE structure.

Definition

typedef enum _TRUSTEE_TYPE

{

  TRUSTEE_IS_UNKNOWN,

  TRUSTEE_IS_USER,

  TRUSTEE_IS_GROUP,

  TRUSTEE_IS_DOMAIN,

  TRUSTEE_IS_ALIAS,

  TRUSTEE_IS_WELL_KNOWN_GROUP,

  TRUSTEE_IS_DELETED,

  TRUSTEE_IS_INVALID,

  TRUSTEE_IS_COMPUTER

} TRUSTEE_TYPE;

Constants

TRUSTEE_IS_UNKNOWN - The trustee type is unknown, but not necessarily invalid.

TRUSTEE_IS_USER - Indicates a user.

TRUSTEE_IS_GROUP - Indicates a group.

TRUSTEE_IS_DOMAIN - Indicates a domain.

TRUSTEE_IS_ALIAS - Indicates an alias.

TRUSTEE_IS_WELL_KNOWN_GROUP - Indicates a well-known group.

TRUSTEE_IS_DELETED - Indicates a deleted account.

TRUSTEE_IS_INVALID - Indicates an invalid trustee type.

TRUSTEE_IS_COMPUTER - Indicates a computer.

Header file

<accctrl.h>

Remark

-

 

Table 23

 

SE_OBJECT_TYPE

 

Item

Description

Enumeration type

SE_OBJECT_TYPE.

Info

Contains values that correspond to the types of Windows objects that support security.  The functions, such as GetSecurityInfo() and SetSecurityInfo(), that set and retrieve the security information of an object, use these values to indicate the type of object.

Definition

typedef enum _SE_OBJECT_TYPE

{

  SE_UNKNOWN_OBJECT_TYPE = 0,

  SE_FILE_OBJECT,

  SE_SERVICE,

  SE_PRINTER,

  SE_REGISTRY_KEY,

  SE_LMSHARE,

  SE_KERNEL_OBJECT,

  SE_WINDOW_OBJECT,

  SE_DS_OBJECT,

  SE_DS_OBJECT_ALL,

  SE_PROVIDER_DEFINED_OBJECT,

  SE_WMIGUID_OBJECT,

  SE_REGISTRY_WOW64_32KEY

} SE_OBJECT_TYPE;

Constants

SE_UNKNOWN_OBJECT_TYPE - Unknown object type.

SE_FILE_OBJECT - Indicates a file or directory.  The name string that identifies a file or directory object can be in one of the following formats:

  1. A relative path, such as "abc.dat" or "..\abc.dat"

  2. An absolute path, such as "\abc.dat", "c:\dir1\abc.dat", or "g:\remote_dir\abc.dat"

  3. A UNC name, such as "\\computer_name\share_name\abc.dat".

  4. A local file system root, such as "\\\\.\\c:".  Security set on a file system root does not persist when the system is restarted.

 

SE_SERVICE - Indicates a Windows service.  A service object can be a local service, such as "service_name"; or a remote service, such as "\\computer_name\service_name".

SE_PRINTER - Indicates a printer.  A printer object can be a local printer, such as "printer_name"; or a remote printer, such as "\\computer_name\printer_name".

SE_REGISTRY_KEY - Indicates a registry key.  A registry key object can be in the local registry, such as "CLASSES_ROOT\some_path"; or in a remote registry, such as "\\computer_name\CLASSES_ROOT\some_path". The names of registry keys must use the following literal strings to identify the predefined registry keys: "CLASSES_ROOT", "CURRENT_USER", "MACHINE", and "USERS".

SE_LMSHARE - Indicates a network share.  A share object can be local, such as "share_name"; or remote, such as "\\computer_name\share_name".

SE_KERNEL_OBJECT - Indicates a local kernel object. The GetSecurityInfo() and SetSecurityInfo() functions support all types of kernel objects.  The GetNamedSecurityInfo() and SetNamedSecurityInfo() functions work only with the following kernel objects: semaphore, event, mutex, waitable timer, and file mapping.

SE_WINDOW_OBJECT - Indicates a window station or desktop object on the local computer.  You cannot use GetNamedSecurityInfo() and SetNamedSecurityInfo() with these objects because the names of window stations or desktops are not unique.

SE_DS_OBJECT - Indicates a directory service (DS) object or a property set or property of a directory service object.  The name string for a DS object must be in X.500 form; for example:

CN=someobject,OU=ou2,OU=ou1,DC=domain,DC=fabrikam,DC=com,O=internet.

SE_DS_OBJECT_ALL - Indicates a directory service object and all of its property sets and properties.

SE_PROVIDER_DEFINED_OBJECT - Indicates a provider-defined object.  Windows NT, Windows Me/98/95:  This enumeration value is not supported.

SE_WMIGUID_OBJECT - Indicates a WMI object.  Windows NT, Windows Me/98/95:  This enumeration value is not supported.

SE_REGISTRY_WOW64_32KEY - Indicates an object for a registry entry under WOW64.  Windows 2000, Windows NT:  This enumeration value is not supported.

Header file

<accctrl.h>

Remark

-

 

Table 24

 

TOKEN_TYPE

 

Item

Description

Enumeration type

TOKEN_TYPE.

Info

Contains values that differentiate between a primary token and an impersonation token.

Definition

typedef enum tagTOKEN_TYPE

{

  TokenPrimary= 1,

  TokenImpersonation

} TOKEN_TYPE;

Constants

TokenPrimary - Indicates a primary token.

TokenImpersonation - Indicates an impersonation token.

Header file

<windows.h>

Remark

-

 

Table 28

 

TOKEN_INFORMATION_CLASS

 

Item

Description

Enumeration type

TOKEN_INFORMATION_CLASS.

Info

Contains values that specify the type of information being assigned to or retrieved from an access token.  The GetTokenInformation() function uses these values to indicate the type of token information to retrieve.

Definition

typedef enum _TOKEN_INFORMATION_CLASS

{

  TokenUser = 1,

  TokenGroups,

  TokenPrivileges,

  TokenOwner,

  TokenPrimaryGroup,

  TokenDefaultDacl,

  TokenSource,

  TokenType,

  TokenImpersonationLevel,

  TokenStatistics,

  TokenRestrictedSids,

  TokenSessionId,

  TokenGroupsAndPrivileges,

  TokenSessionReference,

  TokenSandBoxInert,

  TokenAuditPolicy,

  TokenOrigin

} TOKEN_INFORMATION_CLASS;

Constants

TokenUser - The buffer receives a TOKEN_USER structure that contains the user account of the token.

TokenGroups - The buffer receives a TOKEN_GROUPS structure that contains the group accounts associated with the token.

TokenPrivileges - The buffer receives a TOKEN_PRIVILEGES structure that contains the privileges of the token.

TokenOwner - The buffer receives a TOKEN_OWNER structure that contains the default owner security identifier (SID) for newly created objects.

TokenPrimaryGroup - The buffer receives a TOKEN_PRIMARY_GROUP structure that contains the default primary group SID for newly created objects.

TokenDefaultDacl - The buffer receives a TOKEN_DEFAULT_DACL structure that contains the default DACL for newly created objects.

TokenSource - The buffer receives a TOKEN_SOURCE structure that contains the source of the token.  TOKEN_QUERY_SOURCE access is needed to retrieve this information.

TokenType - The buffer receives a TOKEN_TYPE value that indicates whether the token is a primary or impersonation token.

TokenImpersonationLevel - The buffer receives a SECURITY_IMPERSONATION_LEVEL value that indicates the impersonation level of the token.  If the access token is not an impersonation token, the function fails.

TokenStatistics - The buffer receives a TOKEN_STATISTICS structure that contains various token statistics.

TokenRestrictedSids - The buffer receives a TOKEN_GROUPS structure that contains the list of restricting SIDs in a restricted token.

TokenSessionId - The buffer receives a DWORD value that indicates the Terminal Services session identifier that is associated with the token.

  1. If the token is associated with the Terminal Server console session, the session identifier is zero.

  2. If the token is associated with the Terminal Server client session, the session identifier is nonzero.

 

In a non-Terminal Services environment, the session identifier is zero.

If TokenSessionId is set with SetTokenInformation, the application must have the Act As Part Of the Operating System privilege, and the application must be enabled to set the session ID in a token.

TokenGroupsAndPrivileges - The buffer receives a TOKEN_GROUPS_AND_PRIVILEGES structure that contains the user SID, the group accounts, the restricted SIDs, and the authentication ID associated with the token.

TokenSessionReference - Reserved for internal use.

TokenSandBoxInert - The buffer receives a DWORD value that is nonzero if the token includes the SANDBOX_INERT flag.

TokenAuditPolicy - Reserved for future use.

TokenOrigin - The buffer receives a TOKEN_ORIGIN value. If the token resulted from a logon that used explicit credentials, such as passing a name, domain, and password to the LogonUser() function, then the TOKEN_ORIGIN structure will contain the ID of the logon session that created it.  If the token resulted from network authentication, such as a call to AcceptSecurityContext() or a call to LogonUser() with dwLogonType set to LOGON32_LOGON_NETWORK or LOGON32_LOGON_NETWORK_CLEARTEXT, then this value will be zero.

Header file

<windows.h>

Remark

-

 

Table 33

 

SECURITY_IMPERSONATION_LEVEL

 

Item

Description

Enumeration type

SECURITY_IMPERSONATION_LEVEL.

Info

Enumeration type contains values that specify security impersonation levels.  Security impersonation levels govern the degree to which a server process can act on behalf of a client process.

Definition

typedef enum _SECURITY_IMPERSONATION_LEVEL

{

  SecurityAnonymous,

  SecurityIdentification,

  SecurityImpersonation,

  SecurityDelegation

} SECURITY_IMPERSONATION_LEVEL;

Constants

SecurityAnonymous - The server process cannot obtain identification information about the client, and it cannot impersonate the client.  It is defined with no value given, and thus, by ANSI C rules, defaults to a value of zero.

SecurityIdentification - The server process can obtain information about the client, such as security identifiers and privileges, but it cannot impersonate the client.  This is useful for servers that export their own objects, for example, database products that export tables and views.  Using the retrieved client-security information, the server can make access-validation decisions without being able to use other services that are using the client's security context.

SecurityImpersonation - The server process can impersonate the client's security context on its local system.  The server cannot impersonate the client on remote systems.

SecurityDelegation - The server process can impersonate the client's security context on remote systems.

Header file

<windows.h>

Remark

Impersonation is the ability of a process to take on the security attributes of another process.

 

Table 41

 

Macro

 

ZeroMemory()

 

Item

Description

Macro

ZeroMemory().

Info

Fills a block of memory with zeros.  To avoid undesired effects of optimizing compilers, use the SecureZeroMemory() function.

Definition

void ZeroMemory(PVOID Destination, SIZE_T Length);

Parameters

Destination - [in] Pointer to the starting address of the block of memory to fill with zeros.

Length - [in] Size of the block of memory to fill with zeros, in bytes.

Return value

This function has no return value.

Header file

<windows.h>

Remark

-

 

Table 4

 

TEXT

 

Item

Description

Macro

TEXT.

Info

Identifies a string as Unicode when the UNICODE is defined during compilation. Otherwise, it identifies a string as an ANSI string.

Definition

TEXT(LPTSTR string);

Parameters

string - Pointer to the string to be interpreted as either Unicode or ANSI.

Header file

<windows.h>

Remark

-

 

Table 5

 

Type

 

SECURITY_INFORMATION

 

A data type that identifies the object-related security information being set or queried. This security information includes:

  1. The owner of an object.

  2. The primary group of an object.

  3. The DACL of an object.

  4. The SACL of an object.

typedef DWORD SECURITY_INFORMATION, *PSECURITY_INFORMATION;

New SECURITY_INFORMATION members work only with the SetNamedSecurityInfo() function.  These new members are not returned in the structure returned by other security functions such as GetNamedSecurityInfo() or ConvertStringSecurityDescriptorToSecurityDescriptor(). For Windows NT, the new members are not supported.  Must include windows.h header file. Each item of security information is designated by a bit flag. Each bit flag can be one of the following values.

 

Value

Meaning

DACL_SECURITY_INFORMATION

Indicates the DACL of the object is being referenced.

GROUP_SECURITY_INFORMATION

Indicates the primary group identifier of the object is being referenced.

OWNER_SECURITY_INFORMATION

Indicates the owner identifier of the object is being referenced.

PROTECTED_DACL_SECURITY_INFORMATION

Indicates the DACL cannot inherit ACEs.  Windows NT:  This value is not supported.

PROTECTED_SACL_SECURITY_INFORMATION

Indicates the SACL cannot inherit ACEs.  Windows NT:  This value is not supported.

SACL_SECURITY_INFORMATION

Indicates the SACL of the object is being referenced.

UNPROTECTED_DACL_SECURITY_INFORMATION

Indicates the DACL inherits ACEs from the parent object.

Windows NT:  This value is not supported.

UNPROTECTED_SACL_SECURITY_INFORMATION

Indicates the SACL inherits ACEs from the parent object.  Windows NT:  This value is not supported.

 

Table 6

 

SECURITY_DESCRIPTOR_CONTROL

 

The SECURITY_DESCRIPTOR_CONTROL data type is a set of bit flags that qualify the meaning of a security descriptor or its components.  Each security descriptor has a Control member that stores the SECURITY_DESCRIPTOR_CONTROL bits.

typedef WORD SECURITY_DESCRIPTOR_CONTROL;

To get the control bits of a security descriptor, call the GetSecurityDescriptorControl() function.  To set the control bits of a security descriptor, use the functions for modifying security descriptors.  Applications can use the SetSecurityDescriptorControl() function to set the control bits that relate to automatic inheritance of ACEs.  The control value retrieved by the GetSecurityDescriptorControl() function can include a combination of the following SECURITY_DESCRIPTOR_CONTROL bit flags:

 

Value

Meaning

SE_DACL_AUTO_INHERITED

Indicates a security descriptor in which the DACL is set up to support automatic propagation of inheritable ACEs to existing child objects.  For ACLs that support auto inheritance, this bit is always set.  It is used to distinguish these ACLs from Windows NT 4.0 ACLs that do not support auto inheritance.  Protected servers can call the ConvertToAutoInheritPrivateObjectSecurity() function to convert a security descriptor and set this flag.

SE_DACL_DEFAULTED

Indicates a security descriptor with a default DACL.  For example, if the creator an object does not specify a DACL, the object receives the default DACL from the access token of the creator.  This flag can affect how the system treats the DACL with respect to ACE inheritance. The system ignores this flag if the SE_DACL_PRESENT flag is not set.  This flag is used to determine how the final DACL on the object is to be computed and is not stored physically in the security descriptor control of the securable object.  To set this flag, use the SetSecurityDescriptorDacl() function.

SE_DACL_PRESENT

Indicates a security descriptor that has a DACL.  If this flag is not set, or if this flag is set and the DACL is NULL, the security descriptor allows full access to everyone.  This flag is used to hold the security information specified by a caller until the security descriptor is associated with a securable object.  After the security descriptor is associated with a securable object, the SE_DACL_PRESENT flag is always set in the security descriptor control.  To set this flag, use the SetSecurityDescriptorDacl() function.

SE_DACL_PROTECTED

Prevents the DACL of the security descriptor from being modified by inheritable ACEs. To set this flag, use the SetSecurityDescriptorControl() function.

SE_GROUP_DEFAULTED

Indicates that the security identifier (SID) of the security descriptor group was provided by a default mechanism.  This flag can be used by a resource manager to identify objects whose security descriptor group was set by a default mechanism.  To set this flag, use the SetSecurityDescriptorGroup() function.

SE_OWNER_DEFAULTED

Indicates that the SID of the owner of the security descriptor was provided by a default mechanism.  This flag can be used by a resource manager to identify objects whose owner was set by a default mechanism.  To set this flag, use the SetSecurityDescriptorOwner() function.

SE_SACL_AUTO_INHERITED

Indicates a security descriptor in which the SACL is set up to support automatic propagation of inheritable ACEs to existing child objects.  The system sets this bit when it performs the automatic inheritance algorithm for the object and its existing child objects.  To convert a security descriptor and set this flag, protected servers can call the ConvertToAutoInheritPrivateObjectSecurity() function.

SE_SACL_DEFAULTED

A default mechanism, rather than the original provider of the security descriptor, provided the SACL.  This flag can affect how the system treats the SACL, with respect to ACE inheritance.  The system ignores this flag if the SE_SACL_PRESENT flag is not set.  To set this flag, use the SetSecurityDescriptorSacl() function.

SE_SACL_PRESENT

Indicates a security descriptor that has a SACL. To set this flag, use the SetSecurityDescriptorSacl() function.

SE_SACL_PROTECTED

Prevents the SACL of the security descriptor from being modified by inheritable ACEs.  To set this flag, use the SetSecurityDescriptorControl() function.

SE_SELF_RELATIVE

Indicates a self-relative security descriptor.  If this flag is not set, the security descriptor is in absolute format.

Header file

<windows.h>

 

Table 7

 

ACE

 

An ACE is an access control entry in an ACL.  The following table lists the currently defined ACE types (Discretionary – DACL, System – SACL).

 

ACE type

Structure

ACL type

Access allowed.

ACCESS_ALLOWED_ACE

Discretionary

Access allowed. Allows callback during access check.

ACCESS_ALLOWED_CALLBACK_ACE

Discretionary

Access allowed. Object specific.

ACCESS_ALLOWED_OBJECT_ACE

Discretionary

Access allowed. Object specific. Allows callback during access check.

ACCESS_ALLOWED_CALLBACK_OBJECT_ACE

Discretionary

Access denied.

ACCESS_DENIED_ACE

Discretionary

Access denied. Allows callback during access check.

ACCESS_DENIED_CALLBACK_ACE

Discretionary

Access denied. Object specific. Allows callback during access check.

ACCESS_DENIED_CALLBACK_OBJECT_ACE

Discretionary

Access denied. Object specific.

ACCESS_DENIED_OBJECT_ACE

Discretionary

System alarm.

SYSTEM_ALARM_ACE

System

System alarm. Allows callback during access check.

SYSTEM_ALARM_CALLBACK_ACE

System

System alarm. Object specific. Allows callback during access check.

SYSTEM_ALARM_CALLBACK_OBJECT_ACE

System

System alarm. Object specific.

SYSTEM_ALARM_OBJECT_ACE

System

System audit.

SYSTEM_AUDIT_ACE

System

System audit. Allows callback during access check.

SYSTEM_AUDIT_CALLBACK_ACE

System

System audit. Object specific. Allows callback during access check.

SYSTEM_AUDIT_CALLBACK_OBJECT_ACE

System

System audit. Object specific.

SYSTEM_AUDIT_OBJECT_ACE

System

Header file

<windows.h>

 

Table 8

 

System-alarm and object-specific system-alarm ACEs are not currently supported.  Each ACE starts with an ACE_HEADER structure.  The format of the data following the header varies according to the ACE type specified in the header.

 

Structures

 

SECURITY_ATTRIBUTES

 

Item

Description

Structure

SECURITY_ATTRIBUTES.

Info

Contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable.  This structure provides security settings for objects created by various functions, such as CreateFile(), CreatePipe(), CreateProcess(), RegCreateKeyEx(), or RegSaveKeyEx().

Definition

typedef struct _SECURITY_ATTRIBUTES {

  DWORD nLength;

  LPVOID lpSecurityDescriptor;

  BOOL bInheritHandle;

} SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES;

Members

nLength - Specifies the size, in bytes, of this structure. Set this value to the size of the SECURITY_ATTRIBUTES structure such as sizeof(SECURITY_ATTRIBUTES).

lpSecurityDescriptor - Pointer to a security descriptor for the object that controls the sharing of it. If NULL is specified for this member, the object is assigned the default security descriptor of the calling process.  This is not the same as granting access to everyone by assigning a NULL DACL.  The default security descriptor is based on the default DACL of the access token belonging to the calling process.  By default, the default DACL in the access token of a process allows access only to the user represented by the access token.  If other users must access the object, you can either create a security descriptor with the appropriate access, or add ACEs to the DACL that grants access to a group of users.

bInheritHandle - Specifies whether the returned handle is inherited when a new process is created. If this member is TRUE, the new process inherits the handle.

Header file

<windows.h>

Remark

-

 

Table 9

 

SID

 

Item

Description

Structure

SID.

Info

Variable-length structure used to uniquely identify users or groups.

Definition

typedef struct _SID {

  ...

} SID, *PSID;

Members

Variable.

Header file

<windows.h>

Remark

-

 

Table 10

 

SECURITY_DESCRIPTOR

 

Item

Description

Structure

SECURITY_DESCRIPTOR.

Info

Contains the security information associated with an object.  Applications use this structure to set and query an object's security status.

Definition

typedef struct SECURITY_DESCRIPTOR {

  ...

} SECURITY_DESCRIPTOR, *PISECURITY_DESCRIPTOR,  PSECURITY_DESCRIPTOR;

Members

Variety.

Header file

<windows.h>

Remark

-

 

Table 11

 

Because the internal format of a security descriptor can vary, applications are not to modify the SECURITY_DESCRIPTOR structure directly.  A security descriptor includes information that specifies the following components of an object's security:

  1. An owner (SID).

  2. A primary group (SID).

  3. A discretionary ACL.

  4. A system ACL.

  5. Qualifiers for the preceding items.

 

Several functions that use the SECURITY_DESCRIPTOR structure require that this structure be on a valid pointer boundary in memory.  These boundaries vary depending on the type of processor used.  Memory allocation functions, such as malloc() and LocalAlloc(), return properly aligned pointers.

 

OBJECTS_AND_NAME

 

Item

Description

Structure

OBJECTS_AND_NAME.

Info

Contains a string that identifies a trustee by name and additional strings that identify the object types of an object-specific ACE.

Definition

typedef struct _OBJECTS_AND_NAME {
  DWORD          ObjectsPresent;
  SE_OBJECT_TYPE ObjectType;
  LPTSTR         InheritedObjectTypeName;
  LPTSTR         ptstrName;

} OBJECTS_AND_NAME,  *POBJECTS_AND_NAME;

Members

ObjectsPresent - Indicates whether the ObjectTypeName and InheritedObjectTypeName members contain strings.  This parameter can be a combination of the following values:

  1. ACE_OBJECT_TYPE_PRESENT - The ObjectTypeName member contains a string.

  2. ACE_INHERITED_OBJECT_TYPE_PRESENT - The InheritedObjectTypeName member contains a string.

 

ObjectType - Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object.

InheritedObjectTypeName - Pointer to a null-terminated string that identifies the type of object that can inherit the ACE.  This string must be a valid LDAP display name in the Active Directory schema.  If the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the InheritedObjectTypeName member is ignored, and all types of child objects can inherit the ACE.  Otherwise, only the specified object type can inherit the ACE.  In either case, inheritance is also controlled by the inheritance flags in the ACE_HEADER structure as well as by any protection against inheritance placed on the child objects.

ptstrName - Pointer to a null-terminated string that contains the name of the trustee.

Header file

<accctrl.h>

Remark

-

 

Table 12

 

The ptstrName member of a TRUSTEE structure can be a pointer to an OBJECTS_AND_NAME structure.  This enables functions such as SetEntriesInAcl() and GetExplicitEntriesFromAcl() to store object-specific ACE information in the Trustee member of an EXPLICIT_ACCESS structure.

 

TRUSTEE

 

Item

Description

Structure

TRUSTEE.

Info

Identifies the user account, group account, or logon session to which an access control entry (ACE) applies.  The structure can use a name or a security identifier (SID) to identify the trustee.

Definition

typedef struct _TRUSTEE {
PTRUSTEE pMultipleTrustee;
MULTIPLE_TRUSTEE_OPERATION MultipleTrusteeOperation;
TRUSTEE_FORM TrusteeForm;
TRUSTEE_TYPE TrusteeType;
LPTSTR ptstrName;

} TRUSTEE,   *PTRUSTEE;

Members

pMultipleTrustee - A pointer to a TRUSTEE structure that identifies a server account that can impersonate the user identified by the ptstrName member.  This member is not currently supported and must be NULL.

MultipleTrusteeOperation - A value of the MULTIPLE_TRUSTEE_OPERATION enumeration type. Currently, this member must be NO_MULTIPLE_TRUSTEE.

TrusteeForm - A value from the TRUSTEE_FORM enumeration type that indicates the type of data pointed to by the ptstrName member.

TrusteeType - A value from the TRUSTEE_TYPE enumeration type that indicates whether the trustee is a user account, a group account, or an unknown account type.

ptstrName - A pointer to a buffer that identifies the trustee and, optionally, contains information about object-specific ACEs.  The type of data depends on the value of the TrusteeForm member.  This member can be one of the following values:

  1. TRUSTEE_IS_NAME - Pointer to a null-terminated string that contains the name of the trustee.

  2. TRUSTEE_IS_OBJECTS_AND_NAME - Pointer to an OBJECTS_AND_NAME structure that contains the name of the trustee and the names of the object types in an object-specific ACE.

  3. TRUSTEE_IS_OBJECTS_AND_SID - Pointer to an OBJECTS_AND_SID structure that contains the SID of the trustee and the GUIDs of the object types in an object-specific ACE.

  4. TRUSTEE_IS_SID - Pointer to the SID of the trustee.

Header file

<accctrl.h>

Remark

A trustee SID can be any user or group SID.  It can also be any of the universal, well-known SIDs.

 

Table 13

 

Access control functions, such as SetEntriesInAcl() and GetExplicitEntriesFromAcl(), use this structure to identify the logon account associated with the access control or audit control information in an EXPLICIT_ACCESS structure.  A trustee name can have any of the following formats:

  1. A fully qualified name, such as "g:\remotedir\abc".

  2. A domain account, such as "domain1\xyz".

  3. One of the predefined group names, such as "EVERYONE" or "GUEST".

  4. One of the following special names:

 

Name

Meaning

CREATOR GROUP

The CREATOR_GROUP SID is a SID used in inheritable ACEs.  When a new object is created, the system replaces this SID with the primary group SID of the user who created the object.

CREATOR OWNER

The CREATOR_OWNER SID is a SID used in inheritable ACEs.  When a new object is created, the system replaces this SID with the SID of the user who created the object.

CURRENT_USER

The owner of the calling thread or process.

 

Table 14

 

OBJECTS_AND_SID

 

Item

Description

Structure

OBJECTS_AND_SID.

Info

Contains a SID that identifies a trustee and GUIDs that identify the object types of an object-specific ACE.

Definition

typedef struct _OBJECTS_AND_SID {
DWORD ObjectsPresent;
GUID ObjectTypeGuid;
GUID InheritedObjectTypeGuid;
SID* pSID;

} OBJECTS_AND_SID,  *POBJECTS_AND_SID;

Members

ObjectsPresent - Indicates whether the ObjectTypeGuid and InheritedObjectTypeGuid members contain GUIDs.  This parameter can be a combination of the following values:

  1. ACE_OBJECT_TYPE_PRESENT - The ObjectTypeGuid member contains a GUID.

  2. ACE_INHERITED_OBJECT_TYPE_PRESENT - The InheritedObjectTypeGuid member contains a GUID.

 

ObjectTypeGuid - A GUID structure that identifies the type of object, property set, or property protected by the ACE.  If this ACE is inherited, the GUID identifies the type of object, property set, or property protected by the inherited ACE.  This GUID must be a valid schema identifier in the Active Directory schema.  If the ACE_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the ObjectTypeGuid member is ignored, and the ACE protects the object to which the ACL is assigned.

InheritedObjectTypeGuid - A GUID structure that identifies the type of object that can inherit the ACE. This GUID must be a valid schema identifier in the Active Directory schema.  If the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is not set in the ObjectsPresent member, the InheritedObjectTypeGuid member is ignored, and all types of child objects can inherit the ACE.  Otherwise, only the specified object type can inherit the ACE.  In either case, inheritance is also controlled by the inheritance flags in the ACE_HEADER structure as well as by any protection against inheritance placed on the child objects.

pSID - Pointer to the SID of the trustee to whom the ACE applies.

Header file

<accctrl.h>

Remark

-

 

Table 15

 

The ptstrName member of a TRUSTEE structure can be a pointer to an OBJECTS_AND_SID structure.  This enables functions such as SetEntriesInAcl() and GetExplicitEntriesFromAcl() to store object-specific ACE information in the Trustee member of an EXPLICIT_ACCESS structure.  When you use this structure in a call to SetEntriesInAcl(), ObjectTypeGuid and InheritedObjectTypeGuid must be valid schema identifiers in the Active Directory schema.  The system does not verify the GUIDs; they are used as is.

 

EXPLICIT_ACCESS

 

Item

Description

Structure

EXPLICIT_ACCESS.

Info

Defines access control information for a specified trustee.  Access control functions, such as SetEntriesInAcl() and GetExplicitEntriesFromAcl(), use this structure to describe the information in an ACE of an ACL.

Definition

typedef struct _EXPLICIT_ACCESS {

  DWORD       grfAccessPermissions;

  ACCESS_MODE grfAccessMode;

  DWORD       grfInheritance;

  TRUSTEE     Trustee;

} EXPLICIT_ACCESS,   *PEXPLICIT_ACCESS;

Members

grfAccessPermissions - A set of bit flags that use the ACCESS_MASK format to specify the access rights that an ACE allows, denies, or audits for the trustee.  The functions that use the EXPLICIT_ACCESS structure do not convert, interpret, or validate the bits in this mask.

grfAccessMode - Specifies a value from the ACCESS_MODE enumeration.  For a DACL, this flag indicates whether the ACL allows or denies the specified access rights.  For a SACL, this flag indicates whether the ACL generates audit messages for successful attempts to use the specified access rights, or failed attempts, or both.  When modifying an existing ACL, you can specify the REVOKE_ACCESS flag to remove any existing ACEs for the specified trustee.

grfInheritance - A set of bit flags that determines whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached.  The value of this member corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure.  This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable; or it can be a combination of the following values:

 

  1. CONTAINER_INHERIT_ACE - Other containers that are contained by the primary object inherit the ACE.

  2. INHERIT_ONLY_ACE - The ACE does not apply to the primary object to which the ACL is attached, but objects contained by the primary object inherit the ACE.

  3. NO_PROPAGATE_INHERIT_ACE - The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags are not propagated to an inherited ACE.

  4. OBJECT_INHERIT_ACE - Non container objects contained by the primary object inherit the ACE.

  5. SUB_CONTAINERS_AND_OBJECTS_INHERIT - Both containers and non container objects that are contained by the primary object inherit the ACE.  This flag corresponds to the combination of the CONTAINER_INHERIT_ACE and OBJECT_INHERIT_ACE flags.

  6. SUB_CONTAINERS_ONLY_INHERIT - Other containers that are contained by the primary object inherit the ACE.  This flag corresponds to the CONTAINER_INHERIT_ACE flag.

  7. SUB_OBJECTS_ONLY_INHERIT - Non container objects contained by the primary object inherit the ACE.  This flag corresponds to the OBJECT_INHERIT_ACE flag.

 

Trustee - A TRUSTEE structure that identifies the user, group, or program (such as a Windows service) to which the ACE applies.

Header file

<accctrl.h>

Remark

Use array of the EXPLICIT_ACCESS structure if you need to defined more than one trustee.

 

Table 16

 

ACE_HEADER

 

The ACE_HEADER structure defines the type and size of an access control entry (ACE).  Must include windows.h header file.

typedef struct _ACE_HEADER {

  BYTE AceType;

  BYTE AceFlags;

  WORD AceSize;

} ACE_HEADER,  *PACE_HEADER;

 

Members

 

AceType - Specifies the ACE type.  This member can be one of the following values:

 

Value

Meaning

ACCESS_ALLOWED_ACE_TYPE

Access-allowed ACE that uses the ACCESS_ALLOWED_ACE structure.

ACCESS_ALLOWED_CALLBACK_ACE_TYPE

Access-allowed callback ACE that uses the ACCESS_ALLOWED_CALLBACK_ACE structure. Windows 2000, Windows NT:  Not supported.

ACCESS_ALLOWED_CALLBACK_OBJECT_ACE_TYPE

Object-specific access-allowed callback ACE that uses the ACCESS_ALLOWED_CALLBACK_OBJECT_ACE structure.  Windows 2000, Windows NT:  Not supported.

ACCESS_ALLOWED_COMPOUND_ACE_TYPE

Reserved.

ACCESS_ALLOWED_OBJECT_ACE_TYPE

Object-specific access-allowed ACE that uses the ACCESS_ALLOWED_OBJECT_ACE structure.

ACCESS_DENIED_ACE_TYPE

Access-denied ACE that uses the ACCESS_DENIED_ACE structure.

ACCESS_DENIED_CALLBACK_ACE_TYPE

Access-denied callback ACE that uses the ACCESS_DENIED_CALLBACK_ACE structure.

Windows 2000, Windows NT:  Not supported.

ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE

Object-specific access-denied callback ACE that uses the ACCESS_DENIED_CALLBACK_OBJECT_ACE structure.  Windows 2000, Windows NT:  Not supported.

ACCESS_DENIED_OBJECT_ACE_TYPE

Object-specific access-denied ACE that uses the ACCESS_DENIED_OBJECT_ACE structure.

ACCESS_MAX_MS_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MAX_MS_V2_ACE_TYPE

Same as SYSTEM_ALARM_ACE_TYPE.

ACCESS_MAX_MS_V3_ACE_TYPE

Reserved.

ACCESS_MAX_MS_V4_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MAX_MS_OBJECT_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MIN_MS_ACE_TYPE

Same as ACCESS_ALLOWED_ACE_TYPE.

Windows 2000, Windows NT:  Not supported.

ACCESS_MIN_MS_OBJECT_ACE_TYPE

Same as ACCESS_ALLOWED_OBJECT_ACE_TYPE.

SYSTEM_AUDIT_ACE_TYPE

System-audit ACE that uses the SYSTEM_AUDIT_ACE structure.

SYSTEM_ALARM_ACE_TYPE

Reserved for future use.  System-alarm ACE that uses the SYSTEM_ALARM_ACE structure.

SYSTEM_ALARM_CALLBACK_ACE_TYPE

Reserved for future use.  System-alarm callback ACE that uses the SYSTEM_ALARM_CALLBACK_ACE structure.

SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE

Reserved for future use.  Object-specific system-alarm callback ACE that uses the SYSTEM_ALARM_CALLBACK_OBJECT_ACE structure.

SYSTEM_ALARM_OBJECT_ACE_TYPE

Reserved for future use.  Object-specific system-alarm ACE that uses the SYSTEM_ALARM_OBJECT_ACE structure.

SYSTEM_AUDIT_CALLBACK_ACE_TYPE

System-audit callback ACE that uses the SYSTEM_AUDIT_CALLBACK_ACE structure. Windows 2000, Windows NT:  Not supported.

SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE

Object-specific system-audit callback ACE that uses the SYSTEM_AUDIT_CALLBACK_OBJECT_ACE structure.  Windows 2000, Windows NT:  Not supported.

SYSTEM_AUDIT_OBJECT_ACE_TYPE

Object-specific system-audit ACE that uses the SYSTEM_AUDIT_OBJECT_ACE structure.

 

Table 17

 

AceFlags - Specifies a set of ACE type-specific control flags.  This member can be a combination of the following values:

 

Value

Meaning

CONTAINER_INHERIT_ACE

Child objects that are containers, such as directories, inherit the ACE as an effective ACE.  The inherited ACE is inheritable unless the NO_PROPAGATE_INHERIT_ACE bit flag is also set.

FAILED_ACCESS_ACE_FLAG

Used with system-audit ACEs in a system access control list (SACL) to generate audit messages for failed access attempts.

INHERIT_ONLY_ACE

Indicates an inherit-only ACE, which does not control access to the object to which it is attached.  If this flag is not set, the ACE is an effective ACE which controls access to the object to which it is attached.  Both effective and inherit-only ACEs can be inherited depending on the state of the other inheritance flags.

INHERITED_ACE

Indicates that the ACE was inherited.  The system sets this bit when it propagates an inherited ACE to a child object.

NO_PROPAGATE_INHERIT_ACE

If the ACE is inherited by a child object, the system clears the OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags in the inherited ACE. This prevents the ACE from being inherited by subsequent generations of objects.

OBJECT_INHERIT_ACE

Non container child objects inherit the ACE as an effective ACE.

For child objects that are containers, the ACE is inherited as an inherit-only ACE unless the NO_PROPAGATE_INHERIT_ACE bit flag is also set.

SUCCESSFUL_ACCESS_ACE_FLAG

Used with system-audit ACEs in a SACL to generate audit messages for successful access attempts.

 

Table 18

 

 

AceSize - Specifies the size, in bytes, of the ACE. The ACE_HEADER structure is the first member of the various types of ACE structures, such as ACCESS_ALLOWED_ACE.  System-alarm ACEs are not currently supported.  The AceType member cannot specify the SYSTEM_ALARM_ACE_TYPE or SYSTEM_ALARM_OBJECT_ACE_TYPE values.  Do not use the SYSTEM_ALARM_ACE or SYSTEM_ALARM_OBJECT_ACE structures.

 

TOKEN_GROUPS_AND_PRIVILEGES

 

Item

Description

Structure

TOKEN_GROUPS_AND_PRIVILEGES.

Info

Contains information about the group security identifiers (SIDs) and privileges in an access token.

Definition

typedef struct _TOKEN_GROUPS_AND_PRIVILEGES {

  ULONG SidCount;

  ULONG SidLength;

  PSID_AND_ATTRIBUTES Sids;

  ULONG RestrictedSidCount;

  ULONG RestrictedSidLength;

  PSID_AND_ATTRIBUTES RestrictedSids;

  ULONG PrivilegeCount;

  ULONG PrivilegeLength;

  PLUID_AND_ATTRIBUTES Privileges;

  LUID AuthenticationId;

} TOKEN_GROUPS_AND_PRIVILEGES,  *PTOKEN_GROUPS_AND_PRIVILEGES;

Members

SidCount - Number of SIDs in the access token.

SidLength - Length, in bytes, required to hold all of the user SIDs and the account SID for the group.

Sids - Pointer to an array of SID_AND_ATTRIBUTES structures that contain a set of SIDs and corresponding attributes.  The Attributes members of the SID_AND_ATTRIBUTES structures can have the following values:

  1. SE_GROUP_ENABLED - The SID is enabled for access checks.  When the system performs an access check, it checks for access-allowed and access-denied ACEs that apply to the SID.  A SID without this attribute is ignored during an access check unless the SE_GROUP_USE_FOR_DENY_ONLY attribute is set.

  2. SE_GROUP_ENABLED_BY_DEFAULT - The SID is enabled by default.

  3. SE_GROUP_LOGON_ID - The SID is a logon SID that identifies the logon session associated with an access token.

  4. SE_GROUP_MANDATORY - The SID cannot have the SE_GROUP_ENABLED attribute cleared by a call to the AdjustTokenGroups() function.  However, you can use the CreateRestrictedToken() function to convert a mandatory SID to a deny-only SID.

  5. SE_GROUP_OWNER - The SID identifies a group account for which the user of the token is the owner of the group, or the SID can be assigned as the owner of the token or objects.

  6. SE_GROUP_RESOURCE - The SID identifies a domain-local group.

  7. SE_GROUP_USE_FOR_DENY_ONLY - The SID is a deny-only SID in a restricted token.  When the system performs an access check, it checks for access-denied ACEs that apply to the SID; it ignores access-allowed ACEs for the SID.  If this attribute is set, SE_GROUP_ENABLED is not set, and the SID cannot be re enabled.

 

RestrictedSidCount - Number of restricted SIDs.

RestrictedSidLength - Length, in bytes, required to hold all of the restricted SIDs.

RestrictedSids - Pointer to an array of SID_AND_ATTRIBUTES structures that contain a set of restricted SIDs and corresponding attributes.  The Attributes members of the SID_AND_ATTRIBUTES structures can have the same values as those listed for the preceding Sids member.

PrivilegeCount - Number of privileges.

PrivilegeLength - Length, in bytes, needed to hold the privilege array.

Privileges - Array of privileges.

AuthenticationId - Locally unique identifier (LUID) of the authenticator of the token.

Header file

<windows.h>

Remark

-

 

Table 19

 

TOKEN_PRIVILEGES

 

Item

Description

Structure

TOKEN_PRIVILEGES.

Info

Contains information about a set of privileges for an access token.

Definition

typedef struct _TOKEN_PRIVILEGES {

  DWORD PrivilegeCount;

  LUID_AND_ATTRIBUTES Privileges[ANYSIZE_ARRAY];

} TOKEN_PRIVILEGES,  *PTOKEN_PRIVILEGES;

Members

PrivilegeCount - Specifies the number of entries in the Privileges array.

Privileges - Specifies an array of LUID_AND_ATTRIBUTES structures.  Each structure contains the LUID and attributes of a privilege.  To get the name of the privilege associated with a LUID, call the LookupPrivilegeName() function, passing the address of the LUID as the value of the lpLuid parameter.  The attributes of a privilege can be a combination of the following values:

  1. SE_PRIVILEGE_ENABLED - The privilege is enabled.

  2. SE_PRIVILEGE_ENABLED_BY_DEFAULT - The privilege is enabled by default.

  3. SE_PRIVILEGE_REMOVED - Used to remove a privilege.

  4. SE_PRIVILEGE_USED_FOR_ACCESS - The privilege was used to gain access to an object or service.  This flag is used to identify the relevant privileges in a set passed by a client application that may contain unnecessary privileges.

Header file

<windows.h>

Remark

-

 

Table 20

 

TOKEN_ORIGIN

 

Item

Description

Structure

TOKEN_ORIGIN.

Info

Contains information about the origin of the logon session.  This structure is used by the GetTokenInformation() function.

Definition

typedef struct _TOKEN_ORIGIN {

  LUID OriginatingLogonSession;

} TOKEN_ORIGIN,  *PTOKEN_ORIGIN;

Members

OriginatingLogonSession - Locally unique identifier (LUID) for the logon session.  If the token passed to GetTokenInformation() resulted from a logon using explicit credentials, such as passing name, domain, and password to the LogonUser() function, then this member will contain the ID of the logon session that created it.  If the token resulted from network authentication, such as a call to AcceptSecurityContext, or a call to LogonUser with dwLogonType set to LOGON32_LOGON_NETWORK or LOGON32_LOGON_NETWORK_CLEARTEXT, then this member will be zero.

Header file

<windows.h>

Remark

-

 

Table 25

 

TOKEN_SOURCE

 

Item

Description

Structure

TOKEN_SOURCE.

Info

Identifies the source of an access token.

Definition

typedef struct _TOKEN_SOURCE {

  CHAR SourceName[8];

  LUID SourceIdentifier;

} TOKEN_SOURCE,  *PTOKEN_SOURCE;

Members

SourceName - Specifies an 8-byte character string used to identify the source of an access token. This is used to distinguish between such sources as Session Manager, LAN Manager, and RPC Server.  A string, rather than a constant, is used to identify the source so users and developers can make extensions to the system, such as by adding other networks, which act as the source of access tokens.

SourceIdentifier - Specifies a locally unique identifier (LUID) provided by the source component named by the SourceName member.  This value aids the source component in relating context blocks, such as session-control structures, to the token.  This value is typically, but not necessarily, an LUID.

Header file

<windows.h>

Remark

-

 

Table 26

 

TOKEN_STATISTICS

 

Item

Description

Structure

TOKEN_STATISTICS.

Info

Contains information about an access token.  An application can retrieve this information by calling the GetTokenInformation() function.

Definition

typedef struct _TOKEN_STATISTICS {

  LUID TokenId;

  LUID AuthenticationId;

  LARGE_INTEGER ExpirationTime;

  TOKEN_TYPE TokenType;

  SECURITY_IMPERSONATION_LEVEL ImpersonationLevel;

  DWORD DynamicCharged;

  DWORD DynamicAvailable;

  DWORD GroupCount;

  DWORD PrivilegeCount;

  LUID ModifiedId;

} TOKEN_STATISTICS,  *PTOKEN_STATISTICS;

Members

TokenId - Specifies a locally unique identifier (LUID) that identifies this instance of the token object.

AuthenticationId - Specifies an LUID assigned to the session this token represents.  There can be many tokens representing a single logon session.

ExpirationTime - Specifies the time at which this token expires. Expiration times for access tokens are not currently supported.

TokenType - Specifies a TOKEN_TYPE enumeration type indicating whether the token is a primary or impersonation token.

ImpersonationLevel - Specifies a SECURITY_IMPERSONATION_LEVEL enumeration type indicating the impersonation level of the token.  This member is valid only if the TokenType is TokenImpersonation.

DynamicCharged - Specifies the amount, in bytes, of memory allocated for storing default protection and a primary group identifier.

DynamicAvailable - Specifies the portion of memory allocated for storing default protection and a primary group identifier not already in use.  This value is returned as a count of free bytes.

GroupCount - Specifies the number of supplemental group security identifiers (SIDs) included in the token.

PrivilegeCount - Specifies the number of privileges included in the token.

ModifiedId - Specifies an LUID that changes each time the token is modified.  An application can use this value as a test of whether a security context has changed since it was last used.

Header file

<windows.h>

Remark

-

 

Table 27

 

TOKEN_USER

 

Item

Description

Structure

TOKEN_USER.

Info

Identifies the user associated with an access token.

Definition

typedef struct _TOKEN_USER {

  SID_AND_ATTRIBUTES User;

} TOKEN_USER,  *PTOKEN_USER;

Members

User - Specifies a SID_AND_ATTRIBUTES structure representing the user associated with the access token.  There are currently no attributes defined for user security identifiers (SIDs).

Header file

<windows.h>

Remark

-

 

Table 29

 

TOKEN_CONTROL

 

Item

Description

Structure

TOKEN_CONTROL.

Info

Contains information that identifies an access token.

Definition

typedef struct _TOKEN_CONTROL {

  LUID TokenId;

  LUID AuthenticationId;

  LUID ModifiedId;

  TOKEN_SOURCE TokenSource;

} TOKEN_CONTROL, *PTOKEN_CONTROL;

Members

TokenId - Specifies a locally unique identifier (LUID) identifying this instance of the token object.

AuthenticationId - Specifies an LUID assigned to the session this token represents.  There can be many tokens representing a single logon session.

ModifiedId - Specifies an LUID that changes each time the token is modified.  An application can use this value as a test of whether a security context has changed since it was last used.

TokenSource - Specifies a TOKEN_SOURCE structure identifying the agency that issued the token.  This information is used in audit logging.

Header file

<windows.h>

Remark

-

 

Table 30

 

TOKEN_DEFAULT_DACL

 

Item

Description

Structure

TOKEN_DEFAULT_DACL.

Info

Specifies a DACL.

Definition

typedef struct _TOKEN_DEFAULT_DACL {

  PACL DefaultDacl;

} TOKEN_DEFAULT_DACL,  *PTOKEN_DEFAULT_DACL;

Members

DefaultDacl - Pointer to an ACL structure assigned by default to any objects created by the user.  The user is represented by the access token.

Header file

<windows.h>

Remark

The GetTokenInformation() function retrieves the default DACL for an access token, in the form of a TOKEN_DEFAULT_DACL structure.  This structure is also used with the SetTokenInformation() function to set the default DACL.

 

Table 31

 

TOKEN_GROUPS

 

Item

Description

Structure

TOKEN_GROUPS.

Info

Contains information about the group security identifiers (SIDs) in an access token.

Definition

typedef struct _TOKEN_GROUPS {

  DWORD GroupCount;

  SID_AND_ATTRIBUTES Groups[ANYSIZE_ARRAY];

} TOKEN_GROUPS,  *PTOKEN_GROUPS;

Members

GroupCount - Specifies the number of groups in the access token.

Groups - Specifies an array of SID_AND_ATTRIBUTES structures that contain a set of SIDs and corresponding attributes.  The Attributes members of the SID_AND_ATTRIBUTES structures can have the following values:

  1. SE_GROUP_ENABLED - The SID is enabled for access checks.  When the system performs an access check, it checks for access-allowed and access-denied ACEs that apply to the SID.  A SID without this attribute is ignored during an access check unless the SE_GROUP_USE_FOR_DENY_ONLY attribute is set.

  2. SE_GROUP_ENABLED_BY_DEFAULT - The SID is enabled by default.

  3. SE_GROUP_LOGON_ID - The SID is a logon SID that identifies the logon session associated with an access token.

  4. SE_GROUP_MANDATORY - The SID cannot have the SE_GROUP_ENABLED attribute cleared by a call to the AdjustTokenGroups() function. However, you can use the CreateRestrictedToken() function to convert a mandatory SID to a deny-only SID.

  5. SE_GROUP_OWNER - The SID identifies a group account for which the user of the token is the owner of the group, or the SID can be assigned as the owner of the token or objects.

  6. SE_GROUP_RESOURCE - The SID identifies a domain-local group.

  7. SE_GROUP_USE_FOR_DENY_ONLY - The SID is a deny-only SID in a restricted token.  When the system performs an access check, it checks for access-denied ACEs that apply to the SID; it ignores access-allowed ACEs for the SID.  If this attribute is set, SE_GROUP_ENABLED is not set, and the SID cannot be re enabled.

Header file

<windows.h>

Remark

-

 

Table 32

 

TOKEN_OWNER

 

Item

Description

Structure

TOKEN_OWNER.

Info

Contains the default owner security identifier (SID) that will be applied to newly created objects.

Definition

typedef struct _TOKEN_OWNER {

  PSID Owner;

} TOKEN_OWNER,  *PTOKEN_OWNER;

Members

Owner - Pointer to a SID structure representing a user who will become the owner of any objects created by a process using this access token.  The SID must be one of the user or group SIDs already in the token.

Header file

<windows.h>

Remark

-

 

Table 34

 

TOKEN_PRIMARY_GROUP

 

Item

Description

Structure

TOKEN_PRIMARY_GROUP.

Info

Specifies a group security identifier (SID) for an access token.

Definition

typedef struct _TOKEN_PRIMARY_GROUP {

  PSID PrimaryGroup;

} TOKEN_PRIMARY_GROUP,  *PTOKEN_PRIMARY_GROUP;

Members

PrimaryGroup - Pointer to a SID structure representing a group that will become the primary group of any objects created by a process using this access token.  The SID must be one of the group SIDs already in the token.

Header file

<windows.h>

Remark

-

 

Table 35

 

ACL_REVISION_INFORMATION

 

Item

Description

Structure

ACL_REVISION_INFORMATION.

Info

Contains revision information about an ACL structure.

Definition

typedef struct _ACL_REVISION_INFORMATION {

  DWORD AclRevision;

} ACL_REVISION_INFORMATION;

Members

AclRevision - Specifies a revision number.  The current revision number is ACL_REVISION.

Header file

<windows.h>

Remark

-

 

Table 36

 

ACL_SIZE_INFORMATION

 

Item

Description

Structure

ACL_SIZE_INFORMATION.

Info

Contains information about the size of an ACL structure.

Definition

typedef struct _ACL_SIZE_INFORMATION {

  DWORD AceCount;

  DWORD AclBytesInUse;

  DWORD AclBytesFree;

} ACL_SIZE_INFORMATION;

Members

AceCount - The number of ACEs in the ACL.

AclBytesInUse - The number of bytes in the ACL actually used to store the ACEs and ACL structure.  This may be less than the total number of bytes allocated to the ACL.

AclBytesFree - The number of unused bytes in the ACL.

Header file

<windows.h>

Remark

-

 

Table 37

 

LUID

 

Item

Description

Structure

LUID.

Info

A Locally Unique Identifier (LUID) is a 64-bit value guaranteed to be unique only on the system on which it was generated.  The uniqueness of a LUID is guaranteed only until the system is restarted.

Definition

typedef struct _LUID {

  DWORD LowPart;

  LONG HighPart;

} LUID,  *PLUID;

Member

LowPart - Low order bits.

HighPart - High order bits.

Header file

<windows.h>

Remark

-

 

Table 38

 

LUID_AND_ATTRIBUTES

 

Item

Description

Structure

LUID_AND_ATTRIBUTES.

Info

Represents a locally unique identifier (LUID) and its attributes.

Definition

typedef struct _LUID_AND_ATTRIBUTES {

  LUID Luid;

  DWORD Attributes;

} LUID_AND_ATTRIBUTES,  *PLUID_AND_ATTRIBUTES;

Members

Luid - Specifies an LUID value.

Attributes - Specifies attributes of the LUID.  This value contains up to 32 one-bit flags.  Its meaning is dependent on the definition and use of the LUID.

Header file

<windows.h>

Remark

An LUID_AND_ATTRIBUTES structure can represent an LUID whose attributes change frequently, such as when the LUID is used to represent privileges in the PRIVILEGE_SET structure.  Privileges are represented by LUIDs and have attributes indicating whether they are currently enabled or disabled.

 

Table 39

 

PRIVILEGE_SET

 

Item

Description

Structure

PRIVILEGE_SET.

Info

Specifies a set of privileges.  It is also used to indicate which, if any, privileges are held by a user or group requesting access to an object.

Definition

typedef struct _PRIVILEGE_SET {

  DWORD PrivilegeCount;

  DWORD Control;

  LUID_AND_ATTRIBUTES Privilege[ANYSIZE_ARRAY];

} PRIVILEGE_SET,  *PPRIVILEGE_SET;

Members

PrivilegeCount - Specifies the number of privileges in the privilege set.

Control - Specifies a control flag related to the privileges.  The PRIVILEGE_SET_ALL_NECESSARY control flag is currently defined. It indicates that all of the specified privileges must be held by the process requesting access.  If this flag is not set, the presence of any privileges in the user's access token grants the access.

Privilege - Specifies an array of LUID_AND_ATTRIBUTES structures describing the set's privileges.  The following attributes are defined for privileges:

  1. SE_PRIVILEGE_ENABLED_BY_DEFAULT - The privilege is enabled by default.

  2. SE_PRIVILEGE_ENABLED - The privilege is enabled.

  3. SE_PRIVILEGE_USED_FOR_ACCESS - The privilege was used to gain access to an object or service.  This flag is used to identify the relevant privileges in a set passed by a client application that may contain unnecessary privileges.

Header file

<windows.h>

Remark

A privilege is used to control access to an object or service more strictly than is typical with discretionary access control.  A system manager uses privileges to control which users are able to manipulate system resources.  An application uses privileges when it changes a system-wide resource, such as when it changes the system time or shuts down the system.

 

Table 40

 

SECURITY_ATTRIBUTES

 

Item

Description

Structure

SECURITY_ATTRIBUTES.

Info

Contains the security descriptor for an object and specifies whether the handle retrieved by specifying this structure is inheritable.  This structure provides security settings for objects created by various functions, such as CreateFile(), CreatePipe(), CreateProcess(), RegCreateKeyEx(), or RegSaveKeyEx().

Definition

typedef struct _SECURITY_ATTRIBUTES {

  DWORD nLength;

  LPVOID lpSecurityDescriptor;

  BOOL bInheritHandle;

} SECURITY_ATTRIBUTES,  *PSECURITY_ATTRIBUTES;

Members

nLength - The size, in bytes, of this structure.  Set this value to the size of the SECURITY_ATTRIBUTES structure.

lpSecurityDescriptor - A pointer to a security descriptor for the object that controls the sharing of it.  If NULL is specified for this member, the object is assigned the default security descriptor of the calling process.  This is not the same as granting access to everyone by assigning a NULL DACL. The default security descriptor is based on the default DACL of the access token belonging to the calling process.  By default, the default DACL in the access token of a process allows access only to the user represented by the access token.  If other users must access the object, you can either create a security descriptor with the appropriate access, or add ACEs to the DACL that grants access to a group of users.

bInheritHandle - A Boolean value that specifies whether the returned handle is inherited when a new process is created.  If this member is TRUE, the new process inherits the handle.

Header file

<windows.h>

Remark

-

 

Table 42

 

GENERIC_MAPPING

 

Item

Description

Structure

GENERIC_MAPPING.

Info

Defines the mapping of generic access rights to specific and standard access rights for an object.  When a client application requests generic access to an object, that request is mapped to the access rights defined in this structure.

Definition

typedef struct _GENERIC_MAPPING {

  ACCESS_MASK GenericRead;

  ACCESS_MASK GenericWrite;

  ACCESS_MASK GenericExecute;

  ACCESS_MASK GenericAll;

} GENERIC_MAPPING;

Members

GenericRead - Specifies an access mask defining read access to an object.

GenericWrite - Specifies an access mask defining write access to an object.

GenericExecute - Specifies an access mask defining execute access to an object.

GenericAll - Specifies an access mask defining all possible types of access to an object.

Header file

<windows.h>

Remark

-

 

Table 43

 

SYSTEM_AUDIT_OBJECT_ACE

 

Item

Description

Structure

SYSTEM_AUDIT_OBJECT_ACE.

Info

Defines an ACE for a SACL.  The ACE can audit access to an object or sub objects such as property sets or properties.  The ACE contains a set of access rights, a GUID that identifies the type of object or sub object, and a SID that identifies the trustee for whom the system will audit access.  The ACE also contains a GUID and a set of flags that control inheritance of the ACE by child objects.

Definition

typedef struct _SYSTEM_AUDIT_OBJECT_ACE {

  ACE_HEADER Header;

  ACCESS_MASK Mask;

  DWORD Flags;

  GUID ObjectType;

  GUID InheritedObjectType;

  DWORD SidStart;

} SYSTEM_AUDIT_OBJECT_ACE, *PSYSTEM_ALARM_OBJECT_ACE;

Members

Header - An ACE_HEADER structure that specifies the size and type of ACE.  It contains flags that control inheritance of the ACE by child objects.  The structure also contains flags that indicate whether the ACE audits successful access attempts, failed access attempts, or both.  The AceType member of the ACE_HEADER structure should be set to SYSTEM_AUDIT_OBJECT_ACE_TYPE, and the AceSize member should be set to the total number of bytes allocated for the SYSTEM_AUDIT_OBJECT_ACE structure.

 

Mask - An ACCESS_MASK that specifies the access rights the system will audit for access attempts by the trustee.

Flags - A set of bit flags that indicate whether the ObjectType and InheritedObjectType members contain GUIDs.  This member can be a combination of the following values.  Set all undefined bits to zero.

  1. ACE_OBJECT_TYPE_PRESENT - The ObjectType member contains a GUID.

  2. ACE_INHERITED_OBJECT_TYPE_PRESENT - The InheritedObjectType member contains a GUID.

 

ObjectType - A GUID structure that identifies a property set, property, extended right, or type of child object.

This member is valid only if the ACE_OBJECT_TYPE_PRESENT bit is set in the Flags member. Otherwise, ObjectType is ignored.  The purpose of this GUID depends on the access rights specified in the Mask member.  This member can be one of the following values:

  1. ADS_RIGHT_DS_READ_PROP and/or ADS_RIGHT_DS_WRITE_PROP - The ObjectType GUID identifies a property set or property of the object.  The ACE controls auditing of the trustee's attempts to read or write the property or property set.

  2. ADS_RIGHT_DS_CONTROL_ACCESS - The ObjectType GUID identifies an extended access right.

  3. ADS_RIGHT_DS_CREATE_CHILD - The ObjectType GUID identifies a type of child object. The ACE controls auditing of the trustee's attempts to create this type of child object.

  4. ADS_RIGHT_DS_SELF - The ObjectType GUID identifies a validated write.

 

InheritedObjectType - A GUID structure that identifies the type of child object that can inherit the ACE.

This member is valid only if the ACE_INHERITED_OBJECT_TYPE_PRESENT bit is set in the Flags member.  If that bit is not set, InheritedObjectType is ignored and all types of child objects can inherit the ACE.  In either case, inheritance is also controlled by the inheritance flags in the ACE_HEADER, as well as by any protection against inheritance placed on the child objects.

SidStart - Specifies the first DWORD of a SID that identifies the trustee for whom the access attempts are audited.  The remaining bytes of the SID are stored in contiguous memory after the SidStart member.  This SID can be appended with application data.

Header file

<windows.h>

Remark

-

 

Table 44

 

If neither the ObjectType nor InheritedObjectType GUID is specified, the SYSTEM_AUDIT_OBJECT_ACE structure has the same semantics as the SYSTEM_AUDIT_ACE structure. In that case, use the SYSTEM_AUDIT_ACE structure because it is smaller and more efficient.  An ACL that contains an SYSTEM_AUDIT_OBJECT_ACE must specify the ACL_REVISION_DS revision number in its ACE_HEADER structure.  When a SYSTEM_AUDIT_OBJECT_ACE structure is created, sufficient memory must be allocated to accommodate the GUID structures in the ObjectType and InheritedObjectType members, if one or both of them exists, as well as to accommodate the complete SID of the trustee in the SidStart member and the contiguous memory that follows it.

 

SYSTEM_AUDIT_ACE

 

Item

Description

Structure

SYSTEM_AUDIT_ACE.

Info

Defines an ACE for the SACL that specifies what types of access cause system-level notifications.  A system-audit ACE causes an audit message to be logged when a specified trustee attempts to gain access to an object.  The trustee is identified by a SID.

Definition

typedef struct _SYSTEM_AUDIT_ACE {

  ACE_HEADER Header;

  ACCESS_MASK Mask;

  DWORD SidStart;

} SYSTEM_AUDIT_ACE;

Members

Header - ACE_HEADER structure that specifies the size and type of ACE.  It also contains flags that control inheritance of the ACE by child objects.  The AceType member of the ACE_HEADER structure should be set to SYSTEM_AUDIT_ACE_TYPE, and the AceSize member should be set to the total number of bytes allocated for the SYSTEM_AUDIT_ACE structure.

Mask - Specifies an ACCESS_MASK structure that gives the access rights that cause audit messages to be generated.  The SUCCESSFUL_ACCESS_ACE_FLAG and FAILED_ACCESS_ACE_FLAG flags in the AceFlags member of the ACE_HEADER structure indicate whether messages are generated for successful access attempts, unsuccessful access attempts, or both.

SidStart - The first DWORD of a trustee's SID.  The remaining bytes of the SID are stored in contiguous memory after the SidStart member.  This SID can be appended with application data.  An access attempt of a kind specified by the Mask member by any trustee whose SID matches the SidStart member causes the system to generate an audit message.  If an application does not specify a SID for this member, audit messages are generated for the specified access rights for all trustees.

Header file

<windows.h>

Remark

-

 

Table 45

 

Audit messages are stored in an event log that can be manipulated by using the Windows API event-logging functions or by using the Event Viewer (Eventvwr.exe).  ACE structures should be aligned on double word boundaries.  All Windows memory-management functions return double word-aligned handles to memory.  When a SYSTEM_AUDIT_ACE structure is created, sufficient memory must be allocated to accommodate the complete SID of the trustee in the SidStart member and the contiguous memory that follows it.

 

ACE_HEADER

 

Item

Description

Structure

ACE_HEADER.

Info

Defines the type and size of an ACE.

Definition

typedef struct _ACE_HEADER {

  BYTE AceType;

  BYTE AceFlags;

  WORD AceSize;

} ACE_HEADER,  *PACE_HEADER;

Members

See below.

Header file

<windows.h>

Remark

-

 

Table 46

 

AceType - Specifies the ACE type.  This member can be one of the following values.

 

Value

Meaning

ACCESS_ALLOWED_ACE_TYPE

Access-allowed ACE that uses the ACCESS_ALLOWED_ACE structure.

ACCESS_ALLOWED_CALLBACK_ACE_TYPE

Access-allowed callback ACE that uses the ACCESS_ALLOWED_CALLBACK_ACE structure.

Windows 2000:  Not supported.

ACCESS_ALLOWED_CALLBACK_OBJECT_ACE_TYPE

Object-specific access-allowed callback ACE that uses the ACCESS_ALLOWED_CALLBACK_OBJECT_ACE structure.  Windows 2000:  Not supported.

ACCESS_ALLOWED_COMPOUND_ACE_TYPE

Reserved.

ACCESS_ALLOWED_OBJECT_ACE_TYPE

Object-specific access-allowed ACE that uses the ACCESS_ALLOWED_OBJECT_ACE structure.

Windows NT:  Not supported.

ACCESS_DENIED_ACE_TYPE

Access-denied ACE that uses the ACCESS_DENIED_ACE structure.

ACCESS_DENIED_CALLBACK_ACE_TYPE

Access-denied callback ACE that uses the ACCESS_DENIED_CALLBACK_ACE structure.  Windows 2000:  Not supported.

ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE

Object-specific access-denied callback ACE that uses the ACCESS_DENIED_CALLBACK_OBJECT_ACE structure.  Windows 2000:  Not supported.

ACCESS_DENIED_OBJECT_ACE_TYPE

Object-specific access-denied ACE that uses the ACCESS_DENIED_OBJECT_ACE structure.

ACCESS_MAX_MS_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MAX_MS_V2_ACE_TYPE

Same as SYSTEM_ALARM_ACE_TYPE.

ACCESS_MAX_MS_V3_ACE_TYPE

Reserved.

ACCESS_MAX_MS_V4_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MAX_MS_OBJECT_ACE_TYPE

Same as SYSTEM_ALARM_OBJECT_ACE_TYPE.

ACCESS_MIN_MS_ACE_TYPE

Same as ACCESS_ALLOWED_ACE_TYPE.  Windows 2000:  Not supported.

ACCESS_MIN_MS_OBJECT_ACE_TYPE

Same as ACCESS_ALLOWED_OBJECT_ACE_TYPE.

Windows NT:  Not supported.

SYSTEM_AUDIT_ACE_TYPE

System-audit ACE that uses the SYSTEM_AUDIT_ACE structure.

SYSTEM_ALARM_ACE_TYPE

Reserved for future use.  System-alarm ACE that uses the SYSTEM_ALARM_ACE structure.

SYSTEM_ALARM_CALLBACK_ACE_TYPE

Reserved for future use.  System-alarm callback ACE that uses the SYSTEM_ALARM_CALLBACK_ACE structure.

SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE

Reserved for future use.  Object-specific system-alarm callback ACE that uses the SYSTEM_ALARM_CALLBACK_OBJECT_ACE structure.

SYSTEM_ALARM_OBJECT_ACE_TYPE

Reserved for future use.  Object-specific system-alarm ACE that uses the SYSTEM_ALARM_OBJECT_ACE structure.

SYSTEM_AUDIT_CALLBACK_ACE_TYPE

System-audit callback ACE that uses the SYSTEM_AUDIT_CALLBACK_ACE structure.

Windows 2000:  Not supported.

SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE

Object-specific system-audit callback ACE that uses the SYSTEM_AUDIT_CALLBACK_OBJECT_ACE structure.  Windows 2000:  Not supported.

SYSTEM_AUDIT_OBJECT_ACE_TYPE

Object-specific system-audit ACE that uses the SYSTEM_AUDIT_OBJECT_ACE structure.

 

Table 47

 

AceFlags - Specifies a set of ACE type-specific control flags.  This member can be a combination of the following values:

 

Value

Meaning

CONTAINER_INHERIT_ACE

Child objects that are containers, such as directories, inherit the ACE as an effective ACE.  The inherited ACE is inheritable unless the NO_PROPAGATE_INHERIT_ACE bit flag is also set.

FAILED_ACCESS_ACE_FLAG

Used with system-audit ACEs in a system access control list (SACL) to generate audit messages for failed access attempts.

INHERIT_ONLY_ACE

Indicates an inherit-only ACE, which does not control access to the object to which it is attached.  If this flag is not set, the ACE is an effective ACE which controls access to the object to which it is attached.  Both effective and inherit-only ACEs can be inherited depending on the state of the other inheritance flags.

INHERITED_ACE

Indicates that the ACE was inherited.  The system sets this bit when it propagates an inherited ACE to a child object.

NO_PROPAGATE_INHERIT_ACE

If the ACE is inherited by a child object, the system clears the OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE flags in the inherited ACE.  This prevents the ACE from being inherited by subsequent generations of objects.

OBJECT_INHERIT_ACE

Non container child objects inherit the ACE as an effective ACE.  For child objects that are containers, the ACE is inherited as an inherit-only ACE unless the NO_PROPAGATE_INHERIT_ACE bit flag is also set.

SUCCESSFUL_ACCESS_ACE_FLAG

Used with system-audit ACEs in a SACL to generate audit messages for successful access attempts.

 

Table 48

 

AceSize - Specifies the size, in bytes, of the ACE.

 

The ACE_HEADER structure is the first member of the various types of ACE structures, such as ACCESS_ALLOWED_ACE.  System-alarm ACEs are not currently supported.  The AceType member cannot specify the SYSTEM_ALARM_ACE_TYPE or SYSTEM_ALARM_OBJECT_ACE_TYPE values.  Do not use the SYSTEM_ALARM_ACE or SYSTEM_ALARM_OBJECT_ACE structures.

 

ACL

 

Item

Description

Structure

ACL.

Info

The ACL structure is the header of an ACL.  A complete ACL consists of an ACL structure followed by an ordered list of zero or more ACEs.

Definition

typedef struct _ACL {

  BYTE AclRevision;

  BYTE Sbz1;

  WORD AclSize;

  WORD AceCount;

  WORD Sbz2;

} ACL, *PACL;

Members

AclRevision - Specifies the revision level of the ACL.  This value should be ACL_REVISION, unless the ACL contains an object-specific ACE, in which case this value must be ACL_REVISION_DS.  All ACEs in an ACL must be at the same revision level.  Windows NT:  This value must be ACL_REVISION.

Sbz1 - Specifies a zero byte of padding that aligns the AclRevision member on a 16-bit boundary.

AclSize - Specifies the size, in bytes, of the ACL.  This value includes both the ACL structure and all the ACEs.

AceCount - Specifies the number of ACEs stored in the ACL.

Sbz2 - Specifies two zero-bytes of padding that align the ACL structure on a 32-bit boundary.

Header file

<windows.h>

Remark

-

 

Table 49

 

An ACL includes a sequential list of zero or more ACEs.  The individual ACEs in an ACL are numbered from 0 to n, where n+1 is the number of ACEs in the ACL.  When editing an ACL, an application refers to an ACE within the ACL by the ACE's index.  As you know, there are two types of ACL:

  1. Discretionary (DACL) and

  2. System (SACL).

 

A DACL is controlled by the owner of an object or anyone granted WRITE_DAC access to the object.  It specifies the access particular users and groups can have to an object.  For example, the owner of a file can use a DACL to control which users and groups can and cannot have access to the file.  An object can also have system-level security information associated with it, in the form of a SACL controlled by a system administrator.  A SACL allows the system administrator to audit any attempts to gain access to an object.  A fourth ACE structure, SYSTEM_ALARM_ACE, is not currently supported.  The ACL structure is to be treated as though it was opaque and applications are not to attempt to work with its members directly.  Applications can use the related functions to create and manipulate ACLs.  Each ACL and ACE structure begins on a double word boundary.  The maximum size for an ACL, including its ACEs, is 64 KB.

 

--------------Structure, enumeration, macro and type-------------

 

 

Further reading and digging:

 

  1. Check the best selling C, C++ and Windows books at Amazon.com.

  2. Microsoft Visual C++.

  3. MSDN library.

  4. Other related C topics: Function, Array, Pointer, String and Structure, enum, typedef.

  5. Notation used in MSDN is Hungarian Notation instead of CamelCase and is discussed in C/C++ Notation.

  6. Windows data type information is in Windows Data Types.

 

 

 

 

 

 

| Previous | Main | Next | Site Index | Download | Disclaimer | Privacy |