Windows Win32 API

SecurityBaseApi Functions

This header file defines functions for managing security and access control within the Windows operating system. These functions are crucial for controlling what processes and users can access system resources.

Key Concepts

• Access Tokens: Objects that describe the security context of a thread or process.
• Security Descriptors: Objects that contain the security information of an object, including the owner, group, access control list (ACL), and system access control list (SACL).
• Access Control Lists (ACLs): Lists of access control entries (ACEs) that specify the permissions granted or denied to users or groups.

Core Functions

Function	Description
CreateProcessToken	Creates a new access token for a new process.
DuplicateAccessToken	Duplicates an existing access token.
GetTokenInformation	Retrieves various types of information about an access token.
SetTokenInformation	Sets information in an access token.
AdjustTokenPrivileges	Enables or disables the privileges in the specified access token.
AllocateAndInitializeSid	Allocates and initializes a memory buffer for a SID.
FreeSid	Frees a SID previously allocated by AllocateSid or AllocateAndInitializeSid.
CreateWellKnownSid	Creates a SID for a well-known group.
AreAllAccessRightsGranted	Checks if all specified access rights are granted by an access token.
AccessCheck	Determines whether a security descriptor grants a requested access right to an access token.

Function Details

CreateProcessToken

Creates a new access token for a new process.

BOOL CreateProcessToken(
  HANDLE               hExistingToken,
  DWORD                dwDesiredAccess,
  LPSECURITY_ATTRIBUTES lpTokenAttributes,
  BOOL                 bInheritHandles,
  DWORD                dwCreationFlags,
  LPVOID               lpEnvironment,
  LPSTARTUPINFOW       lpStartupInfo,
  LPPROCESS_INFORMATION lpProcessInformation
);

DuplicateAccessToken

Duplicates an existing access token. This is often used to create a token for a new process or thread with modified privileges.

BOOL DuplicateAccessToken(
  HANDLE               ExistingTokenHandle,
  DWORD                DesiredAccess,
  LPSECURITY_ATTRIBUTES TokenAttributes,
  BOOL                 bEffectiveOnly,
  PHANDLE              NewTokenHandle
);

GetTokenInformation

Retrieves various types of information about an access token, such as its size, whether it's restricted, and the SIDs associated with it.

BOOL GetTokenInformation(
  HANDLE                  TokenHandle,
  TOKEN_INFORMATION_CLASS TokenInformationClass,
  LPVOID                  TokenInformation,
  DWORD                   TokenInformationLength,
  PDWORD                  ReturnLength
);

SetTokenInformation

Sets information in an access token. This can be used to modify token properties like impersonation levels or privilege settings.

BOOL SetTokenInformation(
  HANDLE                  TokenHandle,
  TOKEN_INFORMATION_CLASS TokenInformationClass,
  LPVOID                  TokenInformation,
  DWORD                   TokenInformationLength
);

AdjustTokenPrivileges

Enables or disables the privileges in the specified access token. Privileges are used to perform specific system-related operations.

BOOL AdjustTokenPrivileges(
  HANDLE                  TokenHandle,
  BOOL                    DisableAllPrivileges,
  PTOKEN_PRIVILEGES       NewState,
  DWORD                   BufferLength,
  PTOKEN_PRIVILEGES       PreviousState,
  PDWORD                  ReturnLength
);

AllocateAndInitializeSid

Allocates and initializes a memory buffer for a SID (Security Identifier). SIDs are used to uniquely identify users, groups, and other security principals.

BOOLEAN AllocateAndInitializeSid(
  PSID_IDENTIFIER_AUTHORITY pIdentifierAuthority,
  UCHAR                     nSubAuthorityCount,
  DWORD                     dwSubAuthority0,
  DWORD                     dwSubAuthority1,
  DWORD                     dwSubAuthority2,
  DWORD                     dwSubAuthority3,
  DWORD                     dwSubAuthority4,
  DWORD                     dwSubAuthority5,
  DWORD                     dwSubAuthority6,
  DWORD                     dwSubAuthority7,
  PSID                      *pSid
);

FreeSid

Frees a SID previously allocated by AllocateSid or AllocateAndInitializeSid. It's important to free memory allocated for SIDs to prevent leaks.

BOOLEAN FreeSid(
  PSID pSid
);

CreateWellKnownSid

Creates a SID for a well-known group, such as the local system, administrators, or users. This simplifies common security principal identification.

BOOLEAN CreateWellKnownSid(
  WELL_KNOWN_SID_TYPE SidType,
  PSID                pDomainSid,
  PSID                pSid,
  DWORD               cbSid
);

AreAllAccessRightsGranted

Checks if all specified access rights are granted by an access token. This is a convenient helper function for access checking.

BOOL AreAllAccessRightsGranted(
  PACCESS_TOKEN          Token,
  PRIVILEGE_SET *        Privileges
);

AccessCheck

Determines whether a security descriptor grants a requested access right to an access token. This is a fundamental function for enforcing access control.

BOOL AccessCheck(
  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  HANDLE               ClientToken,
  DWORD                DesiredAccess,
  PRIVILEGE_SET *      GenericMapping,
  PPRIVILEGE_SET       PrivilegeSet,
  PDWORD               AccessStatus,
  PDWORD               Validity
);