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
- Building the DFA — the states that accept nodes end up in
- allow and deny — deny overriding allow, seen from the profile
- Rule priority — rule priority, which the masks are decided by
Part of journeys
- From profile text to kernel tables, step 9 of 13 · previous: Building the DFA · next: Minimisation
- How a rule becomes a permission, step 9 of 12 · previous: Rule priority · next: The binary policy format
01 What may a state do?
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'sabi/5.0feature set and with one that has the kernel'spolicyentries):
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>
- All of the computation is in hfa.cc:1490-1708.
- Seen the machine walked? How the kernel checks an access has scenes on where the path ends and on owner, other and deny.
Read more
- wiki: TechnicalDoc_HFA_permissions: design intent, marked draft by its authors; where it and the code differ, this deck follows the code.
- Rule priority, How the kernel checks an access.
02 What an accept node carries
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)onUniquePermsCache(aare_rules.h:78-101); the key isUniquePerm(aare_rules.h:39-59).- The classes are at expr-tree.h:1150-1205. The third constructor argument of
DenyMatchFlagis the quiet mask (expr-tree.h:1193). - An accept node is an
ImportantNodewith 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
permswithout the link and change_profile bits, and the same mask as the second argument unless the rule saysaudit; an allow or prompt rule passespermsas the second argument when the rule saysaudit. 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.
0x2800ais write with its implied append in both halves.
Read more
- The expression tree: the grouping by accept node.
- allow and deny, The audit qualifier, The owner qualifier.
03 priority*4 + kind, one bit at a time
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) andpri_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 | auditare 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 << 2plus 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
denyandquietand 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 << iwithiup to 31 shifts a signedintinto the sign bit (hfa.cc:1533); no wrong result is known.
Read more
- Rule priority: the ordering rule and worked examples.
- wiki: TechnicalDoc_HFA_permissions.
04 Three rules meet in one state
/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.0feature 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-treedump. Two later runs (one with a feature set that has the kernel'spolicyentries, one withabi/5.0) took the deny first:[1]=-4004 vs. 3, then[1]=3 vs. 41withclearing mask: 2 from 0/0 -> 0/0, then[1]=41 > 1 SKIPPING 3800e/0for 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
*.conffile the dump hasclearing mask: 2 from 3800e/0 -> 3800c/0, thendeny 2/2, and the state is(0x 10004/2800a//0/0/2800a). The tuple is allow/deny/prompt/audit/quiet, printed with a blank after0xand a doubled slash.0x2800ais 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-buildlines for the implied mmap bit have no line end (hfa.cc:1505, hfa.cc:1509, hfa.cc:1517, hfa.cc:1521).
Read more
- Rule priority, scene "Lower the deny"; allow and deny.
- apparmor_parser(8) D n dump n.
05 For exec, the exact path wins
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.0feature set; the dump has six rows (owner and other for each of three sets), and the slide shows one row of each pair. - An
ExactMatchFlagon 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. 0x10201isAA_MAY_EXEC,AA_MAY_GETATTRandAA_EXEC_MMAP(0x10000). The xindexi0isAA_X_INHERITwith index 0;p0is 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
ixis 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.
Read more
- Exec modes, Named exec transitions, Exec and domain transitions.
- The binary policy format: the exec name table.
06 Two exec modes, same score: refused
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_consistentcompares 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 printsERROR 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.0feature set), in a profile namedt. 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
- Exec modes, Rule priority.
- Running apparmor_parser: the exit status.
07 What becomes of a deny rule
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 whenfilter-denyis 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.0feature 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-denygives 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,anddeny /e w,, run with a feature set that has the kernel'spolicyentries: 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. Quiet0x317ais the write bit after the same expansion that turns read into0x244. - The table writer has no code that sets
aa_perms::deny(policy_compat.cc:160-190, policy_compat.cc:199-244);map_perms_to_acceptdoes not pass the deny mask on (hfa.h:132-138). - In the kernel,
unpack_permreads a deny field (policy_unpack.c:911) andverify_permrejects 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-denyleaves unused duplicate permission table entries"; "Kernel: anaudit denyfile rule in a complain-mode profile is allowed and logged ALLOWED"; "Adenyblock around anaudit denyrule drops the audit". - Not determined: why
filter-denyis 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
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_CTLkeeps 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-Soutput made with a feature set that has the kernel'spolicyentries). - In the kernel: without a
permsstruct both tables are expected (policy_unpack.c:1002); the kernel builds its permission table withaa_compat_map_xmatch,aa_compat_map_policyoraa_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).
Read more
- wiki: TechnicalDoc_HFA_permissions.
- Table compression: the accept tables. Unpacking and verifying policy.
09 The permission table
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) andcompute_perms_table_ent(hfa.cc:1412-1420). The table hasuniq_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 ofuniq_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'sabi/5.0feature set and with one that has the kernel'spolicyentries. As printed, every row continues withaccept1: 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_GETATTRis always set; bit 31 isAA_MAY_CHANGE_PROFILEand bit 30AA_MAY_ONEXEC;xindexcomes 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_LOCKis always added,AA_COMPAT_CONT_MATCHbecomesAA_CONT_MATCH. The two policydb rows of the example are0x8000and0x8004. - 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 fieldssubtree,cond,kill,complain,hide,tagandlabelare 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 hasACCEPT_FLAG_OWNER(file.c:194), andverify_perm(policy_unpack.c:1511). - Kernel statements are read from the kernel source and were not run.
- Errors:
permission not in permission table mapandpermission not in idx table map, thrown asstd::runtime_error(hfa.cc:1452-1454). - Known discrepancy: rows that filter deny made unused or equal stay in the table; by title, "
-O filter-denyleaves unused duplicate permission table entries". - Known discrepancy: those two
std::runtime_errors are not caught bycreate_chfa.
Read more
10 Where to go from here
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
- Five things to take away: a state's answer is five masks; each bit goes to the node with the highest
priority*4 + kind; an exact rule wins an exec bit over a glob of the same priority; equal scores with different exec modes are an error; deny is folded into allow before the answer is written as a table row or as the old accept words. - Minimisation: why deny is removed before merging. Table compression: where the accept table is stored. The binary policy format: the fourteen fields of a row.
- Rule priority, allow and deny, The audit qualifier, Exec modes, The owner qualifier, The prompt qualifier.
- Building the DFA, Matching at run time, How the kernel checks an access.
- Sources for this deck: AppArmor 836052d21 and Linux 97d73c825.
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).
| Class | Chosen when (tested in this order) | Kind in the score |
|---|---|---|
DenyMatchFlag | the rule is a deny rule | 3 |
PromptMatchFlag | the rule is a prompt rule | 0 |
ExactMatchFlag | an allow rule whose tree has no star, plus, any-char or negated set | 2 on exec bits, 1 otherwise |
MatchFlag | any other allow rule | 1 |
| Rule | perms argument | second argument |
|---|---|---|
| allow | the permissions | the permissions when the rule says audit, else 0 (audit) |
| prompt | the permissions | the permissions when the rule says audit, else 0 (audit) |
deny | the permissions, without the link and change_profile bits | the same mask (quiet) |
audit deny | the same | 0 (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).
| Kind | Sets | Clears |
|---|---|---|
| deny | deny, quiet (from the node's second mask) | allow, audit, prompt |
| exact, on an exec bit | allow, audit, and the exec type bits | the exec type bits of the loser |
| allow | allow, audit | |
| prompt | prompt, audit |
- For the file DFA,
ixadds 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
| Mask | Meaning |
|---|---|
| allow | permitted |
| deny | refused by a deny rule |
| prompt | ask user space |
| audit | log when used |
| quiet | do 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).
| Profile | Default | -O no-filter-deny |
|---|---|---|
| the six rules above | 16 table rows, 7 states | 12 table rows, 8 states |
| the three-rule example | 22 states | 38 states |
Tree. The deny column of the table is 0 in every case.
Old encoding
| Bits of accept1 (file DFA) | Meaning |
|---|---|
| 0-6 | owner permissions |
| 7-13 | owner exec type and table index |
| 14-20 | other permissions |
| 21-27 | other exec type and table index |
| 30 | onexec |
| 31 | change_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 = promptis 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_tthrough accept1, accept2 and accept3 and then throughcompute_fperms_userandcompute_fperms_otherto anaa_permsrow (compute_perms_table_ent, hfa.cc:1412-1420), so a row can say only what the old words could (code).
Permission table
| Old bit | New bits in the row |
|---|---|
| read 0x4 | read, getattr, open |
| write 0x2 | write, setattr, create, delete, chmod, chown, open |
| 0x10 | link |
| 0x20 | lock, link subset |
| 0x40 | exec mmap |
| exec 0x1 | exec, with xindex from the exec type bits |
| always | getattr |
- 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
permstable32use 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,
0x8000and0x8004(tree, kernel policy entries). - Kernel lookup:
perms[accept[state]], plus 1 for a non-owner whenaccept2[state]has the owner flag (file.c:194) (code).
Errors
| Message | From | Exit status |
|---|---|---|
profile has merged rule with conflicting x modifiers | hfa.cc:1703-1707 | followed by the next line |
ERROR processing regexs for profile %s, failed to load | parser_regex.c:1277 | 255 |
profile %s: has merged rule %s with conflicting x modifiers | block_rules.cc:325 | followed by the next line |
ERROR merging rules for profile %s, failed to load | the front end | 1 |
permission not in permission table map, permission not in idx table map | hfa.cc:1452-1454 | std::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-denyleaves unused duplicate permission table entries" (tree). - The
dfa-perms-buildlines for the implied mmap bit have no line end (tree). 1 << iwithiup to 31 on a signedint(hfa.cc:1533) (code).- Two different messages and exit statuses for the same exec conflict (tree).
- By title: "Kernel: an
audit denyfile rule in a complain-mode profile is allowed and logged ALLOWED"; "Adenyblock around anaudit denyrule drops the audit".
Not determined
- How a
promptrule reaches a kernel without the permission table. - Whether the kernel treats quiet without deny the way the compiler assumes in every hook.
- Why
filter-denyis still the default.
Roads from here
START HERE
- How the kernel checks an access — owner and other and deny in a walked machine
FILE ACCESS
- Exec modes — exec modes and their conflicts
QUALIFIERS
- Rule priority — the ordering rule as a profile author sees it
- allow and deny — what deny means in a profile
- The audit qualifier — audit and quiet and the log
- The owner qualifier — the owner and other halves
- The prompt qualifier — the lowest rung and what the kernel does with it
IN THE KERNEL
- Matching at run time — the kernel lookup of a row
THE DFA ENGINE · libapparmor_re
- Building the DFA — how accept nodes end up in a state
- Minimisation — why deny is removed before merging
- Table compression — where the accept table and the rows are stored
- The binary policy format — the fourteen fields of a row in the binary policy