Hard links and name-based rules
new names, same file for application developers for administrators for security researchers
A hard link gives a file a second name and AppArmor judges the file by the rules for that name. Covers who can create such a name and the three checks AppArmor makes for confined programs and which rule spellings keep the subset test. Also owner and fs.protected_hardlinks and how a file can be linked out of a directory a profile denies.
On the map: security-sensitive programs
▶ Watch this deck — 9 scenes, ~7 min
Worth seeing first
- Profiles for security-sensitive programs — the precise style whose reviews include this one
- Link rules — the link rule and the l letter
Part of journeys
- Hardening a privileged program, step 2 of 11 · previous: Profiles for security-sensitive programs · next: Symlinks: rules see through them
01 One file, two names, two answers
Two hard links are two names for one file, and AppArmor matches the name that was used. A file denied under one name can be allowed under another; the ordinary owner and mode checks still apply. This is read from the kernel code; it was not run on a kernel.
Demo's profile lets it read and write under /var/tmp, and says nothing about the shadow file. So when demo opens the shadow file by its usual name, it's denied. Now suppose the same file has a second name: a hard link in /var/tmp. Demo opens that name instead. In the kernel, AppArmor builds the path from the directory entry that was used, sees /var/tmp/s, finds your rule, and allows it. The file's own permission bits still apply, but AppArmor's answer changed with the name. So the real question is: who can create that second name?
Details and sources
Details
This scene is derived from the kernel code. It was not run on a kernel. The inode number is decoration.
- AppArmor's file rules are matched against a name. For an open, that name is rebuilt from the directory entry that was looked up, so a file with two hard links has two names and each is matched on its own.
- The file itself carries no AppArmor label for file rules. Nothing records that
/var/tmp/sand/etc/shadoware the same file. Systems that label the file itself give the same answer under every name; a name-based system does not. - With
/var/tmp/** rw,and no rule for/etc/shadow:open("/etc/shadow")is matched as/etc/shadowand denied;open("/var/tmp/s", O_RDWR)is matched as/var/tmp/sand allowed by AppArmor. - AppArmor's answer comes on top of the ordinary Unix owner and mode checks. A program that could not open
/etc/shadowbecause of its mode cannot open the link either. - A bind mount also gives a file a second name. Creating one is a mount operation, covered by mount rules and not by link rules.
Read more
- apparmor.d(5): l - Link mode, apparmor.d(5): Link rules
- Link rules (the scene "A second name"), the limits of name-based mediation, matching at run time.
for AppArmor developers for security researchers
Code
- The name is built by
d_namespace_path(path.c:88-128);d_absolute_pathis called on the path that was looked up at path.c:124-127.
02 Not a symlink, and more than a copy
A symlink is resolved to the target's name; a hard link is itself a name of the file. Unlike a copy, a link keeps the inode: owner, mode (including setuid and setgid) and future content, and can be made to a file the program cannot read.
If you've seen the symlinks deck, you might expect the kernel to see through this. It doesn't, because there's nothing to see through. A symlink points at another name and gets resolved to it. And a program that can read a file can copy it anyway. But a copy is a new file, with your ownership and today's content. A hard link is a name of the file, as real as the first, checked under the rules for its directory. It is the original: same owner, same mode, set-user-ID bit and all. It follows every later change, and making one doesn't require read access. That's why AppArmor treats making one as a permission of its own.
Details and sources
Details
- A symlink holds a path. Opening it is checked as the path the kernel arrives at after following it: see symlinks. A hard link holds nothing to follow. It is a directory entry for the file, and the check uses that entry's name.
- A copy is a new file: it belongs to whoever made it, has the mode they gave it, and has the content of the moment of copying. Making it requires reading the original.
- A hard link is the original file under another name. Owner and mode are those of the file, including the setuid and setgid bits; a later change to the content is visible under both names; and creating it does not require read access to the file as far as AppArmor is concerned (the kernel's own
fs.protected_hardlinkssetting may: next scene). link()does not follow a symlink given as the existing name.linkat()follows it only withAT_SYMLINK_FOLLOW. Without that flag the hard link is made to the symlink itself, andtarget=in an AppArmor record is the symlink's own path (read from the kernel code).- Both names must be on the same mount; otherwise the call fails with
EXDEVbefore any other check.
for AppArmor developers for security researchers
Code
AT_SYMLINK_FOLLOWbecomesLOOKUP_FOLLOWat namei.c:5988-5989; theEXDEVtest is at namei.c:6001-6003.
03 Who can create the second name?
Order in the kernel: same mount (EXDEV), fs.protected_hardlinks (EPERM, an AUDIT_ANOM_LINK audit record), AppArmor's link check for confined tasks (EACCES), then the file system. Unconfined programs are not checked by AppArmor.
Who can create that second name? Follow the link call through the kernel. First, both names must be on the same mount. Second, the protected hard links setting: when it's on, you can only link a file you own, or an ordinary file you can read and write. Third, AppArmor, but only if the caller is confined. Fourth, directory permissions. So an ordinary user stops at gate two. Unconfined root sails through: it owns the file, and AppArmor isn't asked. Confined root gets no help from the setting either. There, the profile decides. A refusal at gate two isn't an AppArmor denial; it leaves a different audit record.
Details and sources
Details
The order of checks and their results are read from the kernel code. Nothing here was run. ann and the three callers are illustrations.
- Order inside the
linkatsystem call: look up both names;EXDEVif they are on different mounts; thefs.protected_hardlinkscheck; the security module hook, which is where AppArmor is asked; then the file system's own checks (write and search permission on the directory among them). fs.protected_hardlinksis the file/proc/sys/fs/protected_hardlinks, value 0 or 1. With 1, a link is refused withEPERMunless the caller's fsuid owns the file or the caller hasCAP_FOWNER, or the file is a "safe source": a regular file, not setuid, not setgid with group execute, and both readable and writable by the caller.- The kernel documentation words it: "When set to "1" hardlinks cannot be created by users if they do not already own the source file, or do not have read/write access to it." (fs.rst:207-208).
- The variable has no initializer in the kernel source, so the kernel's own default is 0. Which value an installed system sets is outside both source trees; that is why the narration says "when it's on".
- A refusal by this setting is logged by the kernel as an audit record of type
AUDIT_ANOM_LINKwith the textlinkat. The code read for this deck shows only the record type and that word, so no full log line is shown. It is not anapparmor="DENIED"record, and no profile rule changes it. - With the value 0, any user who can write a directory on the same mount can create a name there for any file. Rules for that directory then apply to the file; the file's own owner and mode still limit what can be done with it.
- AppArmor is asked only when the calling task is confined. A confined caller that fails the link check gets
EACCES. - For a file the caller does not own and that is not a safe source, the setting's exemption is
CAP_FOWNER. A confined task holds that capability only with acapability fowner,rule, so the setting can refuse a confined root too (namei.c:1381-1382). - For a program that runs as root the setting does not help: root owns most system files. Keep it at 1 all the same; it covers programs that are not confined.
Read more
- kernel docs: protected_hardlinks; the same text pinned to the tree read here: linux: Documentation/admin-guide/sysctl/fs.rst:193
- apparmor.d(5): Link rules
- AppArmor's threat model, what is not mediated.
for AppArmor developers for security researchers
Code
filename_linkat: namei.c:5996-6010, withsecurity_path_linkat namei.c:6008.may_linkat: namei.c:1366-1387;safe_hardlink_source: namei.c:1323-1342; the audit call at namei.c:1385.- The variable and its sysctl table entry: namei.c:1211, namei.c:1226-1234.
apparmor_path_linkcallsaa_path_linkonly for a label that is not unconfined: lsm.c:367-384.error = -EACCES;at the start of the per-profile check: file.c:358.
04 The link check in three steps
Link check for confined tasks: l on the new name; the existing file must match the rule's target (info="target restricted"); with the subset test, permissions on the new name must be covered by those on the existing name. Records carry operation="link", name= and target=. The outcomes are read from the kernel code.
Here's what AppArmor does when confined demo asks for that link. Step one: is link allowed on the new name? With plain read and write on /var/tmp, no. The record says operation link, with the new name in name and the existing file in target. Step two: is the existing file acceptable as a target? A link rule with an arrow limits that, and a miss says target restricted. Step three, the subset test: whatever is allowed on the new name must also be allowed on the existing one. Demo has nothing on the shadow file, so it's refused. It would pass only if demo could already read and write the shadow file. And step three runs only for rules that carry the subset test.
Details and sources
Details
The three steps and their outcomes are derived from the kernel code; no kernel was run. The record on the slide is real: it is the record in the libapparmor test suite file testcase_dmesg_link_01.in, shortened with ..., fields in the kernel's order.
The check, per profile, in the order the code makes it:
- Step 1. Both names are built. The existing file's name is built through the mount of the new directory, which is the same mount.
- Step 2. The new name must have link permission (
l). Without it the request is denied:requested_mask="l" denied_mask="l". - Step 3. The existing name is matched as the second half of the link pair. If the rule's target does not accept it, the denial carries
info="target restricted". - Step 4. If the matching rule does not carry the subset test, the link is allowed here.
- Step 5. With the subset test, the existing name is matched again as an ordinary file. Every permission the profile allows on the new name, other than link, must also be allowed on the existing name. When the new name has an exec permission, the exec transitions of both names must agree too; a mismatch there is the only case that sets
info="link not subset of target".
lis needed on the new name only. The existing name needs nol.- Fields of a link record:
name=is the new name,target=the existing file,ouid=the owner of the existing file. - The full record of the slide:
apparmor="DENIED" operation="link" parent=19088 profile="/home/ubuntu/bzr/apparmor/tests/regression/apparmor/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". - A failed subset test lists the permissions the existing name lacks and sets no
infowhen no exec permission is involved. A real record of that kind (file_xm.in):apparmor="DENIED" operation="link" profile="cargo" name="/var/tmp/portage/dev-lang/rust-1.67.1/work/rustc-1.67.1-src/build/bootstrap/debug/libbootstrap.rlib" pid=12412 comm="cargo" requested_mask="xm" denied_mask="xm" fsuid=250 ouid=250 target="/var/tmp/portage/dev-lang/rust-1.67.1/work/rustc-1.67.1-src/build/bootstrap/debug/deps/libbootstrap-4542dd99e796257e.rlib". - Not determined: the exact mask letters of a failed subset test for the
rwcase of the slide. That is why step 3 shows no masks. linkat(fd, "", AT_FDCWD, path, AT_EMPTY_PATH)on anO_TMPFILEdescriptor goes through the same check. The existing name is then a deleted entry, which the regression test describes as "Denial log entry for tmpfile is /path/#[6digits]" (linkat_tmpfile.sh:31-49).- Known discrepancy: by reading, a profile that sets any path flag (for example
attach_disconnected) is packed without the mediate-deleted bit, and the link check then fails for a deleted existing file withinfo="Failed name lookup - deleted entry". This was not run, and it may be intended.
Read more
- apparmor.d(5): Link rules, apparmor.d(5): l - Link mode
- Link rules (the scenes "Two names, two checks" and "subset"), reading a denial, matching at run time.
for AppArmor developers for security researchers
Code
aa_path_link: file.c:437-467;profile_path_link: file.c:331-416; the link permission test at file.c:360-365, the target test at file.c:368-382, the early return without the subset bit at file.c:385-386, the subset comparison at file.c:391-400,xindex_is_subsetat file.c:322-329 and its use at file.c:401-407.target=is written at file.c:73-76;ouidis set at file.c:413-415.- The hook: lsm.c:367-384.
- For the known discrepancy: the link check builds names with the profile's path flags only (file.c:345-356); the default at unpack time (policy_unpack.c:1246-1252); the parser writing the flags (parser_interface.c:530-545).
05 Three spellings, three levels of protection
PATH rwl,: any target, subset test on. link NEW -> OLD,: target restricted, no subset test. link subset NEW -> OLD,: both. rw on a directory plus link DIR/* -> /**, lets the program give itself rw on any file it can link. This is read from the kernel code; it was not run on a kernel.
Which rules give you which checks? The l letter in an ordinary file rule lets the new name point at any file, but the subset test is always on, so demo can't link what it can't already use. A link rule with an arrow turns it around: the target is limited to your pattern, and the subset test is off, unless you add the word subset. Now the row to avoid: write access to /var/tmp, plus a link rule from there to /**. Any file may be the target, and nothing is compared. Then the first rule lets demo open the link read-write: as far as AppArmor is concerned, demo can write the shadow file. So prefer the letter, and keep arrow targets narrow.
Details and sources
Details
The four rows and their outcomes are derived from the kernel code; they were not run on a kernel. The request is assumed to pass the kernel's own checks first (same mount, fs.protected_hardlinks, directory permissions), and the file's owner and mode still apply to the later open. That is what "as far as AppArmor is concerned" stands for.
/var/tmp/** rwl,: the letter allows any file as the target, with the subset test. The manual states the equivalence:/foo l,maps tolink subset /foo -> /**,(apparmor.d.pod:1165-1171), and "the new link MUST have a subset of permissions as the original file (with the exception that the destination does not have to have link access)" (apparmor.d.pod:1105-1110).link /var/tmp/* -> /srv/data/**,: the target must match/srv/data/**, and nothing is compared./etc/shadowis refused withinfo="target restricted".link subset /var/tmp/* -> /srv/data/**,: both the target restriction and the subset test./var/tmp/** rw,withlink /var/tmp/* -> /**,: the link is allowed, and therwrule then applies to the new name. This is the combination to avoid.- A fifth case:
/var/tmp/** rwl,with/etc/shadow r,. The subset test fails for write only: the new name would addw. - What the subset test protects against: a profile that may write in one directory and may only read, or not access, files elsewhere cannot give itself more permissions on those files by linking them into the writable directory.
rename()moves a name without a subset test. It needsrwon the old name andwon the new one. A file renamed into a directory whose rule addsxormgains those permissions under the new name.
Read more
- apparmor.d(5): Link rules, apparmor.d(5): l - Link mode
- Link rules (the scenes "subset" and "The l letter"), file access modes, file rules.
for AppArmor developers for security researchers
Code
- The early return for a pair without the subset bit and the comparison: file.c:384-407.
- The permissions
renameasks for: lsm.c:433-442.
06 Linking a file out of a denied directory for security researchers
An l-only rule passes the subset test for any target, because the compared set is empty. A deny on a directory blocks links created in it, not links made from it. Links by unconfined programs are not checked by AppArmor (read from the kernel code).
For researchers: how does a file leave a directory the profile denies? The private files deny covers every name under .ssh, including creating links there. Linking from there to somewhere else is left to the subset test on the destination's rule. Now give the destination nothing but the link letter. The test compares what the new name grants, minus link, against the existing name. That set is empty, so it passes for any target. Demo gains nothing itself, but a second program whose profile allows reading the export directory reads the key. And this assumes a confined creator. Unconfined programs aren't checked, rename has no subset test, and bind mounts make names too. A deny protects a name, not a file.
Details and sources
Details
Everything here is derived from the kernel code: it states what the check, as defined, permits. Nothing was run. The profile publisher, the key name and /srv/export/ are illustrations. This is how the check is defined, not a bug in it.
- The deny on the slide is shipped:
audit deny @{HOME}/.ssh/{,**} mrwkl,(private-files-strict:12). - The caller must still pass the kernel's own checks. Here it does: it owns its own key, so
fs.protected_hardlinkslets it through, and it can write/srv/export/.
Read more
for security researchers
Attack surface
- The empty set. The subset test compares the permissions of the new name, with link removed, against those of the existing name (file.c:395-400). A new name whose only permission is
lleaves nothing to compare, so the test passes for any target. - What
deny ... ldenies. A deny withlis carried by the link pair keyed on the new name: it stops creating a link whose new name is under~/.ssh/. Linking a file from~/.ssh/to another directory is stopped only by the subset test of the rule for that directory, because the deny removes read and write from the existing name, and only if that rule grants more thanl. - Exposure across profiles. The creator gains nothing: it has no read permission on the new name. Every other profile, and every unconfined program, judges the file by its new name.
- Unconfined creators. The link hook does nothing for an unconfined task (lsm.c:377-380). For those,
fs.protected_hardlinksand the file permissions are the only limits. rename()has no subset test. It asks for read, write and delete on the old name and write and create on the new one (lsm.c:433-442); a file moved into a directory whose rule addsxormgains those permissions.- Bind mounts give a file another name as well. They are controlled by mount rules, not link rules.
- Shipped rules with
lin shared or broad locations:owner /tmp/** rwkl,(user-tmp:21);/tmp/ntp* rwl,and/var/tmp/ntp* rwl,in a root daemon's profile, withoutowner(usr.sbin.ntpd:43, usr.sbin.ntpd:68);/** mrwlkix,(usr.sbin.apache2:86);/** rwkl,(ubuntu-helpers:93);file rwl /**,(tar:25);owner @{HOME}/[^.]* rwl,(user-write:20, user-download:20).
for AppArmor developers for security researchers
Code
profile_path_link: file.c:360-407. The hooks for link and rename: lsm.c:367-384, lsm.c:433-442.
07 owner: only your own files can be linked or used
owner on a link or file rule is tested against the existing file's owner. owner /var/tmp/** rwl, lets a program link only files it owns, and grants nothing on a planted link to someone else's file. This is read from the kernel code; it was not run on a kernel.
One word takes most of the sting out of this for shared directories: owner. In the kernel, when demo asks for a link, the owner that owner rules are compared with is the owner of the existing file, for both names. So with an owner rule on /var/tmp, demo can link its own files there. For the shadow file the rule simply doesn't apply: no link permission. It works after the fact too. If somebody else plants a link to a root-owned file there, demo's owner rule still doesn't apply when it opens it. That's how the user-tmp abstraction is written, and how your own rules for shared directories should be. The owner belongs to the file, so it's the same under every name.
Details and sources
Details
Derived from the kernel code; not run on a kernel. ann, the uid 1000 and the file names are illustrations.
- In a link check the owner condition is filled from the existing file and the same condition is used for every match: the new name, the target, and the subset comparison.
- Permissions from
ownerrules count only when the task's fsuid equals that owner. Soowner /var/tmp/** rwl,giveslonly for files the task owns; for any other file the new name has noland the link is denied. - After a link exists, however it was created, an
ownerrule on the new name grants access only if the opener owns the file. The owner is a property of the file and is the same under every name. ouid=in a link record is the owner of the existing file.- Contrast with creating a symlink: there the owner compared is the caller's own fsuid, so an
ownerrule always matches. - The limit:
ownerdoes nothing for a program that runs as root and links root-owned files. ntpd's/tmp/ntp* rwl,has noowner(usr.sbin.ntpd:43), and adding one would not narrow it for root's own files. - The shipped lines:
owner /var/tmp/** rwkl,andowner /tmp/** rwkl,, next to/var/tmp/ rw,and/tmp/ rw,for the directories themselves (user-tmp:15-22). ownerin front of a link rule is accepted by the parser:owner /tmp/foo l -> /tmp/bar1,(ok_link_4.sd).
Read more
- apparmor.d(5): owner, apparmor.d(5): abstractions/user-tmp, apparmor.d(5): Link rules
- The owner qualifier, link rules (the scene on qualifiers), choosing abstractions.
for AppArmor developers for security researchers
Code
aa_path_linkfillscondfrom the existing inode: file.c:443-448.- The owner test in the permission lookup (
aa_lookup_condperms): file.c:202-206, used at file.c:227-228. ouidin the record: file.c:413-415.
08 Reviewing l in a real profile
Give l only where the program calls link(). Prefer the letter (subset test on). Keep link name and target in one tree. Put owner on rules for /tmp and /var/tmp. Keep fs.protected_hardlinks at 1.
Let's read four shipped rules the way a reviewer would. Dovecot's delivery agent has the link letter on its whole mail store. Link name and target fall under the same rule, so links stay inside the store. Klogd has the link letter on one exact pid file. The user-tmp abstraction has it on /tmp, a shared directory, with owner in front: your own files only. And ntpd, a root daemon, has it in /tmp without owner. There the subset test is the only limit. So ask: does the program call link at all? Is it the letter, not an arrow to everything? Do both names stay in one tree? Is owner there when others can write the directory? And no deny rule protects a file that has another name.
Details and sources
Details
The four rules are quoted from the shipped profiles. The right-hand column applies the previous scenes to them: it says what each rule allows in the kernel, read from the code. It is not a finding of a defect in any profile.
@{DOVECOT_MAILSTORE}/** rwkl,(usr.lib.dovecot.dovecot-lda:25);@{run}/klogd.pid krwl,(sbin.klogd:31);owner /tmp/** rwkl,(user-tmp:21);/tmp/ntp* rwl,(usr.sbin.ntpd:43).
The guidance:
- Write the rule for the resolved name: take it from
name=in the denial. - Do not add a rule for a symlink's own path in order to follow it; add one only to create, remove or rename the symlink itself.
- Give
lonly where the program callslinkorlinkat. Prefer the barelletter, which has the subset test, overlink A -> B,withoutsubset. - If a
linkrule is needed, keep the target pattern narrow and inside the same tree as the new name, as the mail store rule does. - Put
owneron write rules for directories shared with other users (/tmp,/var/tmp), so that a name planted there for someone else's file gets no permission. - Do not rely on a
denyfor one path to protect a file that may have other names; a deny matches names, not files. - Keep
fs.protected_hardlinksandfs.protected_symlinksat 1; they cover programs that are not confined. - More shipped
lrules:/var/log/boot.msg rwl,(sbin.klogd:30);/var/lib/ntp/drift rwl,(usr.sbin.ntpd:48);/etc/shadow rwl,and its siblings in the extras profile for passwd (usr.bin.passwd:23-37); and a link rule with a narrow target,owner @{HOME}/.config/QtProject.conf rwl -> @{HOME}/.config/#[0-9]*[0-9],(qt5-settings-write:9). - Programs that write a file with
O_TMPFILEand thenlinkatneedlon the final name andwon the directory entries (linkat_tmpfile.sh:31-49). - Known discrepancy: by reading, the link of such a deleted file fails under a profile that sets any path flag such as
attach_disconnected; not run, and it may be intended. See the scene "The link check in three steps".
09 Where to go from here
Next: syn-link-rules, prac-symlinks, prac-privileged, syn-owner, adm-denials, sec-path-limits, k-match.
A hard link is a second real name, and the name's rules apply. The kernel's own setting stops ordinary users, the profile's link check stops confined programs, and owner limits what a planted link can show you. The link rules deck has the grammar and the subset option in detail. Symlinks are the opposite case, and they have their own deck. And the deck on security-sensitive programs shows where the link letter turns up in root daemons.
Details and sources
Details
- A hard link is a second real name for a file, and the file is judged by the rules that match the name used.
- Three things limit who can create one:
fs.protected_hardlinksfor ordinary users, the profile's link check for confined programs, and the file system's own permissions.ownerlimits what a planted link can expose.
What each deck answers:
- Link rules: the grammar of
link, thelletter andsubset. - Symlinks: the kind of link that is resolved away before the check.
- Profiles for security-sensitive programs: where
lshows up in root daemons. - Choosing abstractions:
user-tmpand itslin/tmp. - The owner qualifier:
owneron write and link rules. - allow and deny: a deny matches names, not files.
- Reading a denial: the link record and its
target=field. - The limits of name-based mediation, matching at run time.
- Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Nothing was run on a live kernel.
Read more
Basis of the statements on this page: the kernel behaviour is read from the source of mainline Linux 7.4 (7.4-rc2, 97d73c825) and the shipped policy from the AppArmor tree at 836052d21 (6.0.0~alpha2). Nothing here was observed on a running kernel. "Derived" means reasoned from that code. The grammar of link rules, the l letter and subset is in syn-link-rules.
The order of checks in linkat
For link(old, new) and linkat(...), in this order:
| Step | What is checked | On failure | Log record |
|---|---|---|---|
| 1 | both names are looked up; they must be on the same mount | EXDEV | none |
| 2 | fs.protected_hardlinks, when it is 1 | EPERM | an audit record of type AUDIT_ANOM_LINK with the text linkat; not an AppArmor record |
| 3 | the security module hook: AppArmor's link check, for confined tasks only | EACCES | apparmor="DENIED" operation="link" with name= and target= |
| 4 | the file system's own checks, such as write and search permission on the directory | the file system's error | none from AppArmor |
link() does not follow a symlink given as the existing name. linkat() follows it only with AT_SYMLINK_FOLLOW; without it the link is made to the symlink itself and target= is the symlink's own path.
The AppArmor link check
Per profile, for a confined task:
- Step 1. Both names are built with the profile's path flags. The existing file's name is built through the mount of the new directory.
- Step 2. The new name must have link permission (
l); otherwise the request is denied. - Step 3. The existing name is matched as the second half of the link pair. Without link permission there the denial carries
info="target restricted". - Step 4. Without the subset bit on the pair, the link is allowed.
- Step 5. With it, the existing name is matched again as an ordinary file, and every permission allowed on the new name other than link must also be allowed on the existing name. With an exec permission on the new name the exec transitions must agree as well, else
info="link not subset of target".
l is needed on the new name only.
| Rule spelling | Target | Subset test |
|---|---|---|
/var/tmp/** rwl, | any file | on |
link /var/tmp/* -> /srv/data/**, | must match /srv/data/** | off |
link subset /var/tmp/* -> /srv/data/**, | must match /srv/data/** | on |
Worked examples for link("/etc/shadow", "/var/tmp/s") by a task that passes the kernel's own checks (derived, not run):
| Profile fragment | Outcome |
|---|---|
/var/tmp/** rw, | denied at step 2: no l; requested_mask="l" denied_mask="l" |
/var/tmp/** rwl, and nothing for /etc/shadow | denied at step 5: /etc/shadow has neither read nor write |
/var/tmp/** rwl, and /etc/shadow r, | denied at step 5, for write only |
/var/tmp/** rw, and link /var/tmp/* -> /srv/data/**, | denied at step 3 with info="target restricted" |
/var/tmp/** rw, and link /var/tmp/* -> /**, | allowed, no subset test; the task can then open /var/tmp/s read-write under the first rule. The combination to avoid |
What the subset test protects against: a profile that may write in one directory and may only read, or not access, files elsewhere cannot give itself more permissions on those files by linking them into the writable directory.
Log records
A denial at step 2, from the libapparmor test suite (testcase_dmesg_link_01.in):
[ 2010.738449] audit: type=1400 audit(1284062308.965:276251): apparmor="DENIED" operation="link" parent=19088 profile="/home/ubuntu/bzr/apparmor/tests/regression/apparmor/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"
A failed subset test (file_xm.in):
type=AVC msg=audit(1676978994.840:1493): apparmor="DENIED" operation="link" profile="cargo" name="/var/tmp/portage/dev-lang/rust-1.67.1/work/rustc-1.67.1-src/build/bootstrap/debug/libbootstrap.rlib" pid=12412 comm="cargo" requested_mask="xm" denied_mask="xm" fsuid=250 ouid=250 target="/var/tmp/portage/dev-lang/rust-1.67.1/work/rustc-1.67.1-src/build/bootstrap/debug/deps/libbootstrap-4542dd99e796257e.rlib"FSUID="portage" OUID="portage"
| Field | Meaning in a link record |
|---|---|
name= | the new name |
target= | the existing file |
ouid= | the owner of the existing file |
requested_mask=, denied_mask= | l when the new name has no link permission; for a failed subset test, the permissions the existing name lacks |
info="target restricted" | the existing file does not match the rule's target |
info="link not subset of target" | set only when exec transitions of the two names disagree |
Not determined: the exact mask letters of a failed subset test for a pair of rw rules. The code reports the permissions of the new name that the existing name lacks, and file_xm.in shows xm; no kernel was available to produce a record for rw.
owner in link checks
- The owner condition of a link check is the owner of the existing file, for both names and for the subset comparison.
- Permissions from
ownerrules count only when the task's fsuid equals that owner. owner /var/tmp/** rwl,: the task can link only files it owns into/var/tmp/; for any other file the new name has nol.- After a link exists, an
ownerrule on the new name grants access only if the opener owns the file. - When a symlink is created, by contrast, the owner compared is the caller's fsuid, so
owneralways matches. - Parser test examples:
owner /tmp/foo l -> /tmp/bar1,(ok_link_4.sd),audit deny owner link subset /alpha/beta -> /tmp/**,(ok_link_audit_deny_owner_subset.sd).
fs.protected_hardlinks
sysctl fs.protected_hardlinks, file /proc/sys/fs/protected_hardlinks, value 0 or 1. With 1, a link is refused with EPERM unless one of these holds:
- the caller's fsuid owns the file, or the caller has
CAP_FOWNER; - the file is a regular file, not setuid, not setgid with group execute, and readable and writable by the caller.
The variable has no initializer in the kernel source, so the kernel's own default is 0. The value on an installed system is set outside both source trees. Documentation: kernel docs: protected_hardlinks.
| Caller | Sysctl | link("/etc/shadow", "/var/tmp/s") |
|---|---|---|
| ordinary user, unconfined | 1 | refused by the sysctl: EPERM |
| root, unconfined | 1 | created: root owns the file and AppArmor is not asked |
| root, confined | 1 | the sysctl lets it through; the profile's link check decides |
| ordinary user, unconfined | 0 | created if the user can write the directory; the file's owner and mode still limit what can be done with it |
A refusal by the sysctl produces no AppArmor record, and no profile rule changes it.
Other ways a file gets another name
| Way | What AppArmor checks | Subset test |
|---|---|---|
rename(old, new) | read, write and delete on the old name (rw), write and create on the new name (w) | none: a file renamed into a directory whose rule adds x or m gains those permissions |
| bind mount | mount rules, not link rules | none |
O_TMPFILE then linkat(fd, "", AT_FDCWD, path, AT_EMPTY_PATH) | the same link check; the existing name is a deleted entry, logged as /path/#NNNNNN. The regression test passes with l on the final name plus w on dir/ and dir/* (linkat_tmpfile.sh:31-49) | as for any link |
Shipped rules with l
| Rule | Source | Shared directory | owner |
|---|---|---|---|
@{DOVECOT_MAILSTORE}/** rwkl, | usr.lib.dovecot.dovecot-lda:25 | no | no |
@{run}/klogd.pid krwl, | sbin.klogd:31 | no | no |
/var/log/boot.msg rwl, | sbin.klogd:30 | no | no |
owner /tmp/** rwkl,, owner /var/tmp/** rwkl, | user-tmp:15-22 | yes | yes |
/tmp/ntp* rwl,, /var/tmp/ntp* rwl, | usr.sbin.ntpd:43, usr.sbin.ntpd:68 | yes | no (a root daemon) |
/var/lib/ntp/drift rwl, | usr.sbin.ntpd:48 | no | no |
/etc/shadow rwl, and siblings | usr.bin.passwd:23-37 | no | no |
owner @{HOME}/[^.]* rwl, | user-write:20, user-download:20 | no | yes |
owner @{HOME}/.config/QtProject.conf rwl -> @{HOME}/.config/#[0-9]*[0-9], | qt5-settings-write:9 | no | yes |
/** mrwlkix, | usr.sbin.apache2:86 | everything | no |
/** rwkl, | ubuntu-helpers:93 | everything | no |
file rwl /**, | tar:25 | everything | no |
Guidance
- Write the rule for the resolved name. Take it from
name=in the denial; where a path is a symlink on some systems and a real file on others, list both. - Do not add a rule for a symlink's own path in order to follow it. Add one only to create, remove or rename the symlink itself.
- Give
lonly where the program callslinkorlinkat. Prefer the barelletter, which has the subset test, overlink A -> B,withoutsubset. - If a
linkrule is needed, keep the target pattern narrow and inside the same tree as the new name. - Put
owneron write rules for directories shared with other users (/tmp,/var/tmp). - Do not rely on a
denyfor one path to protect a file that may have other names. A deny matches names, not files. - Keep
fs.protected_hardlinksandfs.protected_symlinksat 1. They cover programs that are not confined.
for security researchers
Attack surface
All of this is what the kernel code permits; none of it was run.
- An
l-only new name passes the subset test for any target: the compared set is empty. With/srv/export/* l,a task can link a file it cannot read into/srv/export/; a second program whose rules allow/srv/export/* r,then reads it under the new name. - A
denywithl, as inaudit deny @{HOME}/.ssh/{,**} mrwkl,(private-files-strict:12), denies creating a link whose new name is under~/.ssh/. Linking a file out of~/.ssh/is stopped only by the subset test of the destination's rule, and only if that rule grants more thanl. - Other profiles and unconfined programs judge the file by its new name.
- Links created by unconfined programs are not checked by AppArmor.
fs.protected_hardlinksand the file permissions are the only limits for them. renamehas no subset test and can addxormin the destination.- Bind mounts give a second name through mount rules.
- Shipped rules with
lin shared or broad locations are listed in the table above.
Known discrepancies and open points
- Known discrepancy: link of a deleted file under a profile that sets any path flag. By reading, the link check builds both names with the profile's path flags only, the parser writes those flags without the mediate-deleted bit when, for example, only
attach_disconnectedis set, and the kernel then does not apply its default.linkaton anO_TMPFILEdescriptor would fail withENOENTandinfo="Failed name lookup - deleted entry"underflags=(attach_disconnected)and pass without flags. Not run; it may be intended. - Known discrepancy: by reading, the statement that would keep the mediate-deleted default when a profile sends path flags masks a label flag word with a path flag constant and has no effect. Not run; it may be intended.
linkat_tmpfile.shmarks the case "tmpdir and tmpfile (w), link" asxpass, the harness's marker for a known problem. What that records about current kernels was not determined.- No parser or kernel runs were made for this deck. Which sysctl values distributions set is outside both trees.
for AppArmor developers for security researchers
Code
| What | Where |
|---|---|
aa_path_link | file.c:437-467 |
profile_path_link: names, link permission, target, subset | file.c:331-416, file.c:345-356, file.c:360-365, file.c:368-382, file.c:385-386, file.c:391-400 |
xindex_is_subset and its use | file.c:322-329, file.c:401-407 |
target= in the record; ouid | file.c:73-76, file.c:413-415 |
| owner condition: filled, tested | file.c:443-448, file.c:202-206, file.c:227-228 |
apparmor_path_link, apparmor_path_rename | lsm.c:367-384, lsm.c:433-442 |
| name construction | path.c:88-128; deleted entries path.c:160-164 |
| path flags default at unpack | policy_unpack.c:1246-1252 |
| parser writing path flags | parser_interface.c:530-545 |
filename_linkat | namei.c:5996-6010; AT_SYMLINK_FOLLOW namei.c:5988-5989 |
may_linkat, safe_hardlink_source | namei.c:1366-1387, namei.c:1323-1342 |
| the sysctl variable and table | namei.c:1211, namei.c:1226-1234 |
inode_owner_or_capable | inode.c:2770-2785 |
manual: l and its link-rule equivalent | apparmor.d.pod:1105-1110, apparmor.d.pod:1165-1171 |
Roads from here
FILE ACCESS
- Link rules — the grammar of link rules and the l letter and subset
QUALIFIERS
- The owner qualifier — the owner qualifier on write and link rules
- allow and deny — a deny matches names and not files
IN PRACTICE · general-purpose apps
- Choosing abstractions — user-tmp grants l in /tmp
IN PRACTICE · security-sensitive programs
- Symlinks: rules see through them — the other kind of link which is resolved away
- Profiles for security-sensitive programs — where the l permission shows up in root daemons
SECURITY · threat model and limits
- The limits of name-based mediation — the limits of deciding by name
RUNNING THE PARSER
- Reading a denial — reading the link record and its target field
IN THE KERNEL
- Matching at run time — the two-name match in the kernel