Windows API Security

Accessing Security Structures and Functions

SECURITY_ATTRIBUTES Structure

The SECURITY_ATTRIBUTES structure contains information about the security of an object, including the security descriptor of the object.

Syntax

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 member to sizeof(SECURITY_ATTRIBUTES).
  • lpSecurityDescriptor: A pointer to a SECURITY_DESCRIPTOR structure that specifies the security descriptor for the object. If this member is NULL, the object is assigned a default security descriptor.
  • bInheritHandle: A boolean value that specifies whether child processes created with CreateProcess inherit this handle. If this member is TRUE, child processes inherit the handle.

Description

When you create a securable object, you can provide a pointer to a SECURITY_ATTRIBUTES structure to specify the object's security descriptor and its inheritance. This allows you to control which users and groups have access to the object and whether that access is inherited by child processes.

Related Structures

Related Functions

Remarks

It is important to properly initialize the nLength member of the SECURITY_ATTRIBUTES structure. Failing to do so can lead to unexpected behavior or security vulnerabilities.

Setting lpSecurityDescriptor to NULL means the object will be created with a default security descriptor, which is generally determined by the caller's security token and the system's default security settings.

Example Usage (Conceptual)

The following snippet illustrates how SECURITY_ATTRIBUTES might be used when creating a securable object, such as an event:

#include <windows.h>
#include <iostream>

int main() {
    SECURITY_ATTRIBUTES sa;
    sa.nLength = sizeof(SECURITY_ATTRIBUTES);
    sa.bInheritHandle = FALSE;

    // Create a security descriptor (simplified example)
    // In a real scenario, you would use InitializeSecurityDescriptor,
    // SetSecurityDescriptorDacl, etc.
    PSECURITY_DESCRIPTOR pSD = NULL;
    // For simplicity, we'll use NULL for default security descriptor
    // sa.lpSecurityDescriptor = pSD; 

    // Let's assume we are creating an event with default security
    sa.lpSecurityDescriptor = NULL; 

    HANDLE hEvent = CreateEvent(
        &sa,      // Security attributes
        FALSE,    // Manual-reset event
        FALSE,    // Initial state is signaled
        L"MySecureEvent" // Event name
    );

    if (hEvent != NULL) {
        std::wcout << L"Event created successfully." << std::endl;
        CloseHandle(hEvent);
    } else {
        std::wcerr << L"Failed to create event. Error: " << GetLastError() << std::endl;
    }

    return 0;
}