Add support for the undocumented @token. (0xfc) attribute token (Part of #135)

Windows implements a fifth conditional-expression attribute token, 0xfc, with the
SDDL prefix "@token.". MS-DTYP 2.4.4.17.8 documents only 0xf8-0xfb and its
2.5.1.1 ABNF admits only @user./@device./@resource., so a codec written to the
specification rejects it: Unmarshal failed with "unknown conditional-expression
token 0xfc" and the parser with "unknown attribute prefix".

The token is implemented in both directions by sechost.dll and advapi32.dll, which
parse "@token." into 0xfc and render 0xfc back to "@token.", and it is evaluated
by the kernel: ntoskrnl.exe's evaluator assigns it its own internal attribute
source class and reads it from the access token, not from the user-claims
collection that 0xf9 uses. It is therefore not a synonym for tokenUserAttr, and is
deliberately kept distinct.

Its wire encoding is identical to the other attribute tokens - token byte, DWORD
byte length, UTF-16 name - so the change is four small additions: the constant,
the prefix arm in parseAttribute, the serializer arm, and the token in the
decoder's attribute case. encode.go needed no change because it writes
Attribute.Token generically.

Serialization emits "@token." to match this package's existing capitalisation of
@user./@device./@resource. rather than Windows' all-caps rendering; parsing folds
case, so either form is accepted on input.

Author: p0dalirius

ace/condition/condition.go

@@ -46,6 +46,13 @@ const (
 	tokenUserAttr     byte = 0xf9
 	tokenResourceAttr byte = 0xfa
 	tokenDeviceAttr   byte = 0xfb
+	// tokenTokenAttr is a fifth attribute type that Windows implements but
+	// MS-DTYP 2.4.4.17.8 does not document, carrying the SDDL prefix "@TOKEN.".
+	// Its encoding is identical to the other attribute tokens. The kernel
+	// evaluator treats it as its own attribute source, read from the access
+	// token rather than from the user-claims collection that 0xf9 uses, so it is
+	// not a synonym for tokenUserAttr.
+	tokenTokenAttr byte = 0xfc
 
 	// Binary relational operators.
 	tokenEqual          byte = 0x80
@@ -194,7 +201,7 @@ type Node interface {
 
 // Attribute is an attribute-name operand (local or @User./@Resource./@Device.).
 type Attribute struct {
-	Token byte // one of tokenLocalAttr/tokenUserAttr/tokenResourceAttr/tokenDeviceAttr
+	Token byte // one of tokenLocalAttr/tokenUserAttr/tokenResourceAttr/tokenDeviceAttr/tokenTokenAttr
 	Name  string
 }
 

ace/condition/condition_test.go

@@ -218,3 +218,134 @@ func TestUnaryKeywordOperatorsRejectedInInfixPosition(t *testing.T) {
 		})
 	}
 }
+
+// TestTokenAttribute_0xfc covers the fifth attribute token, 0xfc, whose SDDL
+// prefix is "@TOKEN.". MS-DTYP 2.4.4.17.8 documents only 0xf8-0xfb and its
+// 2.5.1.1 ABNF admits only @user./@device./@resource., but Windows implements
+// 0xfc in both directions: sechost.dll and advapi32.dll parse "@TOKEN." into
+// 0xfc and render 0xfc back to "@TOKEN.", and the kernel evaluator gives it its
+// own attribute source class.
+//
+// Its wire encoding is identical to the other attribute tokens: the token byte,
+// a DWORD byte length, then the UTF-16 name.
+func TestTokenAttribute_0xfc(t *testing.T) {
+	// The token byte lands where the other attribute tokens do: straight after
+	// the 4-byte "artx" signature for a leading attribute operand.
+	raw, err := condition.Marshal(`(@TOKEN.foo == 1)`)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if len(raw) < 5 {
+		t.Fatalf("encoded condition too short: %s", hex.EncodeToString(raw))
+	}
+	if raw[4] != 0xfc {
+		t.Fatalf("attribute token = 0x%02x, want 0xfc (encoded: %s)", raw[4], hex.EncodeToString(raw))
+	}
+
+	// Serialization uses this package's existing capitalisation convention,
+	// matching @User./@Device./@Resource. rather than Windows' all-caps form.
+	got, err := condition.Unmarshal(raw)
+	if err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if got != `@Token.foo == 1` {
+		t.Fatalf("Unmarshal() = %q, want %q", got, `@Token.foo == 1`)
+	}
+}
+
+// TestTokenAttribute_PrefixIsCaseInsensitive checks that the @TOKEN. prefix folds
+// case like the three documented prefixes, and that every casing yields token 0xfc.
+func TestTokenAttribute_PrefixIsCaseInsensitive(t *testing.T) {
+	for _, expr := range []string{
+		`(@TOKEN.foo == 1)`, `(@token.foo == 1)`, `(@Token.foo == 1)`, `(@ToKeN.foo == 1)`,
+	} {
+		t.Run(expr, func(t *testing.T) {
+			raw, err := condition.Marshal(expr)
+			if err != nil {
+				t.Fatalf("Marshal(%q) error = %v", expr, err)
+			}
+			if raw[4] != 0xfc {
+				t.Fatalf("attribute token = 0x%02x, want 0xfc", raw[4])
+			}
+		})
+	}
+}
+
+// TestTokenAttribute_DecodeWindowsBlob decodes a hand-assembled payload of the
+// shape Windows produces — 0xfc, DWORD length, UTF-16 name — proving the decoder
+// no longer rejects the token. Before this was supported, Unmarshal failed with
+// "unknown conditional-expression token 0xfc".
+func TestTokenAttribute_DecodeWindowsBlob(t *testing.T) {
+	// artx | 0xfc len=6 "foo" | 0x04 int64(1) sign=none base=dec | 0x80 == | pad
+	blob, err := hex.DecodeString(
+		"61727478" + "fc06000000" + "66006f006f00" +
+			"04" + "0100000000000000" + "0302" + "80" + "00")
+	if err != nil {
+		t.Fatalf("bad test vector: %v", err)
+	}
+	got, err := condition.Unmarshal(blob)
+	if err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if got != `@Token.foo == 1` {
+		t.Fatalf("Unmarshal() = %q, want %q", got, `@Token.foo == 1`)
+	}
+}
+
+// TestTokenAttribute_RoundTripStable checks Marshal -> Unmarshal -> Marshal is
+// byte-stable for 0xfc across operand positions and operator kinds, and that it
+// composes with the documented attribute tokens.
+func TestTokenAttribute_RoundTripStable(t *testing.T) {
+	for _, expr := range []string{
+		`(@Token.foo == 1)`,
+		`(@Token.dept == "eng")`,
+		`(@Token.a == @Token.b)`,
+		`(@Token.a Any_of {1, 2})`,
+		`(@Token.a && @User.b)`,
+		`(@Token.flags == 0x10)`,
+		`(Exists @Token.foo)`,
+	} {
+		t.Run(expr, func(t *testing.T) {
+			first, err := condition.Marshal(expr)
+			if err != nil {
+				t.Fatalf("Marshal(%q) error = %v", expr, err)
+			}
+			text, err := condition.Unmarshal(first)
+			if err != nil {
+				t.Fatalf("Unmarshal() error = %v", err)
+			}
+			second, err := condition.Marshal("(" + text + ")")
+			if err != nil {
+				t.Fatalf("re-Marshal(%q) error = %v", text, err)
+			}
+			if hex.EncodeToString(first) != hex.EncodeToString(second) {
+				t.Fatalf("round-trip not byte-stable:\n first  = %s\n second = %s",
+					hex.EncodeToString(first), hex.EncodeToString(second))
+			}
+		})
+	}
+}
+
+// TestTokenAttribute_NotAliasOfUserAttr guards against implementing @TOKEN. as a
+// synonym for @USER.. They are separate tokens with separate value sources: the
+// kernel evaluator reads 0xfc from the access token and 0xf9 from the user-claims
+// collection, and assigns them different internal source classes.
+func TestTokenAttribute_NotAliasOfUserAttr(t *testing.T) {
+	tokenRaw, err := condition.Marshal(`(@Token.foo == 1)`)
+	if err != nil {
+		t.Fatalf("Marshal(@Token.) error = %v", err)
+	}
+	userRaw, err := condition.Marshal(`(@User.foo == 1)`)
+	if err != nil {
+		t.Fatalf("Marshal(@User.) error = %v", err)
+	}
+	if tokenRaw[4] == userRaw[4] {
+		t.Fatalf("@Token. and @User. encoded to the same token 0x%02x; they must differ", tokenRaw[4])
+	}
+	if userRaw[4] != 0xf9 {
+		t.Fatalf("@User. token = 0x%02x, want 0xf9", userRaw[4])
+	}
+	if text, _ := condition.Unmarshal(userRaw); text != `@User.foo == 1` {
+		t.Fatalf("@User. round-trip = %q, want %q", text, `@User.foo == 1`)
+	}
+}

ace/condition/decode.go

@@ -130,7 +130,7 @@ func decodeToken(data []byte) (Node, int, error) {
 		}
 		return &Composite{Items: items}, 5 + l, nil
 
-	case tokenLocalAttr, tokenUserAttr, tokenResourceAttr, tokenDeviceAttr:
+	case tokenLocalAttr, tokenUserAttr, tokenResourceAttr, tokenDeviceAttr, tokenTokenAttr:
 		s, n, err := decodeUTF16LenPrefixed(data[1:])
 		if err != nil {
 			return nil, 0, err

ace/condition/parser.go

@@ -425,6 +425,8 @@ func (p *parser) parseAttribute() (Node, error) {
 		return &Attribute{Token: tokenDeviceAttr, Name: name[len("@device."):]}, nil
 	case strings.HasPrefix(lower, "@resource."):
 		return &Attribute{Token: tokenResourceAttr, Name: name[len("@resource."):]}, nil
+	case strings.HasPrefix(lower, "@token."):
+		return &Attribute{Token: tokenTokenAttr, Name: name[len("@token."):]}, nil
 	case strings.HasPrefix(name, "@"):
 		return nil, fmt.Errorf("unknown attribute prefix in %q", name)
 	default:

ace/condition/serialize.go

@@ -111,6 +111,8 @@ func attributeText(a *Attribute) string {
 		return "@Device." + a.Name
 	case tokenResourceAttr:
 		return "@Resource." + a.Name
+	case tokenTokenAttr:
+		return "@Token." + a.Name
 	default:
 		return a.Name
 	}