Permissions in the DFA

accept states, priority for AppArmor developers for security researchers

Every accepting state gets five masks - allow and deny and prompt and audit and quiet - computed one permission bit at a time from the accept nodes in the state. The score is priority times four plus the rule kind. Deny is then folded into allow and the result is written as rows of a permission table or as the older accept words. Priority and deny do not reach the kernel.

On the map: the dfa engine

▶ Watch this deck — 10 scenes, ~8 min

Worth seeing first

Part of journeys

01 What may a state do?

PERMISSIONS IN THE DFA /etc/demo/** r, audit deny @{HOME}/.ssh/** rw, /usr/bin/[a-z]* ix, < 0x10004> < 0x3800e> < 0x804201> accept nodes 35 37 34 allow deny prompt audit quiet permission table rows priority and deny are settled here; the kernel sees neither the three rules do not overlap: later scenes add a rule or two to the profile
Each of the three rules carries an accept node; the three accepting states 35, 37 and 34 get five masks each; states 35 and 34 point at rows of the permission table and the deny state 37 points at none

Accept nodes become five masks per state, and the masks become rows of a permission table. Rule priority and the deny mask are resolved in the parser and are not in the compiled policy.

The kernel walks the machine and stops in a state. What that state allows was decided long before, in the parser. This deck follows that decision. Each rule carries an accept node into the tree. The states that contain accept nodes get five masks computed from them: allow, deny, prompt, audit and quiet. And those masks are finally written as rows of a table that the state points into. Along the way, two things you wrote in the profile disappear: priorities are used up, and deny turns into the absence of allow. Our three rules don't overlap, so for the interesting cases we'll add a rule or two to demo's profile as we go.

Details and sources

Details

  • The profile (file demo3.sd):
abi <abi/5.0>,
include <tunables/global>
profile demo /usr/bin/demo {
  /etc/demo/** r,
  audit deny @{HOME}/.ssh/** rw,
  /usr/bin/[a-z]* ix,
}
  • Its accept nodes, from -D rule-exprs (parser of the AppArmor tree; the same with the tree's abi/5.0 feature set and with one that has the kernel's policy entries):
rule: /etc/demo/[^/\x00][^\x00]*  ->  ... priority=0 (0x10004/0)< 0x10004>
rule: /usr/bin/[a-z][^/\x00]*  ->  ... priority=0 (0x804201/0)< 0x804201>
rule: (/home/[^/\x00]*|/root)/\.ssh/[^/\x00][^\x00]*  ->  ... priority=0 deny (0x3800e/0)< 0x3800e>

Read more

02 What an accept node carries

MatchFlag rule: ... priority=0 deny (0x3800e/0)< 0x3800e> priority kind perms second mask xwraowner: bits 0 to 3 xwraother = owner << 14 tested in this order deny-> DenyMatchFlag prompt-> PromptMatchFlag no wildcard-> ExactMatchFlag anything else-> MatchFlag deny /b w, -> deny (0x2800a/2800a) audit deny /c w, -> deny (0x2800a/0) for a deny node the second mask means quiet one node per unique (priority, mode, exact, perms, audit); it sits in a state and has no followpos
The rule line of the deny rule taken apart into priority, kind, permission mask and second mask; the mask 0x3800e as write, read and append in an owner half and an other half; the four tests that choose the accept node class; for a deny node the second mask means quiet

UniquePermsCache::insert picks DenyMatchFlag, PromptMatchFlag, ExactMatchFlag or MatchFlag (aare_rules.h:78-101). For a deny node the second mask is quiet: deny /b w, is (0x2800a/2800a), audit deny /c w, is (0x2800a/0).

An accept node is small: a priority, a permission mask, an audit mask, and a class. The mask has two halves, owner in the low bits and other fourteen bits up, each with exec, write, read, append and a few more. The class is chosen by four tests in order. A deny rule gets a DenyMatchFlag, a prompt rule a PromptMatchFlag, an allow rule with no wildcard an ExactMatchFlag, and anything else the plain MatchFlag. Watch the second mask. For an allow rule it means audit. For a deny rule the front end has already flipped it, so it means quiet. A plain deny passes its permissions there, because its denials aren't logged, and audit deny passes zero.

Details and sources

Details

  • Node *insert(int priority, rule_mode_t mode, perm32_t perms, perm32_t audit, bool exact_match) on UniquePermsCache (aare_rules.h:78-101); the key is UniquePerm (aare_rules.h:39-59).
  • The classes are at expr-tree.h:1150-1205. The third constructor argument of DenyMatchFlag is the quiet mask (expr-tree.h:1193).
  • An accept node is an ImportantNode with an empty follow set (expr-tree.h:1118-1121, expr-tree.h:1144-1148).
  • What the front end passes for a path rule (parser_regex.c:675-690): a deny rule passes perms without the link and change_profile bits, and the same mask as the second argument unless the rule says audit; an allow or prompt rule passes perms as the second argument when the rule says audit. The inversion for deny is in the front end (rule.h:430-433).
  • The dump field < 0x3800e> prints the permission mask only (expr-tree.h:1157).
  • Bit values: immunix.h:25-44. Exec is 0x1, write 0x2, read 0x4, append 0x8; the other half is the same shifted left by 14. 0x2800a is write with its implied append in both halves.

03 priority*4 + kind, one bit at a time

pri_update_perm 0 1 2 3 4 5 6 7 8 9 10 11 priority 0 priority 1 priority 2 prompt allow exact exec deny allow priority=1 allow beats deny -4004 -4004 -4004 -4004 -4004 -4004 -4004 -4004 ... x 32 one score per bit, start MIN_INTERNAL_PRIORITY*4 lower than the registerskip higherclear the bit in all five masks equaladd class markers: 1001*4+1 = 4005 and -1001*4+1 = -4003
A number line of scores grouped in fours by priority: within priority 0, prompt scores 0, allow 1, an exact rule on an exec bit 2 and deny 3; an allow at priority 1 scores 5 and beats the deny; each state has one score register per bit, starting at -4004; a lower score is skipped, a higher one clears and takes over, an equal one adds

Score per bit: priority << 2 plus 3 (deny), 2 (exact node on an exec bit), 1 (allow), 0 (prompt) (hfa.cc:1536-1554). Lower is skipped, higher clears and replaces, equal accumulates. This is the last use of priority.

When a state holds several accept nodes, who wins? There's a score, per permission bit. Take the node's priority, shift it left by two, and add its kind: three for deny, two for an exact rule if the bit is an exec bit, one for any other allow, zero for prompt. One step of priority outranks all of that: an allow at priority one scores five, above a deny at zero. Each state keeps thirty-two registers, one per bit. A node that scores lower than the register is skipped for that bit. One that scores higher wipes the bit from all five masks and takes over. Equal scores simply add up.

Details and sources

Details

  • perms_t::perms_t (hfa.cc:1661-1708, declared at hfa.h:54) and pri_update_perm (hfa.cc:1529-1654). The steps:
  • every bit gets a score register that starts at MIN_INTERNAL_PRIORITY*4, which is -4004 (hfa.cc:1665);
  • for each accept node, the bits of perms | audit are visited; for the file DFA the exec type bits are not scored as bits of their own (hfa.cc:1683-1685);
  • the score is priority << 2 plus 3 for a deny node, 2 for an exact node on an exec bit, 1 for any other allow, 0 for a prompt node (hfa.cc:1537-1554);
  • a register higher than the score: the node is skipped for this bit; lower: the score is stored and the bit is cleared from allow, deny, prompt, audit and quiet (hfa.cc:1556-1582);
  • then the node is applied by kind (hfa.cc:1585-1651): deny sets deny and quiet and clears allow, audit and prompt; exact replaces the exec type bits and sets allow and audit; allow sets allow and audit; prompt sets prompt and audit.
  • A rule's priority is between -1000 and 1000; the class markers of policydb use -1001 and 1001 (immunix.h:198-207).
  • Equal scores accumulate: two allow rules of one priority OR their bits. An allow and a deny of one priority are never equal.
  • The exact bonus applies to exec bits only.
  • The comment at hfa.cc:1542-1543: this is the last use of priority. The kernel has no field for one (kernel source searched, not run).
  • Known discrepancy: perm32_t mask = 1 << i with i up to 31 shifts a signed int into the sign bit (hfa.cc:1533); no wrong result is known.

Read more

04 Three rules meet in one state

-D dfa-perms-build /etc/demo/** rw,deny /etc/demo/*.conf w,priority=10 allow /etc/demo/override.conf w, override.conf write bit 1glob allow 3deny 41priority 10 [1]=1 vs. 41 mask: 2 xmask: 0 amask: 2[1]=1 < 41 clearing mask: 2 from 3800e/0 -> 3800c/0[1]=41 <= 41 exact 2/0 [1]=41 vs. 3 mask: 2 xmask: 0 amask: 2[1]=41 > 3 SKIPPING 2800a/2800a any other *.conf: 1 3 (0x 10004/2800a//0/0/2800a) read allowed; write denied and quiet the order of the three nodes changes between runs; the result does not
Three overlapping rules meet in the state for /etc/demo/override.conf: on the write bit the glob allow scores 1, the priority 10 allow scores 41 and takes the bit, and the deny with score 3 is skipped; for any other conf file the deny wins and write is denied and quiet

/etc/demo/override.conf: glob allow 1, priority=10 allow 41, deny 3: the deny is skipped for the write bit. Other *.conf files: (0x 10004/2800a//0/0/2800a), write denied and quiet.

Give demo three rules that overlap: read and write under its configuration directory, a deny for writing conf files, and one override at priority ten. The state reached by override.conf holds all three accept nodes, and the dfa-perms-build dump prints every comparison. Bit one is write. The register holds one, from the glob allow. Along comes the priority ten rule with forty-one. One is less, so the bit is cleared from the masks and the new rule takes it. Then the deny arrives with three. Forty-one is greater: skipping. Write stays allowed. For every other conf file the override isn't in the state, the deny's three beats the allow's one, and you get read allowed, write denied and quiet.

Details and sources

Details

  • The profile on this slide adds overlapping rules to demo: /etc/demo/** rw,, deny /etc/demo/*.conf w,, priority=10 allow /etc/demo/override.conf w,. The trace is from -D dfa-perms-build, parser of the AppArmor tree, abi/5.0 feature set. The slide leaves out the pointer that begins each line as printed:
0x62eb090db8e0[1]=1 vs. 41 mask: 2 xmask: 0 amask: 2
  0x62eb090db8e0[1]=1 < 41 clearing mask: 2 from 3800e/0 -> 3800c/0
  0x62eb090db8e0[1]=41 <= 41 exact 2/0
0x62eb090dcbb0[1]=41 vs. 3 mask: 2 xmask: 0 amask: 2
  0x62eb090dcbb0[1]=41 > 3 SKIPPING 2800a/2800a
  • The order of the three nodes changes between runs; the result does not. The accept nodes of a state are visited in the order of their addresses, like the groups of the -D expr-tree dump. Two later runs (one with a feature set that has the kernel's policy entries, one with abi/5.0) took the deny first: [1]=-4004 vs. 3, then [1]=3 vs. 41 with clearing mask: 2 from 0/0 -> 0/0, then [1]=41 > 1 SKIPPING 3800e/0 for the glob allow. -4004 is the start value of a register. The computed set is (0x 3800e/0//0/0/0) in every order.
  • [1] is the bit number: bit 1 is write. The lines are printed at hfa.cc:1558-1651 and hfa.cc:1670-1702.
  • The override rule is an exact node, yet it scores 41 and not 42: write is not an exec bit.
  • For any other *.conf file the dump has clearing mask: 2 from 3800e/0 -> 3800c/0, then deny 2/2, and the state is (0x 10004/2800a//0/0/2800a). The tuple is allow/deny/prompt/audit/quiet, printed with a blank after 0x and a doubled slash. 0x2800a is write with its implied append in both halves.
  • The dump for this profile has 97 "Building Perms" blocks, 76 of them for one accept node: permissions are computed for every transition target before the duplicate check (hfa.cc:340, hfa.cc:349-351).
  • Known discrepancy: the dfa-perms-build lines for the implied mmap bit have no line end (hfa.cc:1505, hfa.cc:1509, hfa.cc:1517, hfa.cc:1521).

Read more

05 For exec, the exact path wins

ExactMatchFlag /usr/bin/[a-z]* ix,/usr/bin/demo-helper Px -> demo-helper, /usr/bin/demo-helper exec bit 1glob: inherit 2exact: Px exact: clear the exec bit and its type bits, install its own Perms Table size: 6(0x200/0x0/0x0//0x0/0x0//0)...(0x10201/0x0/0x0//0x0/0x0//i0)...(0x201/0x0/0x0//0x0/0x0//p0)... the glob: inherit, plus mmap demo-helper: named target 0, no mmap exact = no star, plus, . or negated set: /usr/bin/[de]emo is exact, /usr/bin/dem? is not
A glob exec rule with inherit and an exact exec rule with a named profile meet in the state for /usr/bin/demo-helper: on the exec bit the glob scores 1 and the exact rule 2, so the exact rule replaces the exec type; the permission table has a row with i0 for the glob and a row with p0 for the helper

An ExactMatchFlag scores priority*4 + 2 on exec bits and replaces the glob's exec type (hfa.cc:1549-1551, 1606-1625). Rows: glob 0x10201 ... i0, demo-helper 0x201 ... p0.

Exec permissions have a twist: an exec rule doesn't just allow, it says how. Inherit, or switch to a profile. So the scoring gives an exact rule one extra point on exec bits. Here demo may run anything in the bin directory under its own profile, and one named helper under the helper's profile. The state for demo-helper holds both nodes. The glob scores one, the exact rule two, so it clears the exec bit and its type bits and installs its own. The permission table shows both outcomes: a row with i0, inherit, for the glob, and a row with p0, the first named target, for the helper.

Details and sources

Details

  • The profile on this slide: /usr/bin/[a-z]* ix, and /usr/bin/demo-helper Px -> demo-helper,. The table is from -D compressed-dfa, parser of the AppArmor tree, abi/5.0 feature set; the dump has six rows (owner and other for each of three sets), and the slide shows one row of each pair.
  • An ExactMatchFlag on an exec bit scores one more than a plain allow (hfa.cc:1549-1551); it clears what the glob rule set for the exec bit and its type bits and installs its own (hfa.cc:1606-1625).
  • "Exact" is decided per rule in add_rule_vec (aare_rules.cc:98-105): a character class is not a wildcard for this test, ? is.
  • 0x10201 is AA_MAY_EXEC, AA_MAY_GETATTR and AA_EXEC_MMAP (0x10000). The xindex i0 is AA_X_INHERIT with index 0; p0 is a table transition to entry 0 (policy_compat.cc:48-49, policy_compat.cc:143-144, perms.h:130-148).
  • The implied mmap bit for ix is added unless a higher score already decided that bit (hfa.cc:1497-1524, hfa.cc:1697-1699).
  • The fixture parser/tst/simple_tests/xtrans/minimize-x-conflict.sd (/b px,, /* Pixr,, /a Cx -> foo,, #=EXRESULT PASS) passes because the exact rules dominate the glob.

06 Two exec modes, same score: refused

CONFLICT /usr/bin/* ix,/usr/bin/d* Px, overlapping globs /usr/bin/d... 1 1 inherit vs profile is_merged_x_consistent -> throw profile has merged rule with conflicting x modifiers ERROR processing regexs for profile t, ... exit status 255 /usr/bin/demo ix,/usr/bin/demo Px, identical paths: the front end's rule merge profile t: has merged rule /usr/bin/demo with conflicting x modifiers ERROR merging rules for profile t, ... exit status 1 fix: make one rule exact, or give one a higher priority
Two cases of conflicting exec modes: overlapping globs with equal scores make the DFA constructor throw and the parser exits with status 255; identical paths are caught earlier by the rule merge of the front end, with a message that names the path and exit status 1

Overlapping patterns: profile has merged rule with conflicting x modifiers from perms_t::perms_t (hfa.cc:1703-1707), exit status 255. Identical paths: profile t: has merged rule /usr/bin/demo with conflicting x modifiers from the front end (parser/block_rules.cc:325), exit status 1.

And when neither rule is exact? Two globs that overlap, one says inherit, one says switch profile, same priority, same score. There's no way to pick, and the parser doesn't guess. Before a node sets an exec bit that's already allowed, it compares the type bits, and if they differ the constructor throws. You get "profile has merged rule with conflicting x modifiers", and exit status two fifty-five. If the two paths are identical, the front end's rule merge catches it first, names the path, and exits with status one. Either way the cure is the same: make one rule exact, or give one a higher priority, so its score clears the other first.

Details and sources

Details

  • Before an allow, exact or prompt node sets an exec bit that is already allowed, is_merged_x_consistent compares the exec type bits (hfa.cc:1610-1615, hfa.cc:1632-1637, hfa.cc:1643-1648; the function is at immunix.h:171-186). A difference makes the constructor print the message and throw (hfa.cc:1703-1707); the caller then prints ERROR processing regexs for profile t, failed to load (parser_regex.c:1277).
  • Both cases were run with the parser of the AppArmor tree (abi/5.0 feature set), in a profile named t. The complete messages:
profile has merged rule with conflicting x modifiers
ERROR processing regexs for profile t, failed to load
profile t: has merged rule /usr/bin/demo with conflicting x modifiers
ERROR merging rules for profile t, failed to load
  • The second pair comes from the rule merge of the front end (block_rules.cc:325).
  • Different priorities avoid the conflict: the higher score clears the lower one first.
  • Known discrepancy: the two messages and exit statuses differ for the same mistake, and the first names neither the profile's rules nor a line.

Read more

07 What becomes of a deny rule

DENY /e rw, deny /e w, audit deny @{HOME}/.ssh/** rw, perms_t allow:10004 deny:2800a quiet:2800a allow:0 deny:3800e quiet:0 apply_and_clear_deny allow:10004 deny:0 quiet:2800a allow:0 deny:0 quiet:0= a state with no rule at all allow &= ~deny; prompt &= ~deny; deny = 0 table row (0x244/0x0/0x0//0x0/0x317a//0)read allowed, deny 0, quiet 0x317a (0x200/0x0/0x0//0x0/0x0//0)the row of "no match" the kernel sees: the bit absent from allow, and maybe a quiet bit never a deny bit from this compiler known discrepancy: with -O no-filter-deny states stay apart by deny mask, and the rows still do not contain it
Two deny rules followed through three stops: the masks of the state, the filter deny pass that subtracts deny from allow and clears it, and the table row; a plain deny ends as read allowed with a quiet bit, an audit deny ends as the row of no match; the kernel never receives a deny bit from this compiler

apply_and_clear_deny: allow &= ~deny; prompt &= ~deny; deny = 0 (hfa.h:106-130). The table writer never sets a deny bit (policy_compat.cc:160-244): deny reaches the kernel as "absent from allow" plus, for a plain deny, a quiet bit.

A deny rule makes a deny mask in the state, and during scoring it knocks the bit out of allow. Then, by default, a pass called filter deny runs: allow and not deny, prompt and not deny, and the deny mask is set to zero. What's left is the quiet mask. So a plain deny survives as: not allowed, and don't log it. Our audit deny rule has no quiet bits, so after the filter its state is all zeroes, the same as a path no rule mentions. The kernel has a deny field and checks it, but no row gets a deny bit: from this compiler it's always zero.

Details and sources

Details

  • The five masks of a state: perm32_t allow, deny, prompt, audit, quiet (hfa.h:176).
  • apply_and_clear_deny (hfa.h:106-130): allow &= ~deny; prompt &= ~deny; allow |= deny & AA_COMPAT_CONT_MATCH; deny = 0. Audit and quiet are not changed. It returns true when the state is no longer accepting.
  • When it runs: always for a DFA without extended permissions (xmatch, and every DFA when permstable32_version < 2); otherwise when filter-deny is set, which is the default, with a TODO to remove it (aare_rules.cc:273-278, parser_common.c:125-129).
  • Six rules in one profile, -D dfa-uniq-perms (parser of the AppArmor tree, abi/5.0 feature set; the path notes are added here):
allow:0 deny:0 audit:0 quiet:0 prompt:10004            /d  prompt /d r,
allow:0 deny:2800a audit:0 quiet:0 prompt:0            /c  audit deny /c w,
allow:0 deny:2800a audit:0 quiet:2800a prompt:0        /b  deny /b w,
allow:10004 deny:0 audit:10004 quiet:0 prompt:0        /a  audit /a r,
allow:10004 deny:2800a audit:0 quiet:2800a prompt:0    /e  /e rw, and deny /e w,
  • For that profile the default compile gives 16 table rows and 7 states; -O no-filter-deny gives 12 rows and 8 states. The deny column is 0 in both. For the three-rule example it is 22 states against 38.
  • The upper lane is the two-rule profile /e rw, and deny /e w,, run with a feature set that has the kernel's policy entries: state {3}(0x 10004/2800a//0/0/2800a), Perms Table size: 6, the state's row (0x244/0x0/0x0//0x0/0x317a//0) at accept index 2, and rows 2 to 5 all equal. Quiet 0x317a is the write bit after the same expansion that turns read into 0x244.
  • The table writer has no code that sets aa_perms::deny (policy_compat.cc:160-190, policy_compat.cc:199-244); map_perms_to_accept does not pass the deny mask on (hfa.h:132-138).
  • In the kernel, unpack_perm reads a deny field (policy_unpack.c:911) and verify_perm rejects a row with a bit in both allow and deny (policy_unpack.c:1511).
  • Kernel statements are read from the kernel source and were not run.
  • Known discrepancy: a deny rule cannot be told from "no rule" in the permission table, with or without filter-deny.
  • Known discrepancies, by title: "-O filter-deny leaves unused duplicate permission table entries"; "Kernel: an audit deny file rule in a complain-mode profile is allowed and logged ALLOWED"; "A deny block around an audit deny rule drops the audit".
  • Not determined: why filter-deny is still the default; whether the kernel treats quiet without deny as the compiler assumes in every hook.

08 The old encoding: three words per state for AppArmor developers

accept1 accept2 accept1 = allowbit 0bit 31 owner permissions owner exec type, index other permissions other exec type, index onexec, change_profile accept2 = PACK_AUDIT_CTL(audit, quiet)bit 0bit 31 owner audit owner quiet other audit other quiet audit in place, quiet 7 bits higher accept3 = prompt computed, not written used when permstable32_version < 2, and always for xmatch: its last state in the example has accept1 = 1, exec
The 32-bit accept1 word of the old encoding: bits 0 to 6 owner permissions, 7 to 13 owner exec type and index, 14 to 20 other permissions, 21 to 27 other exec type and index, bit 30 onexec and bit 31 change_profile; accept2 packs audit and quiet; accept3 is prompt and is not written

map_perms_to_accept: accept1 = allow, accept2 = PACK_AUDIT_CTL(audit, quiet), accept3 = prompt (hfa.h:132-138). File layout of accept1: bits 0-6 and 14-20 permissions, 7-13 and 21-27 exec type and index, 30 onexec, 31 change_profile.

The older way to write a state's answer down is three words per state. Accept1 is the allow mask, laid out in halves: seven bits of owner permissions, seven bits of owner exec type and table index, the same again for other, and two bits at the top for onexec and change_profile. Accept2 packs audit and quiet into one word. Accept3 is prompt, which is computed but has no table to go into. The kernel takes these words and builds its own permission entries from them when the policy loads. The attachment DFA always uses this form.

Details and sources

Details

  • map_perms_to_accept (hfa.h:132-138): accept1 = allow, accept2 = PACK_AUDIT_CTL(audit, quiet), accept3 = prompt.
  • PACK_AUDIT_CTL keeps bits 0-6 and 14-20 of each mask and puts quiet 7 bits higher (immunix.h:123-127).
  • The layout of accept1 for the file DFA: policy_compat.cc:71-119; 4 bits of exec index (policy_compat.cc:43).
  • The words are written into the tables when permstable32_version < 2: the accept table holds accept1 and the accept2 table holds accept2 (chfa.cc:129-137, chfa.cc:160-164).
  • In the example, the accept table of the attachment DFA has the value 1 for state 14, the state at the end of /usr/bin/demo (decoded from the -S output made with a feature set that has the kernel's policy entries).
  • In the kernel: without a perms struct both tables are expected (policy_unpack.c:1002); the kernel builds its permission table with aa_compat_map_xmatch, aa_compat_map_policy or aa_compat_map_file (policy_compat.c:302) and rewrites the accept table to state numbers (remap_dfa_accept, policy_compat.c:288).
  • Kernel statements are read from the kernel source and were not run.
  • Not determined: how a prompt rule reaches a kernel without the permission table (policy/perms_compatprompt, parser_main.c:1768).

09 The permission table

-D compressed-dfa Perms Table size: 8(allow/deny/prompt//audit/quiet//xindex)[0](0x200/0x0/0x0//0x0/0x0//0)[1](0x200/0x0/0x0//0x0/0x0//0)[2](0x200/0x0/0x0//0x0/0x0//0)[3](0x200/0x0/0x0//0x0/0x0//0)[4](0x244/0x0/0x0//0x0/0x0//0)[5](0x244/0x0/0x0//0x0/0x0//0)[6](0x10201/0x0/0x0//0x0/0x0//i0)[7](0x10201/0x0/0x0//0x0/0x0//i0) no match: owner, other the deny set after filtering: same as no match, unused read 35 accept = 4 0x244 = read + open + getattr ix 34 accept = 6 0x10201 = exec + getattr + mmap, xindex i0 perms[accept[state]] for the owner, perms[accept[state] + 1] otherwise when accept2[state] has the owner flag
The eight rows of the permission table of the three rules: rows 0 and 1 for no match, rows 2 and 3 for the filtered deny set and unused, rows 4 and 5 read with state 35 pointing at row 4, rows 6 and 7 exec with inherit with state 34 pointing at row 6; the kernel takes the row at accept for the owner and the next row otherwise

compute_perms_table (hfa.cc:1423-1458): one aa_perms row per unique permission set, two for the file DFA. Example: 8 rows; state {35} has accept 4 (0x244), state {34} accept 6 (0x10201, i0). Each row is computed through the three accept words of the older format (hfa.cc:1412-1420).

A state's answer is stored as a row of a table. compute_perms_table writes one row per distinct permission set, or for the file DFA two rows, owner then other. Here's the table for demo's three rules: eight rows. Rows zero and one are the non-matching state. Two and three belonged to the deny rule; they're now identical to no match, and nothing points at them. Four and five are the r permission. Six and seven are our exec rule. Each state's accept entry is a row number: four for the state under the demo directory, six for the exec state. The kernel adds one when the file isn't yours.

Details and sources

Details

  • compute_perms_table (hfa.cc:1423-1458) and compute_perms_table_ent (hfa.cc:1412-1420). The table has uniq_perms.size() rows, times 2 for the file DFA (hfa.cc:1427-1432). Row 0 (and 1) is the set of the non-matching state; the others follow the order of uniq_perms (hfa.cc:1437-1442). The start and non-matching states get index 0 (hfa.cc:1433-1435, hfa.cc:1445-1457).
  • The dump on the slide is from the three-rule example, -D compressed-dfa, parser of the AppArmor tree; it is the same with the tree's abi/5.0 feature set and with one that has the kernel's policy entries. As printed, every row continues with accept1: 0x, accept2: 0x; the row numbers are added on the slide.
  • File rows go through map_old_perms (policy_compat.cc:41-65, policy_compat.cc:127-190): read adds getattr and open; write adds setattr, create, delete, chmod, chown and open; 0x10 is link; 0x20 is lock and link subset; 0x40 is exec mmap; AA_MAY_GETATTR is always set; bit 31 is AA_MAY_CHANGE_PROFILE and bit 30 AA_MAY_ONEXEC; xindex comes from the exec type bits.
  • policydb rows (policy_compat.cc:192-244): the owner half is kept, the other half is moved by map_other, AA_MAY_LOCK is always added, AA_COMPAT_CONT_MATCH becomes AA_CONT_MATCH. The two policydb rows of the example are 0x8000 and 0x8004.
  • Used when permstable32_version >= 2; version 1 is treated as absent (aare_rules.cc:200, aare_rules.cc:318-320, parser_main.c:1779-1784). With version 3 the file DFA also writes accept2 = 1 on every state except 0 and 1 (chfa.cc:118-122, chfa.cc:158-159).
  • prompt &= ~(allow | deny) is applied per file row and not for policydb rows (policy_compat.cc:172, policy_compat.cc:188). The fields subtree, cond, kill, complain, hide, tag and label are always 0 from this compiler.
  • In the kernel: unpack_perms_table (policy_unpack.c:901), aa_lookup_perms (policy.h:156), aa_lookup_condperms, which adds 1 for a non-owner when accept2 has ACCEPT_FLAG_OWNER (file.c:194), and verify_perm (policy_unpack.c:1511).
  • Kernel statements are read from the kernel source and were not run.
  • Errors: permission not in permission table map and permission not in idx table map, thrown as std::runtime_error (hfa.cc:1452-1454).
  • Known discrepancy: rows that filter deny made unused or equal stay in the table; by title, "-O filter-deny leaves unused duplicate permission table entries".
  • Known discrepancy: those two std::runtime_errors are not caught by create_chfa.

10 Where to go from here

ROADS Minimisationstates with equal masks can merge Table compressionthe accept table The binary policy formatthe 14 fields of a row Rule prioritythe ordering rule allow and denythe profile's side Exec modesinherit, profile, child
Roads from this deck: minimisation, table compression and the binary policy format, the syntax decks on priority, allow and deny and exec modes, and matching at run time

Next: minimisation, table compression, the binary policy format. The language side: rule priority, allow and deny, the audit qualifier, exec modes. The kernel side: matching at run time.

So a state's answer is five masks, decided one bit at a time by priority times four plus kind. Exact rules win exec. Equal scores with different exec modes are refused. Deny is folded away. And the result is a table row, or the old accept words. The minimization deck uses exactly these masks to decide which states may merge. Table compression and the binary policy deck show where the accept table and the rows are stored. And if you want the same story told from the profile's side, priority, allow and deny, and exec modes each have a deck.

Details and sources

Details

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run (-Q -K with the -D and -O options shown), with nothing loaded into a kernel. The dumps were made with the tree's abi/5.0 file as the kernel feature set unless a row says "kernel policy entries", which means a feature set with the policy entries the kernel exports; the permission table of the three-rule example is the same under both. "code" means the parser source, or the kernel source, was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.

Accept nodes

Key: (priority, mode, exact, perms, audit) (aare_rules.h:39-59) (code).

ClassChosen when (tested in this order)Kind in the score
DenyMatchFlagthe rule is a deny rule3
PromptMatchFlagthe rule is a prompt rule0
ExactMatchFlagan allow rule whose tree has no star, plus, any-char or negated set2 on exec bits, 1 otherwise
MatchFlagany other allow rule1
Ruleperms argumentsecond argument
allowthe permissionsthe permissions when the rule says audit, else 0 (audit)
promptthe permissionsthe permissions when the rule says audit, else 0 (audit)
denythe permissions, without the link and change_profile bitsthe same mask (quiet)
audit denythe same0 (not quiet)

Code: aare_rules.h:78-101, parser_regex.c:675-690. Tree: deny /b w, prints deny (0x2800a/2800a), audit deny /c w, prints deny (0x2800a/0).

The score

  • score = priority*4 + kind, per permission bit (hfa.cc:1537-1554) (code).
  • Registers start at -4004 (hfa.cc:1665). A lower score is skipped; a higher one clears the bit from all five masks and is applied; an equal one is applied on top (hfa.cc:1556-1582) (code).
KindSetsClears
denydeny, quiet (from the node's second mask)allow, audit, prompt
exact, on an exec bitallow, audit, and the exec type bitsthe exec type bits of the loser
allowallow, audit
promptprompt, audit
  • For the file DFA, ix adds the mmap bit unless a higher score already decided that bit (hfa.cc:1497-1524) (code).
  • Class markers of policydb score 4005 (priority 1001) and -4003 (priority -1001) (tree).

The five masks

MaskMeaning
allowpermitted
denyrefused by a deny rule
promptask user space
auditlog when used
quietdo not log the denial

Dumps print the tuple as (0x 10004/2800a//0/0/2800a): allow/deny/prompt/audit/quiet, with a blank after 0x and a doubled slash (hfa.h:58-68). Six rules in one profile, -D dfa-uniq-perms (tree; path notes added):

allow:0 deny:0 audit:0 quiet:0 prompt:10004            /d  prompt /d r,
allow:0 deny:2800a audit:0 quiet:0 prompt:0            /c  audit deny /c w,
allow:0 deny:2800a audit:0 quiet:2800a prompt:0        /b  deny /b w,
allow:10004 deny:0 audit:10004 quiet:0 prompt:0        /a  audit /a r,
allow:10004 deny:2800a audit:0 quiet:2800a prompt:0    /e  /e rw, and deny /e w,

Exec

  • Exact: no star, plus, any-char or negated set in the rule's tree; a character class is allowed, ? is not (aare_rules.cc:98-105) (code).
  • An exact rule replaces the exec type of a glob rule of the same priority (hfa.cc:1606-1625) (code, tree).
  • is_merged_x_consistent (immunix.h:171-186) compares the exec type bits before an exec bit that is already allowed is set again (code).
  • Fixture: parser/tst/simple_tests/xtrans/minimize-x-conflict.sd.

filter-deny

  • allow &= ~deny; prompt &= ~deny; allow |= deny & AA_COMPAT_CONT_MATCH; deny = 0 (hfa.h:106-130) (code).
  • Forced when permstable32_version < 2, so always for xmatch; otherwise on by default (aare_rules.cc:273-278) (code).
ProfileDefault-O no-filter-deny
the six rules above16 table rows, 7 states12 table rows, 8 states
the three-rule example22 states38 states

Tree. The deny column of the table is 0 in every case.

Old encoding

Bits of accept1 (file DFA)Meaning
0-6owner permissions
7-13owner exec type and table index
14-20other permissions
21-27other exec type and table index
30onexec
31change_profile
  • accept2 = PACK_AUDIT_CTL(audit, quiet): bits 0-6 and 14-20 of audit in place, the same bits of quiet 7 higher (immunix.h:123-127) (code). accept3 = prompt is computed and not written (code).
  • The kernel builds its own permission entries from the two words when the policy has no permission table (policy_compat.c:302) (code).
  • The permission table does not replace these words inside the parser. Each row is computed from the state's perms_t through accept1, accept2 and accept3 and then through compute_fperms_user and compute_fperms_other to an aa_perms row (compute_perms_table_ent, hfa.cc:1412-1420), so a row can say only what the old words could (code).

Permission table

Old bitNew bits in the row
read 0x4read, getattr, open
write 0x2write, setattr, create, delete, chmod, chown, open
0x10link
0x20lock, link subset
0x40exec mmap
exec 0x1exec, with xindex from the exec type bits
alwaysgetattr
  • One row per unique permission set; for the file DFA two rows, owner then other. A state's accept entry is the row index (hfa.cc:1423-1458) (code).
  • Version 2 and later of permstable32 use the table; with version 3 the file DFA also writes accept2 = 1 on every state except 0 and 1 (code).
  • The three-rule example, file DFA (tree, the same under both feature sets; row numbers added):
Perms Table size: 8
(allow/deny/prompt//audit/quiet//xindex)
[0] (0x200/0x0/0x0//0x0/0x0//0)       no match, owner
[1] (0x200/0x0/0x0//0x0/0x0//0)       no match, other
[2] (0x200/0x0/0x0//0x0/0x0//0)       the deny set after filtering, owner
[3] (0x200/0x0/0x0//0x0/0x0//0)       the deny set after filtering, other
[4] (0x244/0x0/0x0//0x0/0x0//0)       r, owner
[5] (0x244/0x0/0x0//0x0/0x0//0)       r, other
[6] (0x10201/0x0/0x0//0x0/0x0//i0)    ix, owner
[7] (0x10201/0x0/0x0//0x0/0x0//i0)    ix, other
  • Its policydb table has two rows, 0x8000 and 0x8004 (tree, kernel policy entries).
  • Kernel lookup: perms[accept[state]], plus 1 for a non-owner when accept2[state] has the owner flag (file.c:194) (code).

Errors

MessageFromExit status
profile has merged rule with conflicting x modifiershfa.cc:1703-1707followed by the next line
ERROR processing regexs for profile %s, failed to loadparser_regex.c:1277255
profile %s: has merged rule %s with conflicting x modifiersblock_rules.cc:325followed by the next line
ERROR merging rules for profile %s, failed to loadthe front end1
permission not in permission table map, permission not in idx table maphfa.cc:1452-1454std::runtime_error, not reproduced

Messages and statuses of the first four rows: tree.

Known discrepancies

  • A deny rule cannot be told from "no rule" in the permission table, with or without filter-deny (tree).
  • Unused duplicate rows stay in the table; by title: "-O filter-deny leaves unused duplicate permission table entries" (tree).
  • The dfa-perms-build lines for the implied mmap bit have no line end (tree).
  • 1 << i with i up to 31 on a signed int (hfa.cc:1533) (code).
  • Two different messages and exit statuses for the same exec conflict (tree).
  • By title: "Kernel: an audit deny file rule in a complain-mode profile is allowed and logged ALLOWED"; "A deny block around an audit deny rule drops the audit".

Not determined

  • How a prompt rule reaches a kernel without the permission table.
  • Whether the kernel treats quiet without deny the way the compiler assumes in every hook.
  • Why filter-deny is still the default.

Roads from here

START HERE

FILE ACCESS

QUALIFIERS

IN THE KERNEL

THE DFA ENGINE · libapparmor_re