GetAuditTrustee - Win32 API

Win32 Apps / API Reference / ACL API / GetAuditTrustee

GetAuditTrustee Function

Retrieves the audit trustee information from an audit entry.

BOOL GetAuditTrustee( _In_ PAUDIT_ENTRY AuditEntry, _Out_ PTSTR TrusteeName, _In_ DWORD cchName, _Out_ PTSTR DomainName, _In_ DWORD cchDomain, _Out_ PTSTR SidString );

Parameters

Parameter	Description
`AuditEntry`	A pointer to an `AUDIT_ENTRY` structure that contains the audit information.
`TrusteeName`	A pointer to a buffer that receives the trustee name. This parameter can be `NULL` if you do not need to retrieve the trustee name.
`cchName`	The size, in characters, of the `TrusteeName` buffer.
`DomainName`	A pointer to a buffer that receives the domain name of the trustee. This parameter can be `NULL` if you do not need to retrieve the domain name.
`cchDomain`	The size, in characters, of the `DomainName` buffer.
`SidString`	A pointer to a buffer that receives a string representation of the trustee's SID. This parameter can be `NULL` if you do not need to retrieve the SID string.

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetAuditTrustee function is used to extract individual components of a trustee from an audit entry. This is useful when processing audit logs or security descriptors that contain audit information.

The AUDIT_ENTRY structure can contain information about both success and failure audits for various access events.

Example Usage

The following example demonstrates how to use GetAuditTrustee to retrieve and display the trustee name from an audit entry.


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

int main() {
    // Assume you have obtained an AUDIT_ENTRY structure, for example:
    AUDIT_ENTRY auditEntry;
    // ... populate auditEntry with actual audit data ...
    // For demonstration, let's create a dummy entry
    auditEntry.pSid = NULL; // Simplified for example, in real scenario this would point to a valid SID
    auditEntry.Reserved = 0;
    auditEntry.Link = NULL;
    auditEntry.Inheritance = NO_INHERITANCE;
    auditEntry.Flags = 0;
    // Assume a dummy trustee name and domain
    TCHAR trusteeNameBuffer[256] = TEXT("BUILTIN\\Administrators");
    TCHAR domainNameBuffer[256] = TEXT("NT AUTHORITY");
    TCHAR sidStringBuffer[256] = TEXT("S-1-5-32-544"); // Example SID for Administrators group

    // In a real scenario, you would populate auditEntry.pAceSid etc.
    // and then use GetAuditTrustee to fill the buffers.
    // For this simplified example, we're showing how the buffers would be used.

    if (GetAuditTrustee(&auditEntry,
                        trusteeNameBuffer,
                        sizeof(trusteeNameBuffer) / sizeof(TCHAR),
                        domainNameBuffer,
                        sizeof(domainNameBuffer) / sizeof(TCHAR),
                        sidStringBuffer)) {
        printf("Trustee Name: %ws\n", trusteeNameBuffer);
        printf("Domain Name: %ws\n", domainNameBuffer);
        printf("SID String: %ws\n", sidStringBuffer);
    } else {
        DWORD error = GetLastError();
        printf("GetAuditTrustee failed with error code: %lu\n", error);
    }

    return 0;
}

Requirements

Header
`aclapi.h`
`windows.h`

Microsoft Learn