The security functions are one of the more complex areas of Windows NT programming, particularly due to the nonobject-orientedness of the implementation. Just creating one of the needed structures is usually a multiple-step process. However, security is an important area, and it should not be implemented less often simply because it’s more trouble to do so.
NOTE
Remember, only a few of the security API functions are fully or partially supported under Windows 98. Although your applications can call one of these functions while running under Windows 98, most likely that function will fail.
A good strategy for dealing with these security functions is to learn how they work, then either cut and paste from existing working code, or wrap up the relative complexity in a tidy object wrapper. You may find that writing an object wrapper for these functions is much easier than trying to handle allocating and deallocating, initializing, recursing, changing, converting back and forth, and updating these structures.
Tables 20.2 through 20.13 list the security functions by categories:
| Access token functions | Access-checking functions |
| Impersonation functions | Privileges functions |
| SD functions | Window station functions |
| SID functions | Local Service Authority functions |
| ACL functions | Security information functions |
| ACE functions | Auditing functions |
TIP
For information about each function’s prototype (parameters), see the online help included with your compiler. The online help provides a comprehensive, alphabetized list of all these functions (however, they are not grouped in categories, as in this chapter). Click on a function to see its prototypes.
Table 20.2: Access Token Functions
| Function | Description |
| AdjustTokenGroups | Adjusts the groups in an access token. |
| AdjustTokenPrivileges | Adjusts privileges for an access token. |
| DuplicateToken | Creates a new access token identical to one supplied. |
| GetTokenInformation | Returns user, group, privileges, and other information about a token. |
| SetThreadToken | Assigns an impersonation token to a given thread. |
| SetTokenInformation | Modifies user, group, privileges, or other information within a given access token. |
| OpenProcessToken | Retrieves the access token for a given process. |
| OpenThreadToken | Retrieves the access token for a given thread |
Table 20.3: Impersonation Functions
| Function | Description |
| CreateProcessAsUser | Identical to CreateProcess, but creates the process for a given access token. |
| DdeImpersonateClient | Allows a DDE server to impersonate a DDE client application, to make system accesses using the client’s security. |
| ImpersonateLoggedOnUser | Lets a calling thread impersonate a given user (takes an access token). |
| ImpersonateNamedPipeClient | Allows the server end of a named pipe to impersonate the pipe client. |
| ImpersonateSelf | Returns an access token impersonating that of the calling process (often used for changing access at a thread level). |
| LogonUser | Allows a server application to acquire an access token for a given user, to use in impersonated access. |
| RevertToSelf | Terminates the impersonation of a client application. |
NOTE
LogonUser isn’t included in the online alphabetical list of security functions, but I think it belongs here. You can frequently use it in your server applications to ensure that requests you’re fulfilling on the requesting user’s behalf match the security settings assigned to that user.
Table 20.4: Security Descriptor (SD) Functions
| Function | Description |
| MakeAbsoluteSD | Creates an SD in absolute format, given one in relative format. |
| MakeSelfRelativeSD | Creates a SD in self-relative format, given one in absoluteformat. |
| InitializeSecurityDescriptor | Initializes a new SD for use. This defaults to no rights granted of any kind. |
| IsValidSecurityDescriptor | Validates an SD by checking the revision level of each part of the SD. |
| GetSecurityDescriptorControl | Retrieves an SD’s control and revision information. |
| GetSecurityDescriptorLength | Returns the size in bytes for a given SD. |
| GetSecurityDescriptorDacl | Returns a pointer to the DACL for a given SD. |
| GetSecurityDescriptorGroup | Returns a pointer to the primary group SID for a given SD. |
| GetSecurityDescriptorOwner | Returns a pointer to the owner SID for a given SD. |
| GetSecurityDescriptorSacl | Returns a pointer to the SACL for a given SD. |
| SetSecurityDescriptorDacl | Updates a given SD’s DACL with new settings. |
| SetSecurityDescriptorGroup | Updates a given SD’s group SID with new settings. |
| SetSecurityDescriptorOwner | Updates a given SD’s owner SID with new settings. |
| SetSecurityDescriptorSacl | Updates a given SD’s SACL with new settings. |
Table 20.5: Security Identifier (SID) Functions
| Function | Description |
| AllocateAndInitializeSid | Allocates and initializes an SID with up to eight subauthorities (groups or users). |
| AllocateLocallyUniqueId | Allocates a locally unique identifier. |
| InitializeSid | Initializes an SID structure with given number of subauthorities. |
| CopySid | Returns copy of a SID to a buffer. |
| EqualSid | Boolean test of two SIDs’ prefix values for equality. |
| FreeSid | Boolean test of two SIDs’ exact equality. |
| GetSidIdentifierAuthority | Returns a pointer to a SID’s top-level authority (in SID_IDENTIFIER_AUTHORITY). |
| GetSidLengthRequired | Returns the length needed in bytes, to store an SID with a given number of subauthorities. |
| GetSidSubAuthority | Returns a pointer to the nth subauthority for a given SID. |
| GetSidSubAuthorityCount | Returns the number of subauthorities in a given SID. |
| GetLengthSid | Returns the length, in bytes, of a given SID. |
| IsValidSid | Validates a given SID by verifying that the revision number is within a known range and that the number of subauthorities is below the maximum. |
| LookupAccountSid | Returns the account name and first domain found for a given SID. |
NOTE
With SIDs, you can allocate and initialize using a single function call. As with SDs, a newly allocated SID needs to be initialized before you can use it.
Table 20.6: Access Control List (ACL, DACL, and SACL) Functions
| Function | Description |
| InitializeAcl | Creates a new ACL structure. |
| GetAclInformation | Retrieves information (such as the revision number, size, and ACE count) for a given ACL. |
| IsValidAcl | Validates a given ACL by checking that its version number is correct and that the number of ACEs matches the ACE count. |
| SetAclInformation | Sets information about an ACL. |
Table 20.7: Access Control Entry (ACE) Functions
| Function | Description |
| AddAce | Adds one or more ACEs to a given ACL, at specified index position. |
| AddAccessAllowedAce | Adds an access-allowed ACE to an ACL, thereby granting access for a particular SID. |
| AddAccessDeniedAce | Adds an access-denied ACE to an ACL, thereby denying access for a particular SID. |
| AddAuditAccessAce | Adds a system-audit ACE to a SACL. |
| DeleteAce | Deletes the nth ACE from a given ACL. |
| FindFirstFreeAce | Returns a pointer to the first free position in an ACL. |
| GetAce | Returns a pointer to the nth ACE for a given ACL. |
WARNING
When calling AddAce or DeleteAce, you must supply an index parameter—the ordering of ACEs in an ACL matters.
Table 20.8: Access-Checking Functions
| Function | Description |
| AccessCheck | Used by a server application to check whether a client has access to an object. |
| AccessCheckAndAuditAlarm | Performs AccessCheck and generates corresponding audit messages. |
| AreAllAccessesGranted | Compares granted with desired rights to see whether all specified access rights have been granted. |
| AreAnyAccessesGranted | Compares granted with desired rights to see whether any specified access rights have been granted. |
| PrivilegeCheck | Tests whether the given access token contains the desired privilege(s). |
| PrivilegedServiceAuditAlarm | Does PrivilegeCheck and generates corresponding audit messages. |
| MapGenericMask | Maps generic access rights to specific and standard access rights. |
WARNING
Keep in mind that overhead (extra time) attaches to each object access while auditing of that object is enabled. How much overhead this incurs depends primarily on how often you will need to access the object. For infrequent access, the auditing overhead isn’t a problem, but when you’re performing very frequent operations on an object, the overhead required for auditing can noticeably impact performance. The best approach is to test your application with and without auditing enabled to ensure that with the auditing overhead, performance is still within an acceptable range.
Table 20.9: Privileges Functions
| Function | Description |
| MapGenericMask | Maps generic access rights of a given mask to specific and standard access rights. |
| PrivilegeCheck | Tests whether a given access token has the specified privilege(s). |
| LookupPrivilegeDisplayName | Retrieves the displayable name associated with a particular privilege. |
| LookupPrivilegeName | Returns the privilege name associated with the given local unique identifier (LUID). |
| LookupPrivilegeValue | Returns the LUID associated with a given privilege on a given system. |
| ObjectPrivilegeAuditAlarm | Generates audit messages when the given user (access token) attempts to perform privileged operations on a particular object. |
| PrivilegedServiceAuditAlarm | Generates audit messages when the given user (access token) attempts to perform privileged operations. |
Table 20.10: Window Station Functions
| Function | Description |
| GetProcessWindowStation | Returns a handle to the window station associated with the calling process. |
| SetProcessWindowStation | Assigns a given window station to the calling process. |
| InitLsaString | Creates a LSA_UNICODE_STRING for the given privilege name. |
| LsaOpenPolicy | Opens (or creates) a given policy on target machine. |
| LsaLookupNames | Returns an account name (and SID) for given access token. |
| LsaRemoveAccountRights | Revokes privileges for the specified user(s). |
| LsaAddAccountRights | Grants privileges to the specified user(s). |
| LsaClose | Closes a given policy. |
| LsaEnumerateAccountRights | Enumerates rights or privileges that are currently granted to a given account. |
| LsaEnumerateAccountsWithUserRight | Enumerates all accounts on a given system that have been granted a given privilege. |
Table 20.12: Security Information Functions
| Function | Description |
| GetFileSecurity | Obtains the SD for a particular file or directory. |
| GetKernelObjectSecurity | Obtains the SD for a specified Kernel object. |
| GetPrivateObjectSecurity | Obtains the SD for a specified private object. |
| GetUserObjectSecurity | Obtains the SD for a specified user object. |
| SetFileSecurity | Updates a file or directory’s security using the supplied SD. |
| SetKernelObjectSecurity | Updates a Kernel object’s security using the supplied SD. |
| SetPrivateObjectSecurity | Updates a private object’s security using the supplied SD. |
| SetUserObjectSecurity | Updates a user object’s security using the supplied SD. |
| CreatePrivateObjectSecurity | Allocates and initializes a self-relative SD to be used with a new private object. |
| DestroyPrivateObjectSecurity | Deletes the given private object’s SD. |
NOTE
A window station is a set of one or more desktops. NT’s default window station is WinSta0. Each window station can contain one or more Desktops. A Desktop in this context can be thought of as a set of visible windows. The default WinSta0 window station, for example, has three Desktops: logon, screen saver, and application. The SwitchDesktop API function allows you to make a different Desktop visible.
Table 20.13: Auditing Functions
| Function | Description |
| ObjectOpenAuditAlarm | Generates audit messages to log when a user attempts to gain access to an existing object or create a new one. |
| ObjectCloseAuditAlarm | Generates audit messages when the handle of an object is closed. |
| ObjectDeleteAuditAlarm | Generates audit messages when the handle of an object is deleted. |
| ObjectPrivilegeAuditAlarm | Generates audit messages when the given user (access token) attempts to perform privileged operations on a particular object. |
| PrivilegedServiceAuditAlarm | Generates audit messages when the given user (access token) attempts to perform privileged operations. |
| AccessCheckAndAuditAlarm | Performs AccessCheck and generates corresponding audit messages. |