MakeSelfRelativeSD (SecurityBaseApi) - Windows API Documentation

Function

BOOL MakeSelfRelativeSD(PSECURITY_DESCRIPTOR pAbsoluteSD, PSECURITY_DESCRIPTOR pRelativeSD, LPDWORD lpdwAbsoluteSDSize, LPDWORD lpdwRelativeSDSize);

Parameters

pAbsoluteSD [PSECURITY_DESCRIPTOR]
A pointer to a SECURITY_DESCRIPTOR structure in absolute format. This parameter can be NULL.
pRelativeSD [PSECURITY_DESCRIPTOR]
A pointer to a buffer that will receive the security descriptor in self-relative format. This parameter can be NULL.
lpdwAbsoluteSDSize [LPDWORD]
A pointer to a DWORD value that specifies the size, in bytes, of the buffer pointed to by pAbsoluteSD. If pAbsoluteSD is NULL, this parameter can be NULL.
lpdwRelativeSDSize [LPDWORD]
A pointer to a DWORD value that receives the size, in bytes, of the buffer pointed to by pRelativeSD. If pRelativeSD is NULL, this parameter can be NULL.

Return value

`TRUE`

The function succeeded. The security descriptor has been converted to self-relative format.

`FALSE`

The function failed. To get extended error information, call GetLastError.

Remarks

A security descriptor can be in absolute format or self-relative format. In absolute format, all members of the security descriptor point to information stored in separate memory buffers. In self-relative format, all the information is stored in a contiguous block of memory. The security descriptor members are offsets from the beginning of this block.

The MakeSelfRelativeSD function converts a security descriptor from absolute format to self-relative format. This is useful for storing or transmitting security descriptors, because the entire structure can be treated as a single unit.

If both pAbsoluteSD and pRelativeSD are NULL, the function calculates the required buffer sizes and returns them in lpdwAbsoluteSDSize and lpdwRelativeSDSize.

If pAbsoluteSD is not NULL and pRelativeSD is NULL, the function calculates the required size for the self-relative security descriptor and returns it in lpdwRelativeSDSize. The lpdwAbsoluteSDSize parameter must contain the correct size of the absolute security descriptor.

If pAbsoluteSD is NULL, pRelativeSD is not NULL, and lpdwAbsoluteSDSize is not NULL, the function calculates the required size for the absolute security descriptor and returns it in lpdwAbsoluteSDSize.

The self-relative security descriptor is not necessarily aligned on any particular boundary.

The security descriptor in self-relative format starts with a SECURITY_DESCRIPTOR structure. The components of the security descriptor (SACL, owner, primary group, and discretionary ACL) follow this structure.

Example Usage

<!-- C++ Example -->
#include <windows.h>
#include <iostream>

int main() {
    SECURITY_DESCRIPTOR abs_sd;
    SECURITY_DESCRIPTOR rel_sd;
    DWORD abs_size = sizeof(abs_sd);
    DWORD rel_size = sizeof(rel_sd);

    // Assume abs_sd is already initialized with absolute security information
    // For demonstration, we'll just zero it out and calculate size
    ZeroMemory(&abs_sd, sizeof(abs_sd));
    abs_sd.Revision = SECURITY_DESCRIPTOR_REVISION;

    // Calculate the required size for the relative SD
    if (!MakeSelfRelativeSD(&abs_sd, NULL, &abs_size, &rel_size)) {
        std::cerr << "Error calculating relative SD size: " << GetLastError() << std::endl;
        return 1;
    }

    // Allocate buffer for relative SD
    PVOID rel_buffer = HeapAlloc(GetProcessHeap(), 0, rel_size);
    if (!rel_buffer) {
        std::cerr << "Error allocating memory for relative SD." << std::endl;
        return 1;
    }
    RtlZeroMemory(rel_buffer, rel_size);

    // Convert the absolute SD to self-relative format
    if (!MakeSelfRelativeSD(&abs_sd, (PSECURITY_DESCRIPTOR)rel_buffer, &abs_size, &rel_size)) {
        std::cerr << "Error converting to self-relative SD: " << GetLastError() << std::endl;
        HeapFree(GetProcessHeap(), 0, rel_buffer);
        return 1;
    }

    std::cout << "Successfully converted security descriptor to self-relative format." << std::endl;
    std::cout << "Absolute SD Size: " << abs_size << " bytes" << std::endl;
    std::cout << "Relative SD Size: " << rel_size << " bytes" << std::endl;

    // rel_buffer now contains the self-relative security descriptor

    HeapFree(GetProcessHeap(), 0, rel_buffer);
    return 0;
}

Requirements

SDK	Library
Windows SDK	Security.lib

MakeSelfRelativeSD