Platform SDK: Access Control

SetPrivateObjectSecurityEx

The SetPrivateObjectSecurityEx function modifies the security descriptor of a private object. SetPrivateObjectSecurityEx has a flags parameter that allows you to specify whether the protected server supports automatic inheritance of ACEs.

BOOL SetPrivateObjectSecurityEx (
  SECURITY_INFORMATION SecurityInformation,     // type
  PSECURITY_DESCRIPTOR ModificationDescriptor,  // new SD
  PSECURITY_DESCRIPTOR *SecurityDescriptor,     // SD
  ULONG AutoInheritFlags,                       // inheritance option
  PGENERIC_MAPPING GenericMapping,              // mapping
  HANDLE Token                                  // handle to client token
);

Parameters

SecurityInformation
[in] Indicates the parts of the security descriptor to set. This value can be a combination of the SECURITY_INFORMATION bit flags.
ModificationDescriptor
[in] Pointer to a SECURITY_DESCRIPTOR structure. The parts of this security descriptor indicated by the SecurityInformation parameter are applied to the SecurityDescriptor security descriptor.
SecurityDescriptor
[out] Pointer to a pointer to a SECURITY_DESCRIPTOR structure. This security descriptor must be in self-relative form.

On input, this is the current security descriptor of the private object. The function modifies it to produce the new security descriptor. If necessary, the SetPrivateObjectSecurityEx function allocates additional memory to produce a larger security descriptor.

AutoInheritFlags
[in] Specifies automatic inheritance of ACEs. If the protected server does not implement automatic inheritance, it should specify zero; otherwise, it can specify a combination of the following values.
Value Meaning
SEF_DACL_AUTO_INHERIT If this flag is set, the DACL is treated as an auto-inherit DACL and is processed as described in the following Remarks section. This bit is ignored if DACL_SECURITY_INFORMATION is not set in the SecurityInformation parameter.
SEF_SACL_AUTO_INHERIT If this flag is set, the SACL is treated as an auto-inherit SACL and is processed as described in the following Remarks section. This bit is ignored if SACL_SECURITY_INFORMATION is not set in the SecurityInformation parameter.
SEF_AVOID_PRIVILEGE_CHECK If this flag is set, the Token parameter can be NULL, and the token is not checked to determine if the ModificationDescriptor is valid. This flag is useful while implementing automatic inheritance to avoid checking privileges on each child updated.

GenericMapping
[in] Pointer to a GENERIC_MAPPING structure that specifies the specific and standard access rights that correspond to each of the generic access rights.
Token
[in] Identifies the access token for the client on whose behalf the private object's security is being modified. This parameter is required to ensure that the client has provided a legitimate value for a new owner SID. The token must be open for TOKEN_QUERY access.

Return Values

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

If the AutoInheritFlags parameter is zero, SetPrivateObjectSecurityEx is identical to the SetPrivateObjectSecurity function.

The SetPrivateObjectSecurityEx function is successful only if the following conditions are met:

The process calling this function must not be impersonating a client.

If AutoInheritFlags specifies the SEF_DACL_AUTO_INHERIT bit, the function applies the following rules to the DACL to create the new security descriptor from the current descriptor

If AutoInheritFlags specifies the SEF_SACL_AUTO_INHERIT bit, the function applies similar rules to the new SACL.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Advapi32.lib.

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, CreatePrivateObjectSecurityEx, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetUserObjectSecurity