Understanding the Windows Security API

The Win32 API contains a set of functions that help you perform various security tasks. Each set of functions addresses a specific area, such as a caller access token or an access control list (the SACL or DACL). This section of the chapter provides a quick overview of the most important functions. You can find a complete list of authorization functions at http://msdn.microsoft.com/library/en-us/security/security/authorization_functions.asp.

The user (or caller) access token is a key to a resource. When a user access token appears in the list of access granted tokens for a particular resource, the caller can access that resource. Table 14.1 contains an overview of the most common API functions that you’ll normally use to change the user’s access token. I used features that you commonly need, but can’t access from the .NET Framework, as a criterion. For example, you can’t easily determine whether the system is auditing the actions of a caller without using the GetAuditedPermissionsFromAcl() function.

Note

The entries in the Function Name column in Tables 14.1, 14.2, 14.3 and 14.4 are single function names, even though the name may appear on more than one line. The use of multiple lines helps make the function name fit within the confines of the book. See the example source code in Chapters 14 and 15 for examples of the full function names in use.

Table 14.1: Common User Access Token Function Overview

Function Name	Description
AdjustTokenGroups	Allows you to adjust one or more group flags that control group usage within the access token. For example, you can use this function to replace the group’s owner.
AdjustTokenPrivileges	Allows you to adjust one or more privileges within the access token. This function enables or disables an existing privilege; you can’t add or delete privileges from the access token.
BuildExplicitAccessWithName	Creates an EXPLICIT_ACCESS data structure for the named trustee. This data structure defines the trustee’s ACL information. Use this data structure with API functions like SetEntriesInAcl to define a trustee’s access level to objects. The EXPLICIT_ACCESS data structure can affect either the SACL or DACL depending on the access mode you set for it.
BuildTrusteeWithName	Creates a TRUSTEE data structure used to identify a specific trustee. You supply a trustee name and Windows fills the other data structure elements with default values. You’ll need to modify the data structure before using it.
BuildTrusteeWithSid	Creates a TRUSTEE data structure that relies on a SID, rather than a trustee name. Windows modifies the default data structure values appropriately.
CheckTokenMembership	Determines whether a SID appears within an access token. This can help you to determine if a user or process belongs to a particular group.
GetAuditedPermissionsFromAc	Returns a list of ACL entries that result in an audit log entry for the specified trustee. This includes ACL entries that affect the trustee as well as groups to which the trustee belongs. You get a complete list of all audit-generating access events, not just those associated with the trustee. Windows returns the audited access in an ACCESS_MASK data structure.
GetEffectiveRightsFromAc	Returns a list of ACL entries that list the effective rights for the specified trustee. Windows returns the effective rights in an ACCESS_MASK data structure.
GetExplicitEntriesFromAc	Returns an array of EXPLICIT_ACCESS data structures that define the level of access each ACE within an ACL grants the trustee. The data structure provides information like the access mode, access rights, and inheritance setting for each ACE.
GetTokenInformation	Returns a data structure containing complete information about the access token. This includes the token’s user, groups that appear within the token, the owner of the token, the impersonation level, and statistics associated with the token.
GetTrusteeName	Returns the name associated with a name trustee. If the TRUSTEE data structure that you provide is for a SID or object, Windows returns a NULL value.
GetTrusteeType	Returns a constant from one of the TRUSTEE_TYPE enumeration values for a trustee. In most cases, the constants indicate whether the trustee is a user, group, domain, or alias. There are also values to show deleted or invalid trustees.
IsTokenRestricted	Detects whether the access token contains one or more restricting SIDs.
LookupPrivilegeDisplayName	Converts a privilege name listed in WINNT.H to human readable form. For example, SE_REMOTE_SHUTDOWN_NAME might convert to “Force shutdown from a remote system.”
LookupPrivilegeName	Allows you to convert a privilege name specified by a LUID to one of the constant forms listed in WINNT.H.
OpenProcessToken	Opens a token associated with a process (application). Like a file, you need to specify level of access to the token. For example, the TOKEN_ALL_ACCESS constant gives you complete access to the token.
OpenThreadToken	Opens a token that’s associated with a thread within an application. As with a process token, you need to request a specific level of access when making the request.
SetEntriesInAc	Creates a new ACL by merging new access control or audit control information into an existing ACL. You can use this function to create an entirely new ACL using the ACL creation function, BuildExplicitAccessWithName.

In general, you can obtain access to user information without using a SID. However, you do need SIDs to perform useful work. For example, certain Windows objects have static SIDs that you can use to access their security settings. (See the list of well-known SIDs at http://msdn.microsoft.com/library/en-us/security/security/well_known_sids.asp.) Active Directory also relies on SIDs for a number of tasks (see the example in the “Working Directly with the Domain Controller” section of Chapter 12 to see how to work with Active Directory using PInvoke). Table 14.2 contains a list of the most common SID-related functions.

Table 14.2: Common SID-Related Function Overview

Function Name	Description
AllocateAndInitializeSid	Creates and initializes a SID with up to eight subauthorities.
ConvertSidToStringSid	Converts a SID to a string in human readable format. This format consists of values in the form S-R-I-SA, where S designates the string as a SID, R is the revision level, I is the identifier authority value, and SA is one or more sub-authority values. Note the dashes between SID values are always part of the SID string.
ConvertStringSidToSid	Converts a specially formatted string into a SID.
FreeSid	Deallocates the memory used by a SID previously created using the AllocateAndInitializeSid function.
GetSidIdentifierAuthority	Returns a pointer to a SID_IDENTIFIER_AUTHORITY data structure that contains an array of six bytes that specify the SID’s top-level authority. Predefined authorities include NULL (0), local (1), world (2), creator (3), and Windows NT/Windows 2000 (5).
InitializeSid	Sets the identifier authority of a SID structure to a known value using a SID_IDENTIFIER_AUTHORITY data structure. Sub-authority values aren’t set using this function. Use the AllocateAndInitializeSid function to initialize a SID completely.
IsValidSid	Determines the validity of a SID structure’s contents. This function checks the revision number and ensures that the number of sub-authorities doesn’t exceed the maximum value.
LookupAccountName	Retrieves the SID (and accompanying data) for a specific account. You must supply an account and system name.
LookupAccountSid	Retrieves the name and machine associated with a given SID. It also returns the name of the SID’s first domain.

Once Windows determines a caller’s rights, it must match those rights to the access requirements of the system resource. This means working with security descriptors. A security descriptor is a lock on the object or other system resource. The key (access token) fits the lock or it doesn’t. Windows grants or denies access when the key fits the lock. Table 14.3 is an overview of the security descriptor API functions.

Table 14.3: Security Descriptor Function Overview

Function Name	Description
ConvertSecurityDescriptorToStringSecurityDescriptor	Converts a security descriptor to string format. Flags determine the level of information returned in the string. A complete string contains the owner SID, the group SID, a DACL flag list using coded letters, a SACL flag list using coded letters, and a series of ACE entries.
ConvertStringSecurityDescriptorToSecurityDescriptor	Converts a specially formatted string into a security descriptor.
GetNamedSecurityInfo	Returns the security descriptor for the named object provided as input. Flags determine what kind of information to retrieve.
GetSecurityDescriptorContro	Returns the security descriptor control information and revision number for the security descriptor structure provided as input.
GetSecurityInfo	Returns the security descriptor for an object that specified using an object handle. Windows 2000 provides flags that determine which security descriptor entries to retrieve.

Note

The entries in the Function Name column are single function names, even though the name may appear on more than one line. The use of multiple lines helps make the function name fit within the confines of the book. See the example source code in Chapters 14 and 15 for examples of the full function names in use.

By now, you should have some idea of how to work within the security portion of the Win32 API. The divisions I set up within the tables are artificial; they’re for description purposes to make the functions easier to comprehend and use. In a real world application, you’ll combine elements of all three tables to create a complete security picture.