GetSecurityInfo

The GetSecurityInfo function retrieves a copy of the security descriptor for an object specified by a handle.

DWORD GetSecurityInfo(
  HANDLE handle,     // handle to the object
  SE_OBJECT_TYPE ObjectType,
                     // type of object
  SECURITY_INFORMATION SecurityInfo, 
                     // type of security information to retrieve
  PSID *ppsidOwner,  // receives a pointer to the owner SID
  PSID *ppsidGroup,  // receives a pointer to the primary group SID
  PACL *ppDacl,      // receives a pointer to the DACL
  PACL *ppSacl,      // receives a pointer to the SACL
  PSECURITY_DESCRIPTOR *ppSecurityDescriptor
                     // receives a pointer to the security descriptor
);
 

Parameters

handle

A handle to the object from which to retrieve security information.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object named by the pObjectName parameter.

SecurityInfo

A set of SECURITY_INFORMATION bit flags that indicate the type of security information to retrieve. This parameter can be a combination of the following values.

Value	Meaning
OWNER_SECURITY_INFORMATION	If this flag is set, the ppsidOwner parameter receives the security identifier (SID) of the object's owner.
GROUP_SECURITY_INFORMATION	If this flag is set, the ppsidGroup parameter receives the SID of the object's primary group.
DACL_SECURITY_INFORMATION	If this flag is set, the ppDacl parameter receives the object's discretionary access-control list (DACL).
SACL_SECURITY_INFORMATION	If this flag is set, the ppSacl parameter receives the object's system access-control list (SACL)..

ppsidOwner

Pointer to a variable that receives a pointer to the owner SID in the security descriptor returned in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the owner SID.

ppsidGroup

Pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the group SID.

ppDacl

Pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the DACL.

ppSacl

Pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not need the SACL.

ppSecurityDescriptor

Pointer to a variable that receives a pointer to the security descriptor of the object. You must call the LocalFree function to free the returned buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WINERROR.H.

Remarks

If the ppsidOwner, ppsidGroup, ppDacl, ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor returned in ppSecurityDescriptor.

To read the owner, group, or DACL from the object's security descriptor, 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 object's DACL 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 proper 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.

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in aclapi.h.
  Import Library: Use advapi32.lib.

See Also

Windows NT 4.0 Access Control Overview, Windows NT 4.0 Access-Control Functions, ACL, GetNamedSecurityInfo, LocalFree, SE_OBJECT_TYPE, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetNamedSecurityInfo, SetSecurityInfo, SID