security.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	DESKTOP_READ
#define	DESKTOP_WRITE
#define	DESKTOP_EXECUTE
#define	DESKTOP_ALL_ACCESS
#define	WINSTA_READ
#define	WINSTA_WRITE
#define	WINSTA_EXECUTE
#define	WINSTA_ACCESS_ALL

Functions
HANDLE	IntCaptureCurrentAccessToken (VOID)
PVOID	IntAllocateSecurityBuffer (_In_ SIZE_T Length)
	Allocates a buffer within UM (user mode) address space area. Such buffer is reserved for security purposes, such as allocating a buffer for a DACL or a security descriptor.
VOID	IntFreeSecurityBuffer (_In_ PVOID Buffer)
	Frees an allocated security buffer from UM memory that is been previously allocated by IntAllocateSecurityBuffer function.
NTSTATUS	IntQueryUserSecurityIdentification (_Out_ PTOKEN_USER *User)
	Queries the authenticated user security identifier (SID) that is associated with the security context of the access token that is being opened.
NTSTATUS NTAPI	IntAssignDesktopSecurityOnParse (_In_ PWINSTATION_OBJECT WinSta, _In_ PDESKTOP Desktop, _In_ PACCESS_STATE AccessState)
	Assigns a security descriptor to the desktop object during a desktop object parse procedure.
NTSTATUS NTAPI	IntCreateServiceSecurity (_Out_ PSECURITY_DESCRIPTOR *ServiceSd)
	Creates a security descriptor for the service.

Macro Definition Documentation

DESKTOP_ALL_ACCESS

#define DESKTOP_ALL_ACCESS

Value:

                            (STANDARD_RIGHTS_REQUIRED | \
                            DESKTOP_CREATEMENU       | \
                            DESKTOP_CREATEWINDOW     | \
                            DESKTOP_ENUMERATE        | \
                            DESKTOP_HOOKCONTROL      | \
                            DESKTOP_JOURNALPLAYBACK  | \
                            DESKTOP_JOURNALRECORD    | \
                            DESKTOP_READOBJECTS      | \
                            DESKTOP_SWITCHDESKTOP    | \
                            DESKTOP_WRITEOBJECTS)

Definition at line 30 of file security.h.

DESKTOP_EXECUTE

#define DESKTOP_EXECUTE

Value:

                         (STANDARD_RIGHTS_EXECUTE  | \
                         DESKTOP_SWITCHDESKTOP)

Definition at line 27 of file security.h.

DESKTOP_READ

#define DESKTOP_READ

Value:

                      (STANDARD_RIGHTS_READ      | \
                      DESKTOP_ENUMERATE         | \
                      DESKTOP_READOBJECTS)

Definition at line 15 of file security.h.

DESKTOP_WRITE

#define DESKTOP_WRITE

Value:

                       (STANDARD_RIGHTS_WRITE    | \
                       DESKTOP_CREATEMENU       | \
                       DESKTOP_CREATEWINDOW     | \
                       DESKTOP_HOOKCONTROL      | \
                       DESKTOP_JOURNALPLAYBACK  | \
                       DESKTOP_JOURNALRECORD    | \
                       DESKTOP_WRITEOBJECTS)

Definition at line 19 of file security.h.

WINSTA_ACCESS_ALL

#define WINSTA_ACCESS_ALL

Value:

                           (STANDARD_RIGHTS_REQUIRED | \
                           WINSTA_ACCESSCLIPBOARD   | \
                           WINSTA_ACCESSGLOBALATOMS | \
                           WINSTA_CREATEDESKTOP     | \
                           WINSTA_ENUMDESKTOPS      | \
                           WINSTA_ENUMERATE         | \
                           WINSTA_EXITWINDOWS       | \
                           WINSTA_READATTRIBUTES    | \
                           WINSTA_READSCREEN        | \
                           WINSTA_WRITEATTRIBUTES)

Definition at line 57 of file security.h.

WINSTA_EXECUTE

#define WINSTA_EXECUTE

Value:

                        (STANDARD_RIGHTS_EXECUTE  | \
                        WINSTA_ACCESSGLOBALATOMS | \
                        WINSTA_EXITWINDOWS)

Definition at line 53 of file security.h.

WINSTA_READ

#define WINSTA_READ

Value:

                     (STANDARD_RIGHTS_READ     | \
                     WINSTA_ENUMDESKTOPS      | \
                     WINSTA_ENUMERATE         | \
                     WINSTA_READATTRIBUTES    | \
                     WINSTA_READSCREEN)

Definition at line 42 of file security.h.

WINSTA_WRITE

#define WINSTA_WRITE

Value:

                      (STANDARD_RIGHTS_WRITE    | \
                      WINSTA_ACCESSCLIPBOARD   | \
                      WINSTA_CREATEDESKTOP     | \
                      WINSTA_WRITEATTRIBUTES)

Definition at line 48 of file security.h.

Function Documentation

IntAllocateSecurityBuffer()

PVOID IntAllocateSecurityBuffer

(

_In_ SIZE_T

Length

)

Allocates a buffer within UM (user mode) address space area. Such buffer is reserved for security purposes, such as allocating a buffer for a DACL or a security descriptor.

Parameters

[in]

Length

The length of the buffer that has to be allocated, in bytes.

Returns

Returns a pointer to an allocated buffer whose contents are arbitrary. If the function fails, it means no pages are available to reserve for memory allocation for this buffer.

Definition at line 97 of file security.c.

{
    NTSTATUS Status;
    PVOID Buffer = NULL;
 
    /* Allocate the buffer in UM memory space */
    Status = ZwAllocateVirtualMemory(ZwCurrentProcess(),
                                     &Buffer,
                                     0,
                                     &Length,
                                     MEM_COMMIT,
                                     PAGE_READWRITE);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntAllocateSecurityBuffer(): Failed to allocate the buffer (Status 0x%08lx)\n", Status);
        return NULL;
    }
 
    return Buffer;
}

Referenced by IntCreateServiceSecurity(), and IntQueryUserSecurityIdentification().

IntAssignDesktopSecurityOnParse()

NTSTATUS NTAPI IntAssignDesktopSecurityOnParse	(	_In_ PWINSTATION_OBJECT	WinSta,
		_In_ PDESKTOP	Desktop,
		_In_ PACCESS_STATE	AccessState
	)

Assigns a security descriptor to the desktop object during a desktop object parse procedure.

Parameters

[in]	WinSta	A pointer to a window station object, of which such object contains its own security descriptor that will be captured.
[in]	Desktop	A pointer to a desktop object that is created during a parse procedure.
[in]	AccessState	A pointer to an access state structure that describes the progress state of an access in action.

Returns

Returns STATUS_SUCCESS if the function has successfully assigned new security descriptor to the desktop object. A NTSTATUS failure code is returned otherwise.

Definition at line 270 of file security.c.

{
    NTSTATUS Status;
    PSECURITY_DESCRIPTOR CapturedDescriptor;
    BOOLEAN MemoryAllocated;
 
    /*
     * Capture the security descriptor from
     * the window station. The window station
     * in question has a descriptor that is
     * inheritable and contains desktop access
     * rights as well.
     */
    Status = ObGetObjectSecurity(WinSta,
                                 &CapturedDescriptor,
                                 &MemoryAllocated);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntAssignDesktopSecurityOnParse(): Failed to capture the security descriptor from window station (Status 0x%08lx)\n", Status);
        return Status;
    }
 
    /* Assign new security to the desktop */
    Status = ObAssignSecurity(AccessState,
                              CapturedDescriptor,
                              Desktop,
                              ExDesktopObjectType);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntAssignDesktopSecurityOnParse(): Failed to assign security information to the desktop object (Status 0x%08lx)\n", Status);
    }
 
    /* Release the descriptor that we have captured */
    ObReleaseObjectSecurity(CapturedDescriptor, MemoryAllocated);
    return Status;
}

Referenced by IntDesktopObjectParse().

IntCaptureCurrentAccessToken()

HANDLE IntCaptureCurrentAccessToken

(

VOID

)

IntCreateServiceSecurity()

NTSTATUS NTAPI IntCreateServiceSecurity

(

_Out_ PSECURITY_DESCRIPTOR *

ServiceSd

)

Creates a security descriptor for the service.

Parameters

[out]

ServiceSd

A pointer to a newly allocated and created security descriptor for the service.

Returns

Returns STATUS_SUCCESS if the function has successfully queried created the security descriptor. STATUS_NO_MEMORY is returned if memory allocation for security buffers because of a lack of needed pages to reserve for such allocation. A failure NTSTATUS code is returned otherwise.

Definition at line 327 of file security.c.

{
    NTSTATUS Status;
    PACL ServiceDacl;
    ULONG DaclSize;
    ULONG RelSDSize;
    SECURITY_DESCRIPTOR AbsSD;
    PSECURITY_DESCRIPTOR RelSD;
    PTOKEN_USER TokenUser;
 
    /* Initialize our local variables */
    RelSDSize = 0;
    TokenUser = NULL;
    RelSD = NULL;
    ServiceDacl = NULL;
 
    /* Query the logged in user of the current security context (aka token) */
    Status = IntQueryUserSecurityIdentification(&TokenUser);
    if (!TokenUser)
    {
        ERR("IntCreateServiceSecurity(): Failed to query the token user (Status 0x%08lx)\n", Status);
        return Status;
    }
 
    /* Initialize the absolute security descriptor */
    Status = RtlCreateSecurityDescriptor(&AbsSD, SECURITY_DESCRIPTOR_REVISION);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to initialize absolute SD (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * Build up the size of access control
     * list (the DACL) necessary to initialize
     * our ACL. The first two entry members
     * of ACL field are the authenticated user
     * that is associated with the security
     * context of the token. Then here come
     * the last two entries which are admins.
     * Why the ACL contains two ACEs of the
     * same SID is because of service access
     * rights and ACE inheritance.
     *
     * A service is composed of a default
     * desktop and window station upon
     * booting the system. On Windows connection
     * to such service is being made if no
     * default window station and desktop handles
     * were created before. The desktop and winsta
     * objects grant access on a separate type basis.
     * The user is granted full access to the window
     * station first and then full access to the desktop.
     * After that admins are granted specific rights
     * separately, just like the user. Ultimately the
     * ACEs that handle desktop rights management are
     * inherited to the default desktop object so
     * that there's no need to have a separate security
     * descriptor for the desktop object alone.
     */
    DaclSize = sizeof(ACL) +
               sizeof(ACCESS_ALLOWED_ACE) + RtlLengthSid(TokenUser->User.Sid) +
               sizeof(ACCESS_ALLOWED_ACE) + RtlLengthSid(TokenUser->User.Sid) +
               sizeof(ACCESS_ALLOWED_ACE) + RtlLengthSid(SeExports->SeAliasAdminsSid) +
               sizeof(ACCESS_ALLOWED_ACE) + RtlLengthSid(SeExports->SeAliasAdminsSid);
 
    /* Allocate memory for service DACL */
    ServiceDacl = IntAllocateSecurityBuffer(DaclSize);
    if (!ServiceDacl)
    {
        ERR("IntCreateServiceSecurity(): Failed to allocate memory for service DACL!\n");
        Status = STATUS_NO_MEMORY;
        goto Quit;
    }
 
    /* Now create the DACL */
    Status = RtlCreateAcl(ServiceDacl,
                          DaclSize,
                          ACL_REVISION);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to create service DACL (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * The authenticated user is the ultimate and absolute
     * king in charge of the created (or opened, whatever that is)
     * window station object.
     */
    Status = RtlAddAccessAllowedAceEx(ServiceDacl,
                                      ACL_REVISION,
                                      0,
                                      WINSTA_ACCESS_ALL,
                                      TokenUser->User.Sid);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to set up window station ACE for authenticated user (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * The authenticated user also has the ultimate power
     * over the desktop object as well. This ACE cannot
     * be propagated but inherited. See the comment
     * above regarding ACL size for further explanation.
     */
    Status = RtlAddAccessAllowedAceEx(ServiceDacl,
                                      ACL_REVISION,
                                      INHERIT_ONLY_ACE | NO_PROPAGATE_INHERIT_ACE | OBJECT_INHERIT_ACE,
                                      DESKTOP_ALL_ACCESS,
                                      TokenUser->User.Sid);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to set up desktop ACE for authenticated user (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * Administrators can only enumerate window
     * stations within a desktop.
     */
    Status = RtlAddAccessAllowedAceEx(ServiceDacl,
                                      ACL_REVISION,
                                      0,
                                      WINSTA_ENUMERATE,
                                      SeExports->SeAliasAdminsSid);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to set up window station ACE for admins (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * Administrators have some share of power over
     * the desktop object. They can enumerate desktops,
     * write and read upon the object itself.
     */
    Status = RtlAddAccessAllowedAceEx(ServiceDacl,
                                      ACL_REVISION,
                                      INHERIT_ONLY_ACE | NO_PROPAGATE_INHERIT_ACE | OBJECT_INHERIT_ACE,
                                      DESKTOP_ENUMERATE | DESKTOP_READOBJECTS | DESKTOP_WRITEOBJECTS,
                                      SeExports->SeAliasAdminsSid);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to set up desktop ACE for admins (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /* Set the DACL to absolute SD */
    Status = RtlSetDaclSecurityDescriptor(&AbsSD,
                                          TRUE,
                                          ServiceDacl,
                                          FALSE);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to set up service DACL to absolute SD (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /* This descriptor is ownerless */
    Status = RtlSetOwnerSecurityDescriptor(&AbsSD,
                                           NULL,
                                           FALSE);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to make the absolute SD as ownerless (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /* This descriptor has no primary group */
    Status = RtlSetGroupSecurityDescriptor(&AbsSD,
                                           NULL,
                                           FALSE);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to make the absolute SD as having no primary group (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /*
     * Determine how much size is needed to allocate
     * memory space for our relative security descriptor.
     */
    Status = RtlAbsoluteToSelfRelativeSD(&AbsSD,
                                         NULL,
                                         &RelSDSize);
    if (Status != STATUS_BUFFER_TOO_SMALL)
    {
        ERR("IntCreateServiceSecurity(): Unexpected status code, must be STATUS_BUFFER_TOO_SMALL (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /* Allocate memory for this */
    RelSD = IntAllocateSecurityBuffer(RelSDSize);
    if (!RelSD)
    {
        ERR("IntCreateServiceSecurity(): Failed to allocate memory pool for relative SD!\n");
        Status = STATUS_NO_MEMORY;
        goto Quit;
    }
 
    /* Convert the absolute SD into a relative one now */
    Status = RtlAbsoluteToSelfRelativeSD(&AbsSD,
                                         RelSD,
                                         &RelSDSize);
    if (!NT_SUCCESS(Status))
    {
        ERR("IntCreateServiceSecurity(): Failed to convert absolute SD to a relative one (Status 0x%08lx)\n", Status);
        goto Quit;
    }
 
    /* All good, give the SD to the caller */
    *ServiceSd = RelSD;
 
Quit:
    if (ServiceDacl)
    {
        IntFreeSecurityBuffer(ServiceDacl);
    }
 
    if (TokenUser)
    {
        IntFreeSecurityBuffer(TokenUser);
    }
 
    if (!NT_SUCCESS(Status))
    {
        if (RelSD)
        {
            IntFreeSecurityBuffer(RelSD);
        }
    }
 
    return Status;
}

Referenced by IntResolveDesktop().

IntFreeSecurityBuffer()

VOID IntFreeSecurityBuffer

(

_In_ PVOID

Buffer

)

Frees an allocated security buffer from UM memory that is been previously allocated by IntAllocateSecurityBuffer function.

Parameters

[in]

Buffer

A pointer to a buffer whose contents are arbitrary, to be freed from UM memory space.

Returns

Nothing.

Definition at line 133 of file security.c.

{
    SIZE_T Size = 0;
 
    ZwFreeVirtualMemory(ZwCurrentProcess(),
                        &Buffer,
                        &Size,
                        MEM_RELEASE);
}

Referenced by IntCreateServiceSecurity(), IntQueryUserSecurityIdentification(), and IntResolveDesktop().

IntQueryUserSecurityIdentification()

NTSTATUS IntQueryUserSecurityIdentification

(

_Out_ PTOKEN_USER *

User

)

Queries the authenticated user security identifier (SID) that is associated with the security context of the access token that is being opened.

Parameters

[out]

User

A pointer to the token user that contains the security identifier of the authenticated user.

Returns

Returns STATUS_SUCCESS if the function has successfully queried the token user. STATUS_UNSUCCESSFUL is returned if the effective token of the caller couldn't be opened. STATUS_NO_MEMORY is returned if memory allocation for token user buffer has failed because of lack of necessary pages reserved for such allocation. A failure NTSTATUS code is returned otherwise.

Remarks

!!!WARNING!!! – THE CALLER WHO QUERIES THE TOKEN USER IS RESPONSIBLE TO FREE THE ALLOCATED TOKEN USER BUFFER THAT IS BEING GIVEN.

Definition at line 169 of file security.c.

{
    NTSTATUS Status;
    PTOKEN_USER UserToken = NULL;
    HANDLE Token;
    ULONG BufferLength;
 
    /* Initialize the parameter */
    *User = NULL;
 
    /* Open the current token of the caller */
    Token = IntGetCurrentAccessToken();
    if (!Token)
    {
        ERR("IntQueryUserSecurityIdentification(): Couldn't capture the token!\n");
        return STATUS_UNSUCCESSFUL;
    }
 
    /*
     * Since we do not know what the length
     * of the buffer size should be exactly to
     * hold the user data, let the function
     * tell us the size.
     */
    Status = ZwQueryInformationToken(Token,
                                     TokenUser,
                                     NULL,
                                     0,
                                     &BufferLength);
    if (Status == STATUS_BUFFER_TOO_SMALL)
    {
        /*
         * Allocate some memory for the buffer
         * based on the size that the function
         * gave us.
         */
        UserToken = IntAllocateSecurityBuffer(BufferLength);
        if (!UserToken)
        {
            /* Bail out if we failed */
            ERR("IntQueryUserSecurityIdentification(): Couldn't allocate memory for the token user!\n");
            ZwClose(Token);
            return STATUS_NO_MEMORY;
        }
    }
    else if (!NT_SUCCESS(Status))
    {
        ERR("IntQueryUserSecurityIdentification(): Failed to query the necessary length for the buffer (Status 0x%08lx)!\n", Status);
        ZwClose(Token);
        return Status;
    }
 
    /* Query the user now as we have plenty of space to hold it */
    Status = ZwQueryInformationToken(Token,
                                     TokenUser,
                                     UserToken,
                                     BufferLength,
                                     &BufferLength);
    if (!NT_SUCCESS(Status))
    {
        /* We failed, bail out */
        ERR("IntQueryUserSecurityIdentification(): Failed to query token user (Status 0x%08lx)\n", Status);
        IntFreeSecurityBuffer(UserToken);
        ZwClose(Token);
        return Status;
    }
 
    /* All good, give the buffer to the caller and close the captured token */
    *User = UserToken;
    ZwClose(Token);
 
    return STATUS_SUCCESS;
}

Referenced by IntCreateServiceSecurity().