Token and session specs

kacs_create_token and kacs_create_session take wire-format specs that describe what to mint. The specs are self-contained binary records that the kernel parses, validates, and turns into a token or session. This page covers both formats and the supporting claim-entry format used inside token specs.

Session spec #

The session spec is small. It identifies who is signing in and how.

Total size: variable. Minimum 15 bytes (smallest auth_pkg + smallest SID). Maximum 4096 bytes total.

Validation:

• logon_type must be a recognised value.
• auth_pkg_len must be reasonable (within size limit).
• user_sid must be well-formed.

The kernel constructs the session, assigns it a fresh session_id LUID (the syscall's return value), derives the logon SID S-1-5-5-{X}-{Y} from the session ID, and stamps created_at.

Token spec #

The token spec is substantially larger. The fixed header is 192 bytes; variable sections follow.

Fixed header (offsets 0–191) #

Each offset points into the variable section that follows. Length zero with offset zero means "absent". Offsets must point within the spec; the kernel rejects out-of-bounds offsets.

Variable sections #

After the 192-byte header, variable-length data follows. The offsets in the header point to records in this region. Each variable section has its own internal format:

Groups list (and the related restricted/device variants) #

[count:u32le]
[group1: sid_len:u32le, sid bytes, attributes:u32le]
[group2: same]
...

Each group entry is sid_len (u32) + sid bytes + attributes (u32). The attributes are the standard SE_GROUP_* flags (MANDATORY 0x01, ENABLED_BY_DEFAULT 0x02, ENABLED 0x04, OWNER 0x08, USE_FOR_DENY_ONLY 0x10, etc.).

Restricted SIDs and confinement capabilities #

Same format as groups but typically with attributes = 0 (the kernel ignores attributes on these).

User/device claims #

Multi-entry claim buffer:

[entry1_len:u32le][entry1 bytes]
[entry2_len:u32le][entry2 bytes]
...

Until the offset+length region is consumed. Each entry is one claim record.

Claim entry format (CLAIM_SECURITY_ATTRIBUTE_RELATIVE_V1) #

Each claim entry has a 16-byte header followed by variable data:

After the offsets array, the name string (UTF-16LE) and value records follow. Each value's format depends on value_type:

Default DACL #

A binary ACL in the standard format covered in Security descriptors. The DACL header plus its ACEs.

Supplementary GIDs #

An array of u32 little-endian GIDs.

Validation #

The kernel validates the token spec extensively:

• version must equal TOKEN_SPEC_VERSION (2 in v0.20).
• token_type must be 1 or 2.
• For Primary tokens (token_type = 1), impersonation_level must be 0 (Anonymous).
• integrity_level must be one of the defined RIDs.
• _reserved1 (elevation_type) must be 0.
• auth_id must reference an existing session.
• user_sid must be well-formed and reasonable.
• owner_sid_index and primary_group_index must be valid (0 = user_sid, 1+ = group at that index).
• Every offset must point within the spec; every length must fit; no overlapping regions.
• confinement_sid and isolation_boundary: isolation_boundary cannot be set without confinement_sid.
• Write-restricted tokens (encoded by the way restricted_sids and user_deny_only combine) must satisfy the user_deny_only constraint.
• ALL_APPLICATION_PACKAGES (S-1-15-2-1) MUST NOT appear in confinement_capabilities.
• The logon SID MUST NOT be supplied; the kernel injects it from the auth_id.

A failure at any check returns -EINVAL. The token is not created.

What the kernel adds #

The kernel sets some fields automatically after validation:

• token_id: a fresh LUID.
• modified_id: 0 at creation.
• created_at: current timestamp.
• source: the calling process's identity (typically "authd " or similar).
• The logon SID (derived from auth_id) is injected into the groups list with SE_GROUP_LOGON_ID set.

After all of this, the kernel returns a token fd with TOKEN_ALL_ACCESS.

Limits #

Per-spec maximums:

The kernel enforces these at parse time.

Comparing to runtime token state #

A token spec describes what to mint. The minted token's runtime state has the same fields plus a few the kernel adds (token_id, modified_id, created_at, source, the logon SID). The fields the spec sets are the fields visible to KACS_IOC_QUERY later — TokenUser returns the user SID, TokenGroups returns the groups, TokenPrivileges returns the privilege bitmasks, etc.

The wire format is the input; the runtime token is the output. Both have the same shape; the wire format is just the serialised version.

kacs_create_token receives just the spec #

The kacs_create_token syscall takes a pointer + length to the spec bytes. The spec is self-contained — every offset, every length, every value the kernel needs is in the buffer. There are no other parameters to the syscall beyond SeCreateTokenPrivilege (implicit, on the calling token).

This is what makes the token-creation API simple. The caller assembles the spec; the kernel validates and constructs. No multi-step protocol, no out-of-band parameters.