QueryServiceObjectSecurity function (winsvc.h)

Article
10/13/2021

The QueryServiceObjectSecurity function retrieves a copy of the security descriptor associated with a service object. You can also use the GetNamedSecurityInfo function to retrieve a security descriptor.

Syntax

BOOL QueryServiceObjectSecurity(
  [in]            SC_HANDLE            hService,
  [in]            SECURITY_INFORMATION dwSecurityInformation,
  [out, optional] PSECURITY_DESCRIPTOR lpSecurityDescriptor,
  [in]            DWORD                cbBufSize,
  [out]           LPDWORD              pcbBytesNeeded
);

Parameters

[in] hService

A handle to the service control manager or the service. Handles to the service control manager are returned by the OpenSCManager function, and handles to a service are returned by either the OpenService or CreateService function. The handle must have the READ_CONTROL access right.

[in] dwSecurityInformation

A set of bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the SECURITY_INFORMATION bit flags, with the exception that this function does not support the LABEL_SECURITY_INFORMATION value.

[out, optional] lpSecurityDescriptor

A pointer to a buffer that receives a copy of the security descriptor of the specified service object. The calling process must have the appropriate access to view the specified aspects of the security descriptor of the object. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

[in] cbBufSize

The size of the buffer pointed to by the lpSecurityDescriptor parameter, in bytes. The largest size allowed is 8 kilobytes.

[out] pcbBytesNeeded

A pointer to a variable that receives the number of bytes needed to return the requested security descriptor information, if the function fails.

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.

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Return code	Description
ERROR_ACCESS_DENIED	The specified handle was not opened with READ_CONTROL access, or the calling process is not the owner of the object.
ERROR_INVALID_HANDLE	The specified handle is not valid.
ERROR_INSUFFICIENT_BUFFER	The security descriptor information is too large for the lpSecurityDescriptor buffer. The number of bytes required to get all the information is returned in the pcbBytesNeeded parameter. Nothing is written to the lpSecurityDescriptor buffer.
ERROR_INVALID_PARAMETER	The specified security information is not valid.

Remarks

When a service is created, the service control manager assigns a default security descriptor to the service object. To retrieve a copy of the security descriptor for a service object, call the QueryServiceObjectSecurity function. To change the security descriptor, call the SetServiceObjectSecurity function. For a description of the default security descriptor for a service object, see Service Security and Access Rights.

To read the owner, group, or DACL from the security descriptor of the service object, the calling process must have been granted READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must be the owner of the object or the DACL of the object must grant the access.

To read the SACL from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access when the handle was opened. The correct way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's current token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winsvc.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll