Link rules

hard links for application developers for security researchers

Creating a hard link needs link permission on the new name and a rule pairing it with the existing file. The link rule and the l letter both provide that. The subset option also requires the new name to grant no more than the existing file.

On the map: file access

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

Part of journeys

01 A second name for the same file

LINK RULES the existing file /var/lib/demo/releases/v2 demo link("/var/lib/demo/releases/v2", "/var/lib/demo/current") /var/lib/demo/current the new name one file rules follow names link /var/lib/demo/current -> /var/lib/demo/releases/*, line 30 of demo's profile a new path means different rules for the same data
The program demo calls link to give the file /var/lib/demo/releases/v2 the second name /var/lib/demo/current. Both names lead to one file, and the link rule in demo's profile names the new name and the existing file.

A hard link adds a path to an existing file. AppArmor checks the new name and the existing file's name before allowing it: link NEWNAME -> EXISTING,.

Demo publishes a release by making a hard link. The newest release file gets a second name, current, and from then on the same file answers to both. Here's why AppArmor cares. Its rules are about names. Once the file has a new name, the rules for that name decide what demo can do with the data. If making links were free, a program could give a protected file a name in a directory it controls. So the kernel asks the profile before it creates one, and the link rule is how you answer. It's line thirty of demo's profile, and this deck takes it apart.

Details and sources

Details

  • Syntax on the slide: link NEWNAME -> EXISTING,. NEWNAME is the hard link to be created, EXISTING the file that is already there.
  • The system calls are link(2) and linkat(2). Both reach the LSM hook path_link (security_path_link, called at namei.c:6008); in the kernel AppArmor registers apparmor_path_link for it (lsm.c:1796).
  • apparmor_path_link(old_dentry, new_dir, new_dentry) returns 0 without a check when the file system of the existing file is not mediated or the task is unconfined; otherwise it calls aa_path_link (lsm.c:367-384).
  • aa_path_link builds two paths on the mount of the new link's directory, one for the new name and one for the existing file, and checks them against every profile that confines the task (file.c:437-467).
  • A refused link is logged with operation="link", the new name in name= and the existing file in target= (testcase_dmesg_link_01.in).
  • The kernel has a second, unrelated restriction on hard links, the sysctl fs.protected_hardlinks. It is not part of AppArmor and applies to unconfined tasks too.
  • The program demo and its profile are invented for the map. Nothing on this slide was observed on a running kernel; the kernel behaviour is stated from the kernel source.

Read more

02 Two ways to write link permission

GRAMMAR QUALIFIERS link subset LINK -> TARGET , the new name the existing file link /var/lib/demo/current -> /var/lib/demo/releases/*, PATH MODE with l -> TARGET , /var/lib/demo/state/* rwl, MODE with l subset PATH -> TARGET , l subset /var/lib/demo/current -> /var/lib/demo/releases/*, the arrow points from the new name to the old one
Three syntax diagrams. The link rule: optional qualifiers, the word link, optional subset, the new name, an arrow, the existing file, a comma. A file rule with the path first, a mode containing l and an optional arrow and target. A file rule with the mode first, optional subset, the path and an optional arrow and target.

link [subset] NEWNAME -> EXISTING, or the letter l in a file rule: PATH l [-> EXISTING], and l [subset] PATH [-> EXISTING],.

The link rule reads like the shell command turned around: the word link, the new name, an arrow, and the file that already exists. Both names are patterns. The arrow and the target are required. The word subset is optional, and we'll come to it. There's a second way: put the letter l into an ordinary file rule, as in rwl. There the target is optional, and if you write the letters first you can add subset too. The thing to remember is the direction. The arrow points from the new name to the old file.

Details and sources

Details

  • The three spellings: [QUALIFIERS] link [subset] NEWNAME -> EXISTING,; [QUALIFIERS] [file] PATH MODE-with-l [-> EXISTING],; [QUALIFIERS] [file] MODE-with-l [subset] PATH [-> EXISTING],.
  • QUALIFIERS is [priority=N] [audit] [allow|deny|prompt] [owner|other], in that order.
  • The link rule requires the arrow and the target. Run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel), link /a, is rejected: syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ARROW.
  • The link rule does not take the word file: file link /a -> /b, is a syntax error (unexpected TOK_LINK).
  • Both names are patterns in the globbing syntax, and variables are expanded in both (block_rules.cc:399-406).
  • In a path-first file rule the arrow is a link target only when the mode has l and no exec letter. With an exec letter the arrow names an exec target instead.
  • Examples from the parser's tests: link /alpha/beta -> /tmp/**, (ok_link_2.sd), link subset /alpha/beta -> /tmp/**, (ok_link_3.sd), /tmp/foo l -> /tmp/bar, (ok_link_4.sd).
  • The manual page gives the mapping between the two forms in its section "Link rules" (apparmor.d.pod:1160-1171).

Read more

for AppArmor developers for security researchers

In the code

03 The kernel checks both names

ONE LINK, TWO QUESTIONS link /var/lib/demo/current -> /var/lib/demo/releases/*, demo link(.../releases/v2, .../current) the kernel new name /var/lib/demo/current link allowed here? yes existing /var/lib/demo/releases/v2 an allowed target? yes link created the same call with another existing file existing /etc/shadow an allowed target? no info="target restricted" apparmor="DENIED" operation="link" ... name="/var/lib/demo/current" ... requested_mask="l" denied_mask="l" ... target="/etc/shadow"
Demo calls link. The kernel asks whether link is allowed on the new name /var/lib/demo/current and whether the existing file /var/lib/demo/releases/v2 is an allowed target; both answers are yes. With /etc/shadow as the existing file the second answer is no, and the denial record names the new path and carries /etc/shadow in its target field.

In the kernel a link needs l on the new name and a rule whose target matches the existing file. A refused target carries info="target restricted" and target= the existing file.

When demo calls link, the kernel builds both names and asks two questions. This is the kernel, read from its source. First: does the profile give link permission on the new name? Second: given that new name, is the existing file an allowed target? Our rule says current may point at anything directly in releases, so linking the second release works. Now try to make current point at the shadow password file. The first answer is still yes; the second is no. The denial names the new path, shows l in both masks, and carries the existing file in the target field.

Details and sources

Details

  • Everything here is read from the kernel source (profile_path_link, file.c:331-416) and was not observed on a running kernel.
  • Question one: the new name is matched against the profile's file rules and must have link permission. Without it the request fails with EACCES and no info text (file.c:358-365).
  • Question two: continuing from where the new name ended, the name of the existing file must match the target part of a rule. If it does not, the request fails with info="target restricted" (file.c:367-382).
  • The second question depends on the first: the target is looked up from the place the new name led to, not from the start. A target allowed for one link name says nothing about another link name.
  • Whether the denial is logged or kept quiet is taken from the pair of names, not from the rule for the new name alone (file.c:371-376).
  • Record fields for a link: operation="link", name= the new name, requested_mask="l", denied_mask="l", fsuid=, ouid= and target= the existing file (file.c:52-75). ouid is the owner of the existing file.
  • A real record, from the libapparmor test suite (testcase_dmesg_link_01.in): apparmor="DENIED" operation="link" ... name="/tmp/sdtest.19088-12382-HWH57d/linkfile" pid=19142 comm="link" requested_mask="l" denied_mask="l" fsuid=0 ouid=0 target="/tmp/sdtest.19088-12382-HWH57d/target". The record on the slide is adapted from it.
  • A task confined by several profiles (a stack) is checked against each of them (file.c:460-462).

Read more

for AppArmor developers for security researchers

In the code

  • The steps of profile_path_link in the kernel: path_name for the link and for the target (file.c:345-356); aa_str_perms on the link name from the start state of the file class; AA_MAY_LINK is required (file.c:360-365); aa_dfa_null_transition, then aa_str_perms on the target name from that state; the audit, quiet and kill masks are copied from this lookup (file.c:367-376); aa_audit_file with OP_LINK, the link name as name and the target name as target (file.c:413-415).
  • The compiled pair that these steps walk is described in the scene "Two rules, two DFA walks".

04 subset: no more than the original

SUBSET without subset /srv/demo/data r, /var/lib/demo/tmp/* rw, link /var/lib/demo/tmp/* -> /srv/demo/data, link(/srv/demo/data, /var/lib/demo/tmp/x) allowed: the pair matches open(/var/lib/demo/tmp/x, O_WRONLY) allowed: rw on that name demo writes a file it could only read with subset /srv/demo/data r, /var/lib/demo/tmp/* rw, link subset /var/lib/demo/tmp/* -> /srv/demo/data, link(/srv/demo/data, /var/lib/demo/tmp/x) new name: r w existing: r w is not in r: the link is refused the record's masks name the extra permissions the comparison is between the profile's rules for the two names what the rules allow in the kernel, read from its code
Two profiles. Without subset, demo may link a name in its temp directory to a read-only data file and then open that name for writing. With subset the kernel compares the permissions on the new name, read and write, with those on the existing file, read only, and refuses the link.

link subset NEW -> OLD, also requires every permission the profile grants on NEW (other than link) to be granted on OLD. This is what the kernel code does; it was not run on a kernel.

Look at the profile on the left. Demo may only read the data file. It may read and write in its temp directory, and it may link names there to the data file. So it makes a link in temp, opens the link for writing, and those rules have just let it write a file it could only read. Subset closes that. With subset, the kernel compares what the profile allows on the new name with what it allows on the existing file, and refuses the link if the new name would give more. Here write isn't covered, so the link is refused.

Details and sources

Details

  • Spellings with the test: link subset NEW -> OLD,, l subset NEW -> OLD, and the letter l without an arrow. Without the test: link NEW -> OLD, and NEW l -> OLD,.
  • All kernel statements are read from the kernel source and were not run.
  • Without subset the kernel stops after the two name checks and allows the link (file.c:384-386).
  • With subset it looks up the existing file once more, as an ordinary file, and takes every permission the profile allows on the new name except link itself. If one of them is not allowed on the existing file, the link is refused (file.c:388-400).
  • That refusal carries no info text. Both masks of the record name the missing permissions, for example requested_mask="xm" denied_mask="xm" in file_xm.in.
  • Exec is compared separately: if the new name has exec permission, the exec mode of the two names must be equal, or differ only in the new name being the safe variant where the existing file has the unsafe one. Otherwise the refusal has info="link not subset of target" (file.c:322-329, file.c:401-407).
  • The test compares what the profile's rules allow on the two names. It does not look at the file's mode bits or its owner's rights.
  • The manual page states the rule as: the new link must have a subset of the permissions of the original file, and an x rule on the new link must match the original exactly (apparmor.d.pod:1105-1110).
  • Test file: ok_link_3.sd.

for security researchers

Attack surface

  • A hard link gives a file a second name, and file rules are matched by name. A link rule, or l with an arrow, written without subset lets the task give a file a name under which the profile grants more than it does under the old name: for example write access through a name in a writable directory. Read from the source of mainline linux 7.4 (97d73c825), not observed on a running kernel.
  • subset closes that: every permission the profile grants on the new name, other than link, must also be granted on the existing file (file.c:384-407). The test compares what the profile allows on the two names; it does not look at what other profiles or other tasks may do with the new name.
  • The letter l in a file rule compiles to a link to any absolute path with the subset test: /e l, gives the pair /e NUL /[^/].* with the subset bit (run with the parser built from the AppArmor tree at 836052d21, nothing loaded into a kernel, -D rule-exprs). link /new -> /old, without subset has no such test.
  • owner on a link rule compares the task's fsuid with the owner of the existing file, not of the directory or the new name (file.c:443-448).
  • A symbolic link is not a link in this sense: creating one needs w on the new name, and the file it points to is checked under its own name when it is opened.

Read more

for AppArmor developers for security researchers

In the code

  • The subset request is lperms.allow & ~AA_MAY_LINK (file.c:395); xindex_is_subset masks AA_X_UNSAFE out of both exec indexes before comparing them (file.c:322-329).
  • In the kernel AA_LINK_SUBSET has the value of AA_MAY_LOCK (perms.h:34, perms.h:49). It is read from the state reached by the pair, where a lock bit has no other meaning.
  • In the parser the bit is AA_LINK_SUBSET_TEST, the link bit shifted left by one (immunix.h:117-120); it is added to the pair when the entry has subset (parser_regex.c:704-705).

05 The l letter: any target, subset on

THE LETTER L /var/lib/demo/state/* rwl, = /var/lib/demo/state/* rw, link subset /var/lib/demo/state/* -> (any path), link(/var/lib/demo/state/a, /var/lib/demo/state/b) new name: rw existing: rw allowed link(/etc/demo/demo.conf, /var/lib/demo/state/c) new name: rw existing: r not a subset /var/lib/demo/current l -> /var/lib/demo/releases/*, with an arrow: that target, no subset test l subset /var/lib/demo/current -> /var/lib/demo/releases/*, letters first: subset if you write it
The rule /var/lib/demo/state/* rwl equals read and write on that pattern plus link subset from that pattern to any path. Linking one state file to another is allowed because both names have read and write. Linking a state name to the read-only configuration file is not a subset. With an arrow, l names one target and has no subset test.

PATH l, allows hard links named PATH to any file, subject to the subset test. PATH l -> TARGET, allows that target without the test. l is not needed on the existing file.

Most profiles don't use the link keyword at all. They add l to a file rule, as in rwl on the state directory. It means: names matching this pattern may be created as hard links to any file, with the subset test always on. So demo can link one state file to another, because both names have read and write. It can't link a state name to its configuration file, which it may only read. Put an arrow after the letters and you get one specific target instead, and the subset test goes away unless you ask for it in the letters-first spelling.

Details and sources

Details

  • PATH l, compiles to: link permission on PATH, any absolute path as the target, and the subset test on. Checked with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load -D rule-exprs, nothing loaded into a kernel).
  • PATH l -> TARGET, allows the one target and has no subset test. l subset PATH -> TARGET, is the letters-first spelling that turns the test back on.
  • The other letters of the mode apply to PATH as usual: /var/lib/demo/state/* rwl, grants read and write on the names and lets them be created as hard links.
  • l is not needed on the existing file. The manual page says the same: "the destination does not have to have link access" (apparmor.d.pod:1105-1110).
  • To pass the subset test of a plain l rule, the profile must grant on the existing file at least what it grants on the new name (the kernel, file.c:384-400; read, not run). This is why a state file can be linked to another state file and not to a read-only configuration file.
  • The manual page gives /foo l, as equal to link subset /foo -> /**, (apparmor.d.pod:1165-1171). The compiled targets differ slightly: the bare l accepts NUL bytes in the target and /** does not. No path name contains a NUL byte, so the two match the same files.
  • Examples from the parser's tests: /alpha/beta rl, and /gamma/* rwl, (ok_link_1.sd); owner /tmp/foo l -> /tmp/bar1, (ok_link_4.sd).

for AppArmor developers for security researchers

In the code

  • Without link_name the pair gets the fixed target expression /[^/].* and always the subset bit (parser_regex.c:706-709).
  • Values printed by -D rule-exprs (the link bit is 0x10 per half, 0x40010 for both; the subset bit is 0x20): /a l, gives /a with 0x40010 and /a\x00/[^/].* with 0x40030; /a rl -> /b, gives /a with 0x50014 and /a\x00/b with 0x40010; l subset /a -> /b, gives the pair with 0x40030.
  • The letter sets AA_OLD_MAY_LINK (parser_misc.c:606-609); the kernel maps the old bit 0x10 to AA_MAY_LINK and 0x20 to AA_MAY_LOCK | AA_LINK_SUBSET when it loads the policy (policy_compat.c:87-93).

07 Two rules, two DFA walks for AppArmor developers for security researchers

PARSER AND KERNEL: THE LINK PAIR link subset /var/lib/demo/latest -> /var/lib/demo/releases/*, /var/lib/demo/latest (0x40010) /var/lib/demo/latest\x00/var/lib/demo/releases/[^/\x00][^/\x00]* (0x40030) process_dfa_entry (parser/parser_regex.c:684-716) 0x10 link 0x20 lock, in a pair: subset (LINK_TO_LINK_SUBSET) bare l: target /[^/].* and subset start lname S1 AA_MAY_LINK? \0 tname S2 AA_MAY_LINK? else "target restricted" S2 without AA_LINK_SUBSET: allow with it: start, tname again -> perms; request = lperms.allow & ~AA_MAY_LINK request & ~perms.allow: denied; exec: xindex_is_subset, else "link not subset of target" profile_path_link (linux:security/apparmor/file.c:331-416), the kernel
The parser turns a link subset rule into two expressions: the link name with value 0x40010, and the link name, a NUL byte and the target with value 0x40030. The kernel walks the link name to a state, takes the NUL transition, walks the target name to a second state, and when the subset bit is set there walks the target name again from the start to compare permissions.

link a -> b compiles to a and a\x00b (parser/parser_regex.c:684-716). profile_path_link (linux:security/apparmor/file.c:331-416, the kernel) walks name, NUL, target and tests AA_LINK_SUBSET.

process_dfa_entry emits two rules for a link. One is the link name with the link bit. The other is the name, a NUL separator and the target, again with the link bit, plus the bit next to it when subset is on. That neighbour is the lock bit, reused: in a pair state it means subset. For a bare l the target is a fixed expression and subset is always set. In the kernel, profile_path_link matches the link name, steps over the NUL, and matches the target. Only if the subset bit is there does a third match, of the target as an ordinary file, compare the two permission sets.

Details and sources

for AppArmor developers for security researchers

Details

  • process_dfa_entry (parser_regex.c:648-716) emits two rules per link entry: the link name with the entry's permissions (parser_regex.c:684-689), and the pair "link name, NUL, target" (parser_regex.c:692-716).
  • The pair is built by add_rule_vec, which joins the expressions with cat_with_null_separator: CatNode(CatNode(l, CharNode(0)), r) (aare_rules.cc:64-67, aare_rules.cc:90).
  • Values printed by the parser built from the AppArmor tree at 836052d21 with -D rule-exprs (link bit 0x10 per half, 0x40010 for both halves): link /a -> /b,: /a 0x40010 and /a\x00/b 0x40010; link subset /a -> /b,: /a 0x40010 and /a\x00/b 0x40030; /a l,: /a 0x40010 and /a\x00/[^/].* 0x40030.
  • The subset bit: AA_LINK_SUBSET_TEST is AA_OLD_MAY_LINK << 1 and LINK_TO_LINK_SUBSET(X) is ((X) << 1) & AA_LINK_SUBSET_TEST (immunix.h:117-120). In the kernel AA_LINK_SUBSET is defined as AA_MAY_LOCK, with the comment "overlaid" (perms.h:34, perms.h:49).
  • A bare l has no link_name: the target is the fixed expression /[^/].* and the subset bit is always added (parser_regex.c:706-709).
  • Both names pass through filter_slashes and convert_aaregex_to_pcre (parser_regex.c:658-660, parser_regex.c:699-701).
  • profile_path_link in the kernel, read and not run: aa_str_perms on lname from rules->file->start[AA_CLASS_FILE]; needs AA_MAY_LINK (file.c:360-365); aa_dfa_null_transition, then aa_str_perms on tname; without AA_MAY_LINK: info = "target restricted" (file.c:367-382); no AA_LINK_SUBSET in that state: done (file.c:384-386); third match: aa_str_perms on tname from the start state, request = lperms.allow & ~AA_MAY_LINK, denied if request & ~lperms.allow after lperms.allow is limited to the target's permissions (file.c:388-400); xindex_is_subset for exec, info = "link not subset of target" (file.c:401-407).
  • aa_path_link runs this for every confined profile of the label with fn_for_each_confined (file.c:437-467).

08 Link rules the parser refuses

COMMON MISTAKES link /var/lib/demo/current, any target? write: /var/lib/demo/current l, syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ARROW r subset /etc/demo/demo.conf, no l in the letters subset can only be used with link rules. lpx /var/lib/demo/current -> /var/lib/demo/releases/v1, letters first: an error link and exec perms conflict on a file rule using -> /var/lib/demo/current lPx -> demo-helper, path first: a warning, shown with --warn=all ambiguous rule specifies both link target and exec transition target. Using as exec transition link /var/lib/demo/current -> releases/v2, no message at all accepted, but a target that does not start with / matches no file
Five link rules with the parser's reaction: link without an arrow is a syntax error; subset without l is refused; l with an exec mode and an arrow is an error with the letters first and a deprecation warning with the path first; a relative target is accepted and matches no file.

"subset can only be used with link rules." "link and exec perms conflict on a file rule using ->". The link keyword requires -> TARGET; targets are absolute paths.

The link keyword needs both names. Leave out the arrow and you get a syntax error asking for it; if what you want is any target, use the letter l instead. Subset on a rule without l is refused. And one arrow can't do two jobs. The letter l together with an exec mode and an arrow is an error when the letters come first. With the path first it's accepted, with a deprecation warning, and the arrow is taken as the exec target. Last, a quiet one: targets are full path names, so a relative target loads and matches nothing.

Details and sources

Details

  • Messages are from the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel). The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.
  • link /a,: syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ARROW.
  • r subset /a,: subset can only be used with link rules.
  • lpx /a -> /b,: link and exec perms conflict on a file rule using ->. Test file: bad_leading_link_x.sd.
  • l /a -> :ns:b,: link perms are not allowed on a named profile transition.
  • /a lPx -> b, is accepted. With --warn=deprecated the parser prints ambiguous rule specifies both link target and exec transition target. Using as exec transition; that warning class is not in the default set (parser.h:77-78). The arrow is the exec target, and the link permission of such a rule gets any target with the subset test. Test files: depricated1.sd to depricated5.sd.
  • A link rule outside a profile is a syntax error (bad_link_outside.sd).
  • link /a -> b, loads without a message. The kernel compares the target with an absolute path name, so a target that does not start with / matches no file.

Read more

for AppArmor developers for security researchers

In the code

09 Where to go from here

ROADS link rules l on the new name + a matching pair; subset: no more than the original syn-globbing patterns in both names syn-file-rules the rule that carries l syn-access-modes why a symlink needs w syn-owner the qualifier syn-named-transitions the arrow's other job prac-hardlinks the security side k-match one automaton, two names syntax-map every kind of line
Link rules in the centre with roads to syn-file-rules, syn-access-modes, syn-globbing, syn-owner, syn-named-transitions, prac-hardlinks, k-match and syntax-map.

Next: syn-access-modes, syn-globbing, syn-owner, syn-named-transitions, prac-hardlinks (the security side), k-match.

That's hard links: permission on the new name, a pair that matches, and subset when the new name mustn't be stronger than the old. If the patterns in the two names are new to you, go to globbing. The access modes deck explains why a symlink needs w, and the owner deck covers the qualifier. The arrow has another job in named transitions. For what hard links mean for the security of a real system, take the practical deck on hard links. And the kernel matching deck shows how one automaton answers a question about two names.

Details and sources

Details

  • A hard link needs link permission on the new name and a rule whose target matches the existing file.
  • link A -> B, and A l -> B,: target B, no subset test. link subset A -> B, and l subset A -> B,: target B, with the test. A l,: any target, with the test.
  • The subset test: every permission the profile grants on the new name, apart from link, must also be granted on the existing file.
  • Symbolic links are created with w on their own name; link rules do not apply to them.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). The kernel behaviour was read from the source, not observed on a running kernel.

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment (-Q -K --skip-kernel-load --warn=all), with nothing loaded into a kernel; "code" means the parser source or the source of mainline Linux 7.4 was read, not run. Nothing here was observed on a running kernel.

Grammar

LINK RULE:   [QUALIFIERS] link [subset] NEWNAME -> EXISTING ,
FILE RULE:   [QUALIFIERS] [file] PATH MODE-with-l [-> EXISTING] ,
FILE RULE:   [QUALIFIERS] [file] MODE-with-l [subset] PATH [-> EXISTING] ,
QUALIFIERS:  [priority=N] [audit] [allow|deny|prompt] [owner|other]
  • The link rule does not take the file keyword. Its arrow and target are required.
  • NEWNAME (or PATH) is the name of the link to be created; EXISTING is the file that already exists. The arrow points from the new name to the old one.
  • Both names are patterns in the same pattern language as file rules: syn-globbing. Variables are expanded in both (code).
  • In a file rule the arrow is a link target only when the mode has l and no exec letters. With an exec letter see "Errors and warnings" below and syn-named-transitions.

Keywords

KeywordWhereMeaning
linkstart of the rule, after the qualifiersa link rule: the new name, the arrow, the existing file
subsetafter link, or after the mode in a letters-first file rulealso require the new name to grant no more than the existing file
->between the two namesseparates the new name from the existing file
lin the mode of a file rulelink permission on that path; without an arrow, any target with the subset test

Which form does what

Compiled forms are from the tree's parser (tree); what the kernel then does is from the source of mainline Linux 7.4 (code).

RuleAllowed targetSubset test
link A -> B,Bno
link subset A -> B,Byes
A l,any absolute pathyes
A l -> B,Bno
l subset A -> B,Byes
A rwl,any absolute path; r and w apply to A as usualyes

l is not needed on the existing file. To pass the subset test of a plain l rule, the profile must grant on the existing file at least what it grants on the new name.

What the kernel checks

All statements in this section are from the source of mainline Linux 7.4 (linux:security/apparmor/file.c:331-467), not from a run.

1. The kernel builds the name of the new link and the name of the existing file. 2. The new name must have link permission. If it does not, the request is denied. 3. Given the new name, the existing file must be an allowed target. If it is not, the request is denied with info="target restricted". 4. If the matching rule has no subset test, the link is allowed. 5. Otherwise every permission the profile allows on the new name, apart from link itself, must also be allowed on the existing file. If one is missing the request is denied, and the masks of the record name the missing permissions; no info text is set in this case. If the new name has exec permission, the exec mode of the two names must also agree (equal, or the new name safe where the existing file is unsafe); if not, the request is denied with info="link not subset of target".

  • owner on a link rule compares the task's fsuid with the owner of the existing file.
  • The audit and quiet settings reported for a link come from the pair (new name, existing file), not from the rule for the new name alone.
  • The subset test compares what the profile's rules allow on the two names. It does not look at file modes.

A denial record, shortened, adapted from libraries/libapparmor/testsuite/test_multi/testcase_dmesg_link_01.in:

apparmor="DENIED" operation="link" profile="demo" name="/var/lib/demo/current" pid=19142 comm="demo" requested_mask="l" denied_mask="l" fsuid=1000 ouid=0 target="/etc/shadow"

A failed subset test can show other letters in the masks, for example requested_mask="xm" denied_mask="xm" (libraries/libapparmor/testsuite/test_multi/file_xm.in).

Not covered

  • Symbolic links. Creating a symlink is a file creation: it needs w on the symlink's own name, and no rule looks at where it points when it is made (linux:security/apparmor/lsm.c:360-365, mainline Linux 7.4).
  • The security consequences of hard links for whole systems: prac-hardlinks.

Errors and warnings

Messages are from the tree's parser (tree). A full error reads AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

LineMessage
link /a,syntax error, unexpected TOK_END_OF_RULE, expecting TOK_ARROW
r subset /a,subset can only be used with link rules.
lpx /a -> /b,link and exec perms conflict on a file rule using ->
l /a -> :ns:b,link perms are not allowed on a named profile transition.
file link /a -> /b,syntax error, unexpected TOK_LINK, ...
/a lPx -> b,warning: ambiguous rule specifies both link target and exec transition target. Using as exec transition
  • The warning belongs to the deprecated warning class, which is off by default. The arrow of such a rule is the exec target, and its link permission gets the any-path target with the subset test (tree; fixtures parser/tst/simple_tests/link/depricated1.sd to depricated5.sd).
  • A link rule outside a profile is a syntax error (parser/tst/simple_tests/link/bad_link_outside.sd).

Known discrepancies

  • The grammar lists <= as an alternative to subset, but it cannot be written: link <= /a -> /b, fails with "Lexer found unexpected character: '<' (0x3c) in state: INITIAL" (tree). Use subset.
  • The manual page says /foo l, equals link subset /foo -> /**,. The compiled target of the bare l is /[^/].*, while /** compiles to /[^/\x00][^\x00]*; the two differ only in whether NUL bytes are accepted (tree, code).
  • A target that does not start with / is accepted without a message: link /a -> b, loads and matches no file (tree).
  • The text link not subset of target is set only when the exec modes disagree. A subset failure on other permissions is denied without an info text (code, mainline Linux 7.4).

for AppArmor developers for security researchers

Compiled form

process_dfa_entry (parser/parser_regex.c:648-716) emits two rules per link entry: the link name, and the pair "link name, NUL, target" built by add_rule_vec with cat_with_null_separator (parser/libapparmor_re/aare_rules.cc:64-67,90). Values from -D rule-exprs (tree); the link bit is 0x10 per half, both halves 0x40010.

RuleFirst rulePair
link /a -> /b,/a 0x40010/a\x00/b 0x40010
link subset /a -> /b,/a 0x40010/a\x00/b 0x40030
/a l,/a 0x40010/a\x00/[^/].* 0x40030
/a rl -> /b,/a 0x50014/a\x00/b 0x40010
l subset /a -> /b,/a 0x40010/a\x00/b 0x40030
/var/lib/demo/state/* rwl,the name, 0x7801ethe name, \x00/[^/].* 0x40030
  • The subset bit is the lock bit of a pair state: LINK_TO_LINK_SUBSET(X) shifts the link bit left by one (parser/immunix.h:117-120); in the kernel AA_LINK_SUBSET has the value of AA_MAY_LOCK (linux:security/apparmor/include/perms.h:34,49).
  • Deny rules: the first rule is added only when the mode has bits other than link, and without the link bit; the denial of the link is carried by the pair (parser/parser_regex.c:665-683). deny /a l, emits only the pair; deny /a rl, emits /a as a deny rule with 0x10004 and the pair (tree).
  • Both names pass through filter_slashes and the AARE conversion (parser/parser_regex.c:659-660,700-701).

profile_path_link in mainline Linux 7.4 (linux:security/apparmor/file.c):

LinesStep
345-356path_name for the link and for the target
360-365aa_str_perms on lname from the start state; needs AA_MAY_LINK
367-382aa_dfa_null_transition, aa_str_perms on tname; audit, quiet and kill masks taken from this state; without AA_MAY_LINK: "target restricted"
384-386no AA_LINK_SUBSET: done
388-400aa_str_perms on tname from the start state; request = lperms.allow & ~AA_MAY_LINK; denied if request & ~perms.allow
322-329, 401-407xindex_is_subset; "link not subset of target"
437-467aa_path_link: cond.uid is the owner of the existing file's inode

Roads from here

START HERE

FILE ACCESS

QUALIFIERS

IN PRACTICE · security-sensitive programs

IN THE KERNEL