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
- File rules — the file rule that carries the l letter and the arrow
- File access modes — the access letters, l among them
- Globbing (AARE) — the patterns both names of a link rule are written in
Part of journeys
- File access in depth, step 7 of 12 · previous: Named exec transitions · next: The owner qualifier
01 A second name for the same 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,.NEWNAMEis the hard link to be created,EXISTINGthe file that is already there. - The system calls are
link(2)andlinkat(2). Both reach the LSM hookpath_link(security_path_link, called at namei.c:6008); in the kernel AppArmor registersapparmor_path_linkfor 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 callsaa_path_link(lsm.c:367-384).aa_path_linkbuilds 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 inname=and the existing file intarget=(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
demoand 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
- apparmor.d(5), Link rules.
- Kernel documentation: protected_hardlinks.
- Hard links in practice: what a second name means for the security of a system.
- File rules.
02 Two ways to write link permission
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],. QUALIFIERSis[priority=N] [audit] [allow|deny|prompt] [owner|other], in that order.- The
linkrule 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
linkrule does not take the wordfile: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
land 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
- apparmor.d(5), Link rules and l - Link mode.
- Globbing: the pattern syntax of both names.
- Named transitions: the other use of the arrow.
for AppArmor developers for security researchers
In the code
- The
link_ruleproduction:TOK_LINK opt_subset_flag id_or_var TOK_ARROW id_or_var TOK_END_OF_RULE(parser_yacc.y:1141-1152). It creates an entry with the link permission for both halves and the target aslink_name. - The two file rule productions: path first (parser_yacc.y:1072-1083) and permissions first with
opt_subset_flag(parser_yacc.y:1085-1101). - The keywords
linkandsubset: parser_misc.c:94, parser_misc.c:98. opt_subset_flagalso listsTOK_LE(parser_yacc.y:672-674), butlink <= /a -> /b,cannot be written: the tree's parser answersLexer found unexpected character: '<' (0x3c) in state: INITIAL.
03 The kernel checks both names
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
infotext (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=andtarget=the existing file (file.c:52-75).ouidis 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
- apparmor.d(5), Link rules.
- Reading a denial: the fields of a record.
- Matching at run time: how one automaton answers a question about two names.
for AppArmor developers for security researchers
In the code
- The steps of
profile_path_linkin the kernel:path_namefor the link and for the target (file.c:345-356);aa_str_permson the link name from the start state of the file class;AA_MAY_LINKis required (file.c:360-365);aa_dfa_null_transition, thenaa_str_permson the target name from that state; the audit, quiet and kill masks are copied from this lookup (file.c:367-376);aa_audit_filewithOP_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
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 letterlwithout an arrow. Without the test:link NEW -> OLD,andNEW l -> OLD,. - All kernel statements are read from the kernel source and were not run.
- Without
subsetthe kernel stops after the two name checks and allows the link (file.c:384-386). - With
subsetit 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
infotext. Both masks of the record name the missing permissions, for examplerequested_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
xrule 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
linkrule, orlwith an arrow, written withoutsubsetlets 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. subsetcloses 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
lin a file rule compiles to a link to any absolute path with the subset test:/e l,gives the pair/eNUL/[^/].*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,withoutsubsethas no such test. owneron 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
won the new name, and the file it points to is checked under its own name when it is opened.
Read more
- apparmor.d(5), l - Link mode and Link rules.
- Access modes: the permissions that are compared.
- Safe and unsafe exec.
for AppArmor developers for security researchers
In the code
- The subset request is
lperms.allow & ~AA_MAY_LINK(file.c:395);xindex_is_subsetmasksAA_X_UNSAFEout of both exec indexes before comparing them (file.c:322-329). - In the kernel
AA_LINK_SUBSEThas the value ofAA_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 hassubset(parser_regex.c:704-705).
05 The l letter: any target, subset on
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 onPATH, 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
PATHas usual:/var/lib/demo/state/* rwl,grants read and write on the names and lets them be created as hard links. lis 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
lrule, 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 tolink subset /foo -> /**,(apparmor.d.pod:1165-1171). The compiled targets differ slightly: the barelaccepts 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).
Read more
- apparmor.d(5), l - Link mode.
- apparmor.d(5), Link rules.
- Access modes: the other letters.
for AppArmor developers for security researchers
In the code
- Without
link_namethe 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 is0x10per half,0x40010for both; the subset bit is0x20):/a l,gives/awith0x40010and/a\x00/[^/].*with0x40030;/a rl -> /b,gives/awith0x50014and/a\x00/bwith0x40010;l subset /a -> /b,gives the pair with0x40030. - The letter sets
AA_OLD_MAY_LINK(parser_misc.c:606-609); the kernel maps the old bit0x10toAA_MAY_LINKand0x20toAA_MAY_LOCK | AA_LINK_SUBSETwhen it loads the policy (policy_compat.c:87-93).
06 deny, audit and owner on a link
Link rules accept audit, deny and owner. In the kernel owner tests the owner of the existing file. A symlink needs w on its own name, not l.
A link rule takes the same qualifiers as a file rule, in the same order. The tree's tests have one with all of them: audit deny owner link subset. Owner needs a word of explanation. For a link, the kernel compares the task's user with the owner of the existing file, because the new name doesn't exist yet. And one common confusion: symbolic links aren't covered by any of this. Creating a symlink is creating a file, so it needs w on the new name, and the rule says nothing about where the symlink points.
Details and sources
Details
- Order:
[priority=N] [audit] [allow|deny|prompt] [owner|other] link [subset] NEWNAME -> EXISTING,. - Test files in the tree:
audit deny owner link subset /alpha/beta -> /tmp/**,(ok_link_audit_deny_owner_subset.sd),owner link subset /alpha/beta -> /tmp/**,(ok_link_owner.sd),deny link /alpha/beta -> /tmp/**,(ok_deny_link.sd),audit deny link /alpha/beta -> /tmp/**,(ok_audit_deny_link.sd). owner: in the kernel the owner used for a link check is the owner of the existing file's inode, translated through the mount's ID mapping (file.c:441-448). It is compared with the task's fsuid (file.c:226-228). The same value is logged asouid=.auditand the quiet effect ofdenyare read from the pair of names (file.c:371-376).- Symbolic links:
symlink(2)andsymlinkat(2)reach the LSM hookpath_symlink.apparmor_path_symlinkasks for create permission on the new name and does not look at the text the symlink will hold (lsm.c:360-365). - Create permission comes from
win a file rule: when it loads a policy, the kernel maps the write bit to create, delete, setattr, chmod, chown and open (policy_compat.c:84-86). - These kernel statements are read from the source and were not run.
Read more
for AppArmor developers for security researchers
In the code
- A deny entry contributes its first rule 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_regex.c:665-683).
deny /a l,emits only the pair;deny /a rl,emits/aas a deny rule with0x10004and the pair. - The audit mask of the pair is
perms & AA_LINK_BITSwhen the rule hasaudit(parser_regex.c:710-716).
07 Two rules, two DFA walks for AppArmor developers for security researchers
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 withcat_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 bit0x10per half,0x40010for both halves):link /a -> /b,:/a0x40010and/a\x00/b0x40010;link subset /a -> /b,:/a0x40010and/a\x00/b0x40030;/a l,:/a0x40010and/a\x00/[^/].*0x40030. - The subset bit:
AA_LINK_SUBSET_TESTisAA_OLD_MAY_LINK << 1andLINK_TO_LINK_SUBSET(X)is((X) << 1) & AA_LINK_SUBSET_TEST(immunix.h:117-120). In the kernelAA_LINK_SUBSETis defined asAA_MAY_LOCK, with the comment "overlaid" (perms.h:34, perms.h:49). - A bare
lhas nolink_name: the target is the fixed expression/[^/].*and the subset bit is always added (parser_regex.c:706-709). - Both names pass through
filter_slashesandconvert_aaregex_to_pcre(parser_regex.c:658-660, parser_regex.c:699-701). profile_path_linkin the kernel, read and not run:aa_str_permsonlnamefromrules->file->start[AA_CLASS_FILE]; needsAA_MAY_LINK(file.c:360-365);aa_dfa_null_transition, thenaa_str_permsontname; withoutAA_MAY_LINK:info = "target restricted"(file.c:367-382); noAA_LINK_SUBSETin that state: done (file.c:384-386); third match:aa_str_permsontnamefrom the start state,request = lperms.allow & ~AA_MAY_LINK, denied ifrequest & ~lperms.allowafterlperms.allowis limited to the target's permissions (file.c:388-400);xindex_is_subsetfor exec,info = "link not subset of target"(file.c:401-407).aa_path_linkruns this for every confined profile of the label withfn_for_each_confined(file.c:437-467).
08 Link rules the parser refuses
"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 isAppArmor 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=deprecatedthe parser printsambiguous 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 todepricated5.sd.- A
linkrule 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
- apparmor.d(5), Link rules.
- apparmor_parser(8): the
--warnoption. - Named transitions: the arrow as an exec target.
for AppArmor developers for security researchers
In the code
- The three
yyerrorcalls are in the permissions-first file rule (parser_yacc.y:1087-1092); the deprecation warning is in the path-first one (parser_yacc.y:1074-1077). - The warning class
deprecated: parser_main.c:284. link <= /a -> /b,: the grammar acceptsTOK_LEas a subset flag (parser_yacc.y:672-674), but the lexer does not return that token here; the message isLexer found unexpected character: '<' (0x3c) in state: INITIAL(parser_lex.l:930).
09 Where to go from here
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,andA l -> B,: targetB, no subset test.link subset A -> B,andl subset A -> B,: targetB, 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
won 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
linkrule does not take thefilekeyword. Its arrow and target are required. NEWNAME(orPATH) is the name of the link to be created;EXISTINGis 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
land no exec letters. With an exec letter see "Errors and warnings" below and syn-named-transitions.
Keywords
| Keyword | Where | Meaning |
|---|---|---|
link | start of the rule, after the qualifiers | a link rule: the new name, the arrow, the existing file |
subset | after link, or after the mode in a letters-first file rule | also require the new name to grant no more than the existing file |
-> | between the two names | separates the new name from the existing file |
l | in the mode of a file rule | link 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).
| Rule | Allowed target | Subset test |
|---|---|---|
link A -> B, | B | no |
link subset A -> B, | B | yes |
A l, | any absolute path | yes |
A l -> B, | B | no |
l subset A -> B, | B | yes |
A rwl, | any absolute path; r and w apply to A as usual | yes |
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".
owneron 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
won 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.
| Line | 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 -> |
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
deprecatedwarning 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
linkrule outside a profile is a syntax error (parser/tst/simple_tests/link/bad_link_outside.sd).
Known discrepancies
- The grammar lists
<=as an alternative tosubset, but it cannot be written:link <= /a -> /b,fails with "Lexer found unexpected character: '<' (0x3c) in state: INITIAL" (tree). Usesubset. - The manual page says
/foo l,equalslink subset /foo -> /**,. The compiled target of the barelis/[^/].*, 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 targetis set only when the exec modes disagree. A subset failure on other permissions is denied without aninfotext (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.
| Rule | First rule | Pair |
|---|---|---|
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, 0x7801e | the 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 kernelAA_LINK_SUBSEThas the value ofAA_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/aas a deny rule with 0x10004 and the pair (tree). - Both names pass through
filter_slashesand the AARE conversion (parser/parser_regex.c:659-660,700-701).
profile_path_link in mainline Linux 7.4 (linux:security/apparmor/file.c):
| Lines | Step |
|---|---|
| 345-356 | path_name for the link and for the target |
| 360-365 | aa_str_perms on lname from the start state; needs AA_MAY_LINK |
| 367-382 | aa_dfa_null_transition, aa_str_perms on tname; audit, quiet and kill masks taken from this state; without AA_MAY_LINK: "target restricted" |
| 384-386 | no AA_LINK_SUBSET: done |
| 388-400 | aa_str_perms on tname from the start state; request = lperms.allow & ~AA_MAY_LINK; denied if request & ~perms.allow |
| 322-329, 401-407 | xindex_is_subset; "link not subset of target" |
| 437-467 | aa_path_link: cond.uid is the owner of the existing file's inode |
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
FILE ACCESS
- File rules — the file rule that carries the l letter
- File access modes — the other letters and why symlinks need w
- Globbing (AARE) — patterns in both names
- Named exec transitions — the other meaning of the arrow
QUALIFIERS
- The owner qualifier — owner on a link rule looks at the existing file
IN PRACTICE · security-sensitive programs
- Hard links and name-based rules — what hard links mean for the security of a system
IN THE KERNEL
- Matching at run time — the two-part match in the kernel