Conditional ACE bytecode

Conditional ACE expressions are encoded as postfix bytecode — a stack-based instruction sequence where literals push values onto the stack and operators pop and push. The same bytecode is used in callback ACEs (ACCESS_ALLOWED_CALLBACK, SYSTEM_AUDIT_CALLBACK, etc.) and in CAAP rule applies-to expressions.

This page is the byte-level reference for the bytecode. The conceptual model (three-valued logic, four attribute namespaces, when expressions fire) is in Conditional ACEs.

All multi-byte integers are little-endian.

The magic header #

Every conditional ACE expression bytecode starts with the four magic bytes:

0x61 0x72 0x74 0x78

These spell artx in ASCII (no actual significance beyond serving as a distinguishing prefix). Conditional ApplicationData buffers that do not start with these bytes are not recognised as conditional expressions; the kernel treats the expression as evaluating to UNKNOWN.

The magic bytes are followed by the bytecode proper. Total ApplicationData length is determined by the containing ACE's AceSize (for ACE-embedded expressions) or by the CAAP wire format's per-applies-to length (for CAAP).

The bytecode model #

The bytecode is a sequence of tokens (instructions). Each token has a 1-byte opcode followed by 0 or more bytes of inline data. The reader walks the bytecode left to right; at end, the stack must contain exactly one tri-state value (TRUE, FALSE, or UNKNOWN).

The stack holds values; operators pop their operands and push results. Stack depth grows with literal tokens, shrinks with operator tokens.

Recommended stack depth limit #

Implementations should enforce a maximum evaluation stack depth of 1024. Expressions that would exceed this depth evaluate to UNKNOWN. This prevents pathological deep-nesting expressions from consuming unbounded stack space.

Literal tokens #

Literal tokens push a typed value onto the stack.

Integer literals (0x01–0x04) #

The four integer-width opcodes:

Each integer literal is encoded as 11 bytes:

The sign and base codes are metadata about how the integer was originally written; they do not affect evaluation. The same numeric value can appear with different sign/base codes; comparisons use the QWORD value.

Unicode string literal (0x10) #

The string's character count is length / 2; the byte length is what's in the length field.

Octet string literal (0x18) #

Used for binary data — file hashes, GUIDs, anything not naturally a string or number.

Composite literal (0x50) #

A heterogeneous array of values. Used for set-membership operators (Any_of, Member_of, etc.).

Each element is itself a literal token (integer, string, octet, or SID). The kernel reads elements until the total length is consumed.

SID literal (0x51) #

Used in Member_of-family operators where the comparison is against a specific SID.

Attribute reference tokens #

Attribute references push the value of a named attribute onto the stack. Each namespace has its own opcode:

After the opcode, the attribute name follows in the same format as a string literal (without the 0x10 type-tag byte):

The attribute name is looked up in the corresponding namespace. If found, the attribute's value(s) are pushed. If not found, UNKNOWN is pushed.

The reference's stored value type matches the attribute's stored type. For multi-valued attributes, the resulting stack value is a composite-equivalent that subsequent operators handle as a set.

Attribute name lookups are case-insensitive by default. An attribute can opt into case-sensitive lookup via the CLAIM_SECURITY_ATTRIBUTE_VALUE_CASE_SENSITIVE flag on the attribute itself.

Relational operators #

Pop two operands, push TRUE / FALSE / UNKNOWN.

Type-mixing rules #

The kernel promotes operand types per these rules:

• INT64 vs UINT64: a negative INT64 is always less than any UINT64. Both can be compared in either direction.
• String vs string: lexicographic, case-insensitive by default (unless either operand was tagged case-sensitive).
• Octet vs octet: byte-exact.
• SID vs SID: byte-exact, no normalisation.
• Boolean vs boolean: TRUE > FALSE (rarely useful).
• Mixed types where promotion is undefined: result is UNKNOWN.

A comparison with UNKNOWN on either side produces UNKNOWN.

Set-membership operators #

For operations involving sets (composites or multi-valued attributes).

Exists is special — it specifically returns TRUE if an attribute exists on its token/object, FALSE if not. This distinguishes "attribute is absent" from "attribute exists with UNKNOWN-producing value", which the other operators conflate.

Not_Exists is the conservative way to test "the attribute is not there" — it returns TRUE for missing attributes (in contrast to !Exists(...) which would return UNKNOWN if the attribute is missing because Exists returns UNKNOWN there).

Logical operators #

Three-valued logic over TRUE/FALSE/UNKNOWN.

The truth tables:

AND (pops 2) #

OR (pops 2) #

NOT (pops 1) #

UNKNOWN propagates through NOT — there is no way to "prove an UNKNOWN value is FALSE" by negating. To test "the attribute is absent", use Not_Exists, not !Exists.

Boolean coercion #

When a non-boolean value reaches a position that requires a boolean (top of stack at the end of evaluation, operand of AND/OR/NOT), it is coerced:

Strings, SIDs, and binary blobs do not coerce to a definite boolean — they yield UNKNOWN when forced into a boolean position. The relational operators (e.g. @User.Department == "Engineering") are how to convert them to booleans by explicit comparison.

Final result #

The expression evaluates by walking the bytecode. The final stack should contain exactly one value, which is the result. If:

• The final stack is empty → UNKNOWN.
• The final stack has more than one value → UNKNOWN.
• The final stack's single value is non-boolean and doesn't coerce → UNKNOWN.
• The final stack's single value is TRUE / FALSE / UNKNOWN → that value.

Any stack-violation or coercion failure during evaluation also produces UNKNOWN. The kernel does not raise errors for malformed expressions during evaluation; UNKNOWN is the universal "I cannot decide" signal.

Validation #

The kernel validates conditional ACE bytecode at ingestion time (when the SD or CAAP is set):

• The magic bytes must be present.
• Each token's opcode must be recognised.
• Each literal's inline data must fit within the buffer.
• The expression must be structurally well-formed (in particular, each operator must have enough operands available at its point in the bytecode).

Failures at ingestion return -EINVAL. The kernel does not evaluate the expression at ingestion — that happens at access-check time. Ingestion validation catches structural problems; evaluation handles runtime semantics.

Structurally-valid expressions that produce UNKNOWN at runtime (because of missing attributes, type mismatches, etc.) are still valid; they just evaluate to UNKNOWN, with the standard fail-open-for-deny-and-audit behaviour.

Encoded example #

A concrete example. The expression @User.Department == "Engineering" would encode roughly as:

[magic: 0x61 0x72 0x74 0x78]
[@User. opcode: 0xF9]
[name length: 14 (u32le) — for UTF-16LE "Department"]
[name: UTF-16LE "Department"]
[string literal opcode: 0x10]
[string length: 22 (u32le) — for UTF-16LE "Engineering"]
[string bytes: UTF-16LE "Engineering"]
[== opcode: 0x80]

At evaluation:

1. Push the value of @User.Department (or UNKNOWN if absent).
2. Push the literal "Engineering".
3. == pops both, compares, pushes TRUE / FALSE / UNKNOWN.
4. The single stack value is the result.

Size limits #

Per-expression:

A pathological expression that approaches these limits will be rejected at ingestion or yield UNKNOWN at evaluation.