Authorization APIs

The Windows operating system provides a comprehensive set of APIs for managing authorization, which determines whether a user or process has the necessary permissions to perform a specific action on a resource. This includes working with Access Control Lists (ACLs), security descriptors, and user/group privileges.

Core Concepts

Understanding the following concepts is crucial for effective use of authorization APIs:

• Security Descriptor: A data structure that contains the security information for an object, including the owner, group, discretionary access control list (DACL), and system access control list (SACL).
• Access Control List (ACL): A list of Access Control Entries (ACEs) that specify the access rights granted or denied to specific security principals for an object.
• Access Control Entry (ACE): An entry within an ACL that defines permissions for a specific security principal.
• Security Principal: A user account, group, or service account that can be granted or denied access to resources.

Key Functions

Accessing and Modifying Security Descriptors

These functions allow you to retrieve and set the security descriptor for an object (e.g., files, registry keys, processes).

• GetSecurityObject: Retrieves the security descriptor of an object.
• SetSecurityObject: Sets the security descriptor of an object.
• ConvertStringSecurityDescriptorToSecurityDescriptor: Converts a string representation of a security descriptor into a security descriptor format.
• ConvertSecurityDescriptorToStringSecurityDescriptor: Converts a security descriptor into a string representation.

Working with Access Control Lists (ACLs)

Functions for managing the contents of ACLs, including adding, deleting, and modifying Access Control Entries (ACEs).

• CreateAcl: Creates an empty ACL.
• AddAccessAllowedAce: Adds an ACE that grants access to a specified security principal.
• AddAccessDeniedAce: Adds an ACE that denies access to a specified security principal.
• GetAclInformation: Retrieves information about an ACL.
• SetAclInformation: Modifies information about an ACL.

Checking Access Rights

Determine if a security principal has the required permissions for a given operation.

• AccessCheck: Checks whether a security principal is granted the requested access rights for an object.
• PrivilegeCheck: Checks the privileges held by a security principal.

Managing User and Group Information

APIs for retrieving information about users, groups, and their memberships.

• LookupAccountName: Retrieves the SID for a given account name.
• LookupAccountSid: Retrieves the account name for a given SID.
• GetSidSubAuthorityCount: Retrieves the number of subauthorities in a SID.

Example: Checking File Read Permissions

This example demonstrates how to check if the current user has read permissions on a file.

#include <windows.h>
#include <aclapi.h>
#include <sddl.h>

BOOL CheckFileReadAccess(const WCHAR* filePath) {
    PSECURITY_DESCRIPTOR pSD = NULL;
    PACL pDacl = NULL;
    BOOL bDaclPresent = FALSE;
    BOOL bDaclDefaulted = FALSE;
    BOOL bAccessGranted = FALSE;
    HANDLE hFile = CreateFileW(filePath, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);

    if (hFile == INVALID_HANDLE_VALUE) {
        // Handle file opening error
        return FALSE;
    }

    if (!GetSecurityInfo(hFile, SE_FILE_OBJECT, DACL_SECURITY_INFORMATION, NULL, NULL, &pDacl, NULL, NULL, &pSD)) {
        CloseHandle(hFile);
        return FALSE;
    }

    if (!GetAclInformation(pDacl, &bDaclPresent, sizeof(bDaclPresent), ACL_INFORMATION_CLASS::AclInformation)) {
        LocalFree(pSD);
        CloseHandle(hFile);
        return FALSE;
    }

    if (bDaclPresent) {
        GENERIC_MAPPING GenericMapping;
        PSECURITY_DESCRIPTOR pTempSD = NULL;
        DWORD AccessMask = 0;
        BOOL bRes = FALSE;

        // Define generic mapping for files
        GenericMapping.GenericRead = GENERIC_READ;
        GenericMapping.GenericWrite = GENERIC_WRITE;
        GenericMapping.GenericExecute = GENERIC_EXECUTE;
        GenericMapping.GenericAll = GENERIC_ALL;

        bRes = AccessCheck(pSD, GetCurrentThread(), FILE_READ_DATA, &GenericMapping, NULL, 0, &AccessMask, &bAccessGranted);

        if (!bRes) {
            // Handle AccessCheck error
        }
    } else {
        // No DACL present, typically means full access by default or explicit deny all
        // For simplicity, assuming full access if no DACL
        bAccessGranted = TRUE;
    }

    LocalFree(pSD);
    CloseHandle(hFile);
    return bAccessGranted;
}
            

Related Topics

• Access Control Model
• Security Principals
• Security Descriptors