Edit

Security Descriptor Definition Language for Conditional ACEs

  • Article

A conditional access control entry (ACE) allows an access condition to be evaluated when an access check is performed. The security descriptor definition language (SDDL) provides syntax for defining conditional ACEs in a string format.

The SDDL for a conditional ACE is the same as for any ACE, with the syntax for the conditional statement appended to the end of the ACE string. For information about SDDL, see Security Descriptor Definition Language.

The "#" sign is synonymous with "0" in resource attributes. For example, D:AI(XA;OICI;FA;;;WD;(OctetStringType==#1#2#3##)) is equivalent to and interpreted as D:AI(XA;OICI;FA;;;WD;(OctetStringType==#01020300)).

Conditional ACE String Format

Each ACE in a security descriptor string is enclosed in parentheses. The fields of the ACE are in the following order and are separated by semicolons (;).

AceType**;AceFlags;Rights;ObjectGuid;InheritObjectGuid;AccountSid;(ConditionalExpression)**

The fields are as described in ACE Strings, with the following exceptions.

  • The AceType field can be one of the following strings.

    ACE type string Constant in Sddl.h AceType value
    "XA"
    		 SDDL_CALLBACK_ACCESS_ALLOWED
    		 ACCESS_ALLOWED_CALLBACK_ACE_TYPE
    "XD"
    		 SDDL_CALLBACK_ACCESS_DENIED
    		 ACCESS_DENIED_CALLBACK_ACE_TYPE

  • The ACE string includes one or more conditional expressions, enclosed in parentheses at the end of the string.

Conditional Expressions

A conditional expression can include any of the following elements.

Expression element Description
AttributeName
 Tests whether the specified attribute has a nonzero value.
exists AttributeName
 Tests whether the specified attribute exists in the client context.
AttributeName Operator Value
 Returns the result of the specified operation.
ConditionalExpression**||**ConditionalExpression
 Tests whether either of the specified conditional expressions is true.
ConditionalExpression && ConditionalExpression
 Tests whether both of the specified conditional expressions are true.
!(ConditionalExpression)
 The inverse of a conditional expression.
Member_of{SidArray}
 Tests whether the SID_AND_ATTRIBUTES array of the client context contains all of the Security Identifiers (SIDs) in the comma-separated list specified by SidArray.
For Allow ACEs, a client context SID must have the SE_GROUP_ENABLED attribute set to be considered a match.
For Deny ACEs, a client context SID must have either the SE_GROUP_ENABLED or the SE_GROUP_USE_FOR_DENY_ONLY attribute set to be considered a match.
The SidArray array can contain either SID strings (for example, "S-1-5-6") or SID aliases (for example, "BA"

Attributes

An attribute represents an element in the AUTHZ_SECURITY_ATTRIBUTES_INFORMATION array in the client context. An attribute name can contain any alphanumeric characters and any of the characters ":", "/", ".", and "_".

An attribute value can be any of the following types.

Value type Description
Integer
 A 64-bit integer in either decimal or hexadecimal notation.
String
 A string value delimited by quotes.
SID
 SID(S-1-1-0) or SID(BA). Has to be on RHS of Member_of or Device_Member_of.
BLOB
 # followed by hexadecimal numbers. If length of the numbers is odd, then the # is translated to a 0 to make it even. Also an # appearing elsewhere in the value is translated to a 0.

Operators

The following operators are defined for use in conditional expressions to test the values of attributes. All of these are binary operators and used in the form AttributeName Operator Value.

Operator Description
==
 Conventional definition.
!=
 Conventional definition.
<
 Conventional definition.
<=
 Conventional definition.
>
 Conventional definition.
>=
 Conventional definition.
Contains
 TRUE if the value of the specified attribute is a superset of the specified value; otherwise, FALSE.
Any_of
 TRUE if the specified value is a superset of the value of the specified attribute; otherwise, FALSE.

In addition, the unary operators Exists, Member_of, and negation (!) are defined as described in the Conditional Expressions table.

The "Contains" operator must be preceded and followed by white space, and the "Any_of" operator must be preceded by white space.

Operator Precedence

The operators are evaluated in the following order of precedence, with operations of equal precedence being evaluated from left to right.

  1. Exists, Member_of
  2. Contains, Any_of
  3. ==, !=, <, <=, >, >=
  4. !
  5. &&
  6. ||

In addition, any portion of a conditional expression can be enclosed in parentheses. Expressions within parentheses are evaluated first.

Unknown Values

The results of conditional expressions sometimes return a value of Unknown. For example, any of the relational operations return Unknown when the specified attribute does not exist.

The following table describes the results for a logical AND operation between two conditional expressions, ConditionalExpression1 and ConditionalExpression2.

ConditionalExpression1 ConditionalExpression2 ConditionalExpression1 && ConditionalExpression2
TRUE
 TRUE
 TRUE
TRUE
 FALSE
 FALSE
TRUE
 UNKNOWN
 UNKNOWN
FALSE
 TRUE
 FALSE
FALSE
 FALSE
 FALSE
FALSE
 UNKNOWN
 FALSE
UNKNOWN
 TRUE
 UNKNOWN
UNKNOWN
 FALSE
 FALSE
UNKNOWN
 UNKNOWN
 UNKNOWN

The following table describes the results for a logical OR operation between two conditional expressions, ConditionalExpression1 and ConditionalExpression2.

ConditionalExpression1 ConditionalExpression2 ConditionalExpression1 || ConditionalExpression2
TRUE
 TRUE
 TRUE
TRUE
 FALSE
 TRUE
TRUE
 UNKNOWN
 TRUE
FALSE
 TRUE
 TRUE
FALSE
 FALSE
 FALSE
FALSE
 UNKNOWN
 UNKNOWN
UNKNOWN
 TRUE
 TRUE
UNKNOWN
 FALSE
 UNKNOWN
UNKNOWN
 UNKNOWN
 UNKNOWN

The negation of a conditional expression with a value of UNKNOWN is also UNKNOWN.

Conditional ACE Evaluation

The following table describes the access check result of a conditional ACE depending on the final evaluation of the conditional expression.

ACE type TRUE FALSE UNKNOWN
Allow
 Allow
 Ignore ACE
 Ignore ACE
Deny
 Deny
 Ignore ACE
 Deny

Examples

The following examples show how the specified access policies are represented by a conditional ACE defined by using SDDL.

Policy

Allow Execute to Everyone if both of the following conditions are met:

  • Title = PM
  • Division = Finance or Division = Sales

SDDL

D:(XA; ;FX;;;S-1-1-0; (@User.Title=="PM" && (@User.Division=="Finance" || @User.Division ==" Sales")))

Policy

Allow execute if any of the user s projects intersect with the file s projects.

SDDL

D:(XA; ;FX;;;S-1-1-0; (@User.Project Any_of @Resource.Project))

Policy

Allow read access if the user has logged in with a smart card, is a backup operator, and is connecting from a machine with Bitlocker enabled.

SDDL

D:(XA; ;FR;;;S-1-1-0; (Member_of {SID(Smartcard_SID), SID(BO)} && @Device.Bitlocker))

[MS-DTYP]: Security Descriptor Description Language