CreatePrivateObjectSecurity

The CreatePrivateObjectSecurity function allocates and initializes a self-relative security descriptor for a new private object. A protected server calls this function when it creates a new private object.

BOOL CreatePrivateObjectSecurity(
  PSECURITY_DESCRIPTOR ParentDescriptor,
                           // pointer to parent directory SD
  PSECURITY_DESCRIPTOR CreatorDescriptor,
                           // pointer to creator SD
  PSECURITY_DESCRIPTOR *NewDescriptor,
                           // pointer to pointer to new SD
  BOOL IsDirectoryObject,  // container flag for new SD
  HANDLE Token,            // handle to client's access token
  PGENERIC_MAPPING GenericMapping 
                           // pointer to access-rights structure
);
 

Parameters

ParentDescriptor

Pointer to the security descriptor for the parent directory in which a new object is being created. If there is no parent directory, this parameter can be NULL.

CreatorDescriptor

Pointer to a security descriptor provided by the creator of the object. If the object's creator does not explicitly pass security information for the new object, this parameter is intended to be NULL.

lppsdNew

Pointer to a variable that receives a pointer to the newly allocated self-relative security descriptor. The caller must call the DestroyPrivateObjectSecurity function to free this security descriptor.

IsDirectoryObject

Specifies whether the new object is a container. A value of TRUE indicates the object contains other objects, such as a directory.

Token

Identifies the access token for the client process on whose behalf the object is being created. If this is an impersonation token, it must be at SecurityIdentification level or higher. For a full description of the SecurityIdentification impersonation level, see the SECURITY_IMPERSONATION_LEVEL enumerated type

A client token is used to retrieve default security information for the new object, such as its default owner, primary group, and discretionary access-control list. The token must be open for TOKEN_QUERY access.

GenericMapping

Pointer to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

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 a system access-control list, or SACL, is specified in the SECURITY_DESCRIPTOR specified by CreatorDescriptor, Token must have the SE_SECURITY_NAME privilege enabled, and the caller's token must have the SE_AUDIT_NAME privilege enabled. The CreatePrivateObjectSecurity function performs access/privilege checks to ensure this, and may generate audits during the process.

QuickInfo

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

See Also

Client/Server Access Control Overview, Client/Server Access Control Functions, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, GetTokenInformation, OpenProcessToken, SECURITY_DESCRIPTOR, SECURITY_IMPERSONATION_LEVEL, SetPrivateObjectSecurity