AddMandatoryAce function (securitybaseapi.h)

Article
10/13/2021

The AddMandatoryAce function adds a SYSTEM_MANDATORY_LABEL_ACE access control entry (ACE) to the specified system access control list (SACL).

Syntax

BOOL AddMandatoryAce(
  [in, out] PACL  pAcl,
  [in]      DWORD dwAceRevision,
  [in]      DWORD AceFlags,
  [in]      DWORD MandatoryPolicy,
  [in]      PSID  pLabelSid
);

Parameters

[in, out] pAcl

A pointer to an SACL. This function adds a mandatory ACE to the end of this SACL. The ACE is in the form of a SYSTEM_MANDATORY_LABEL_ACE structure.

[in] dwAceRevision

The revision level of the SACL being modified. This value can be one of the following values.

Value	Meaning
ACL_REVISION	The SACL does not contain object-specific ACEs.
ACL_REVISION_DS	The SACL contains object-specified ACEs.

[in] AceFlags

A set of bit flags that control ACE inheritance. This function sets these flags in the AceFlags member of the ACE_HEADER structure of the new ACE.

This parameter can be a combination of the following values.

Value	Meaning
OBJECT_INHERIT_ACE 0x1	The ACE is inherited by noncontainer objects.
CONTAINER_INHERIT_ACE 0x2	The ACE is inherited by container objects.
NO_PROPAGATE_INHERIT_ACE 0x4	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
INHERIT_ONLY_ACE 0x8	The ACE does not apply to the object to which the SACL is assigned, but the ACE can be inherited by child objects.
INHERITED_ACE 0x10	The ACE is inherited. Operations that change the security on a tree of objects may modify inherited ACEs without changing ACEs that were directly applied to the object.

[in] MandatoryPolicy

The access policy for principals with a mandatory integrity level lower than the object associated with the SACL that contains this ACE.

Value	Meaning
SYSTEM_MANDATORY_LABEL_NO_WRITE_UP 0x1	A principal with a lower mandatory level than the object cannot write to the object.
SYSTEM_MANDATORY_LABEL_NO_READ_UP 0x2	A principal with a lower mandatory level than the object cannot read the object.
SYSTEM_MANDATORY_LABEL_NO_EXECUTE_UP 0x4	A principal with a lower mandatory level than the object cannot execute the object.

[in] pLabelSid

A pointer to an SID that specifies the mandatory integrity level of the object associated with the SACL being appended.

Return value

If the function succeeds, it returns TRUE.

If the function fails, it returns FALSE. For extended error information, call GetLastError. The following are possible error values.

Return code/value	Description
ERROR_ALLOTTED_SPACE_EXCEEDED 0x540	The new ACE does not fit into the pAcl buffer.

Remarks

To compile an application that uses this function, define _WIN32_WINNT as 0x0600 or later. For more information, see Using the Windows Headers.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	securitybaseapi.h (include WinBase.h)
Library	Advapi32.lib
DLL	Advapi32.dll