Expand Minimize

QueryServiceObjectSecurity function

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 WINAPI QueryServiceObjectSecurity(
  _In_       SC_HANDLE hService,
  _In_       SECURITY_INFORMATION dwSecurityInformation,
  _Out_opt_  PSECURITY_DESCRIPTOR lpSecurityDescriptor,
  _In_       DWORD cbBufSize,
  _Out_      LPDWORD pcbBytesNeeded
);

Parameters

hService [in]

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.

dwSecurityInformation [in]

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.

lpSecurityDescriptor [out, optional]

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.

cbBufSize [in]

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

pcbBytesNeeded [out]

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 codeDescription
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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winsvc.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Low-level Access Control
Low-level Access Control Functions
CreateService
GetNamedSecurityInfo
OpenService
SECURITY_DESCRIPTOR
SetServiceObjectSecurity

 

 

Community Additions

ADD
Show:
© 2014 Microsoft