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

Part of journeys

01 One file, two names, two answers

HARD LINKS profile demo /usr/bin/demo { /var/tmp/** rw, } no rule for /etc/shadow demo open("/etc/shadow") /etc/shadow matched as /etc/shadow: denied /var/tmp/s a hard link one file inode 4711 demo open("/var/tmp/s") matched as /var/tmp/s: allowed by AppArmor ordinary owner and mode checks still apply so the real question is: who can create the second name?
The profile demo allows /var/tmp/** rw and has no rule for /etc/shadow. One file has two names, /etc/shadow and the hard link /var/tmp/s. demo opening /etc/shadow is denied; demo opening /var/tmp/s is allowed by AppArmor.

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/s and /etc/shadow are 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/shadow and denied; open("/var/tmp/s", O_RDWR) is matched as /var/tmp/s and allowed by AppArmor.
  • AppArmor's answer comes on top of the ordinary Unix owner and mode checks. A program that could not open /etc/shadow because 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.

for AppArmor developers for security researchers

Code

03 Who can create the second name?

WHO CAN CREATE THE SECOND NAME link("/etc/shadow", "/var/tmp/s") same mount? else EXDEV protected hardlinks else EPERM AppArmor check else EACCES directory permissions 1 2 3 4 ann, unconfined not her file, and she can't read and write it root, unconfined owns the file not asked link created root, profile demo owns the file the profile decides fs.protected_hardlinks refuses: logged as AUDIT_ANOM_LINK, "linkat"; not an apparmor="DENIED" record for a confined program that runs as root, AppArmor's link check is the control
The call link /etc/shadow to /var/tmp/s passes four gates in order: same mount, the fs.protected_hardlinks setting, the AppArmor link check, and directory permissions. An unconfined ordinary user is stopped by the setting. Unconfined root passes everything and AppArmor is not asked. For root confined by the profile demo, the profile decides.

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 linkat system call: look up both names; EXDEV if they are on different mounts; the fs.protected_hardlinks check; 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_hardlinks is the file /proc/sys/fs/protected_hardlinks, value 0 or 1. With 1, a link is refused with EPERM unless the caller's fsuid owns the file or the caller has CAP_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_LINK with the text linkat. The code read for this deck shows only the record type and that word, so no full log line is shown. It is not an apparmor="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 a capability 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.

for AppArmor developers for security researchers

Code

04 The link check in three steps

THE LINK CHECK demo: link("/etc/shadow", "/var/tmp/s") /var/tmp/** rw, 1 new name /var/tmp/s: is link allowed? no l: denied apparmor="DENIED" operation="link" ... name="/tmp/sdtest.19088-12382-HWH57d/linkfile" ... requested_mask="l" denied_mask="l" fsuid=0 ouid=0 target="/tmp/sdtest.19088-12382-HWH57d/target" a record from the test suite: name= is the new name, target= the existing file link /var/tmp/* -> /srv/data/**, 2 /etc/shadow: allowed as the target? info="target restricted" /var/tmp/** rwl, 3 subset: does the new name grant more? new name: r w · existing name: nothing more: denied /etc/shadow rw, new name: r w · existing name: r w link created step 3 runs only for rules that carry the subset test: next slide
Three steps of the AppArmor link check for link /etc/shadow to /var/tmp/s. Step 1: link permission on the new name; /var/tmp/** rw has no l, denied, with a real denial record. Step 2: is /etc/shadow allowed as the target; a link rule to /srv/data/** says target restricted. Step 3: the subset test; /var/tmp/** rwl grants r and w on the new name and nothing on /etc/shadow, denied; with /etc/shadow rw as well the link is created.

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".
  • l is needed on the new name only. The existing name needs no l.
  • 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 info when 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 rw case of the slide. That is why step 3 shows no masks.
  • linkat(fd, "", AT_FDCWD, path, AT_EMPTY_PATH) on an O_TMPFILE descriptor 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 with info="Failed name lookup - deleted entry". This was not run, and it may be intended.

Read more

for AppArmor developers for security researchers

Code

05 Three spellings, three levels of protection

SAME REQUEST, DIFFERENT RULES link("/etc/shadow", "/var/tmp/s") then open("/var/tmp/s", O_RDWR) /var/tmp/** rwl, any target, subset test on refused: demo has nothing on /etc/shadow /var/tmp/** rw, link /var/tmp/* -> /srv/data/**, target limited, no subset test refused: target restricted /var/tmp/** rw, link subset /var/tmp/* -> /srv/data/**, target limited, subset test on both checks: refused /var/tmp/** rw, link /var/tmp/* -> /**, any target, no subset test link allowed /etc/shadow then open read-write passes the first rule: AppArmor lets demo write it file permissions and the sysctl still apply prefer the l letter; if you need link ... ->, keep the target narrow or add subset
The same request, link /etc/shadow to /var/tmp/s then open it read-write, under four profile fragments. /var/tmp/** rwl: any target, subset test on, refused. rw plus link to /srv/data/**: target restricted, refused. The same with subset: both checks. rw plus link /var/tmp/* to /**: the link is allowed with no subset test and the open is then allowed, so demo can write /etc/shadow as far as AppArmor is concerned.

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 to link 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/shadow is refused with info="target restricted".
  • link subset /var/tmp/* -> /srv/data/**,: both the target restriction and the subset test.
  • /var/tmp/** rw, with link /var/tmp/* -> /**,: the link is allowed, and the rw rule 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 add w.
  • 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 needs rw on the old name and w on the new one. A file renamed into a directory whose rule adds x or m gains those permissions under the new name.

for AppArmor developers for security researchers

Code

06 Linking a file out of a denied directory for security researchers

ATTACK SURFACE audit deny @{HOME}/.ssh/{,**} mrwkl, /srv/export/* l, profile demo: the deny covers names under ~/.ssh demo link("~/.ssh/id_ed25519", "/srv/export/k") l on /srv/export/k: yes target: any subset: only l, nothing to compare: passes one file ~/.ssh/id_ed25519 /srv/export/k link created; demo itself still can't read it /srv/export/* r, profile publisher: another program publisher reads the key under its new name unconfined programs: no link check rename(): no subset test needs rw on the old name: the deny blocks it here bind mounts: mount rules a deny protects a name. Protecting a file means controlling every way to name it.
The profile demo denies everything under ~/.ssh and allows l on /srv/export/*. demo links ~/.ssh/id_ed25519 to /srv/export/k: l is allowed on the new name, any target is accepted, and the subset test has nothing to compare, so it passes. demo still cannot read the file, but a second program, publisher, whose profile allows /srv/export/* r, reads the key under its new name.

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_hardlinks lets it through, and it can write /srv/export/.

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 l leaves nothing to compare, so the test passes for any target.
  • What deny ... l denies. A deny with l is 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 than l.
  • 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_hardlinks and 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 adds x or m gains those permissions.
  • Bind mounts give a file another name as well. They are controlled by mount rules, not link rules.
  • Shipped rules with l in shared or broad locations: owner /tmp/** rwkl, (user-tmp:21); /tmp/ntp* rwl, and /var/tmp/ntp* rwl, in a root daemon's profile, without owner (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

07 owner: only your own files can be linked or used

OWNER owner /var/tmp/** rwl, demo (fsuid 1000) /home/ann/notes.txt owner 1000 link(".../notes.txt", "/var/tmp/n") owner matches: l applies /etc/shadow owner 0 link("/etc/shadow", "/var/tmp/s") not the owner: the rule gives no l demo (fsuid 1000) /var/tmp/s hard link to /etc/shadow, owner 0 open("/var/tmp/s") the owner rule does not apply planted by someone else include <abstractions/user-tmp> has owner /tmp/** rwkl, owner /var/tmp/** rwkl, the owner belongs to the file, so it is the same under every name
With owner /var/tmp/** rwl, demo running as user 1000 can link its own file /home/ann/notes.txt into /var/tmp, because the owner matches. Linking /etc/shadow, owned by root, gets no l. Opening a planted hard link /var/tmp/s to /etc/shadow is not covered by the owner rule either. abstractions/user-tmp contains owner rules for /tmp and /var/tmp.

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 owner rules count only when the task's fsuid equals that owner. So owner /var/tmp/** rwl, gives l only for files the task owns; for any other file the new name has no l and the link is denied.
  • After a link exists, however it was created, an owner rule 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 owner rule always matches.
  • The limit: owner does nothing for a program that runs as root and links root-owned files. ntpd's /tmp/ntp* rwl, has no owner (usr.sbin.ntpd:43), and adding one would not narrow it for root's own files.
  • The shipped lines: owner /var/tmp/** rwkl, and owner /tmp/** rwkl,, next to /var/tmp/ rw, and /tmp/ rw, for the directories themselves (user-tmp:15-22).
  • owner in front of a link rule is accepted by the parser: owner /tmp/foo l -> /tmp/bar1, (ok_link_4.sd).

for AppArmor developers for security researchers

Code

08 Reviewing l in a real profile

FOUR SHIPPED RULES, FOUR QUESTIONS @{DOVECOT_MAILSTORE}/** rwkl, usr.lib.dovecot.dovecot-lda link and target match the same rule links inside the mail store, nowhere else @{run}/klogd.pid krwl, sbin.klogd one exact name links only to files it may also read, write and lock owner /tmp/** rwkl, abstractions/user-tmp shared directory, owner present your own files only /tmp/ntp* rwl, usr.sbin.ntpd (a root daemon) shared directory, no owner only the subset test limits what ntpd can link needed? letter l, not link -> /** same tree owner where shared fs.protected_hardlinks=1 and no deny rule protects a file that has another name
Four shipped rules with the l permission and what each allows: dovecot-lda on the mail store, where link and target match the same rule; klogd on one exact pid file; abstractions/user-tmp on /tmp with owner; ntpd, a root daemon, on /tmp/ntp* without owner, where only the subset test limits it. Below, a checklist: needed, the letter l, same tree, owner where shared, fs.protected_hardlinks=1.

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.

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 l only where the program calls link or linkat. Prefer the bare l letter, which has the subset test, over link A -> B, without subset.
  • If a link rule is needed, keep the target pattern narrow and inside the same tree as the new name, as the mail store rule does.
  • Put owner on 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 deny for one path to protect a file that may have other names; a deny matches names, not files.
  • Keep fs.protected_hardlinks and fs.protected_symlinks at 1; they cover programs that are not confined.
  • More shipped l rules: /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_TMPFILE and then linkat need l on the final name and w on 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

ROADS hard links: a new name, the name's rules l on the new name · target · subset · owner syn-link-rules grammar, l, subset prac-symlinks links that are resolved away prac-privileged l in root daemons syn-owner the owner qualifier adm-denials name= and target= also: sec-path-limits (deciding by name) · k-match (the two-name match) prac-abstractions · syn-allow-deny
Hard links in the centre, with the recap l on the new name, target, subset, owner, and roads to the decks syn-link-rules, prac-symlinks, prac-privileged, syn-owner and adm-denials, and a row naming sec-path-limits, k-match, prac-abstractions and syn-allow-deny.

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_hardlinks for ordinary users, the profile's link check for confined programs, and the file system's own permissions. owner limits what a planted link can expose.

What each deck answers:

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:

StepWhat is checkedOn failureLog record
1both names are looked up; they must be on the same mountEXDEVnone
2fs.protected_hardlinks, when it is 1EPERMan audit record of type AUDIT_ANOM_LINK with the text linkat; not an AppArmor record
3the security module hook: AppArmor's link check, for confined tasks onlyEACCESapparmor="DENIED" operation="link" with name= and target=
4the file system's own checks, such as write and search permission on the directorythe file system's errornone 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.

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 spellingTargetSubset test
/var/tmp/** rwl,any fileon
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 fragmentOutcome
/var/tmp/** rw,denied at step 2: no l; requested_mask="l" denied_mask="l"
/var/tmp/** rwl, and nothing for /etc/shadowdenied 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"
FieldMeaning 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.

  • The owner condition of a link check is the owner of the existing file, for both names and for the subset comparison.
  • Permissions from owner rules 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 no l.
  • After a link exists, an owner rule 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 owner always 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).

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.

CallerSysctllink("/etc/shadow", "/var/tmp/s")
ordinary user, unconfined1refused by the sysctl: EPERM
root, unconfined1created: root owns the file and AppArmor is not asked
root, confined1the sysctl lets it through; the profile's link check decides
ordinary user, unconfined0created 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

WayWhat AppArmor checksSubset 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 mountmount rules, not link rulesnone
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

RuleSourceShared directoryowner
@{DOVECOT_MAILSTORE}/** rwkl,usr.lib.dovecot.dovecot-lda:25nono
@{run}/klogd.pid krwl,sbin.klogd:31nono
/var/log/boot.msg rwl,sbin.klogd:30nono
owner /tmp/** rwkl,, owner /var/tmp/** rwkl,user-tmp:15-22yesyes
/tmp/ntp* rwl,, /var/tmp/ntp* rwl,usr.sbin.ntpd:43, usr.sbin.ntpd:68yesno (a root daemon)
/var/lib/ntp/drift rwl,usr.sbin.ntpd:48nono
/etc/shadow rwl, and siblingsusr.bin.passwd:23-37nono
owner @{HOME}/[^.]* rwl,user-write:20, user-download:20noyes
owner @{HOME}/.config/QtProject.conf rwl -> @{HOME}/.config/#[0-9]*[0-9],qt5-settings-write:9noyes
/** mrwlkix,usr.sbin.apache2:86everythingno
/** rwkl,ubuntu-helpers:93everythingno
file rwl /**,tar:25everythingno

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 l only where the program calls link or linkat. Prefer the bare l letter, which has the subset test, over link A -> B, without subset.
  • If a link rule is needed, keep the target pattern narrow and inside the same tree as the new name.
  • Put owner on write rules for directories shared with other users (/tmp, /var/tmp).
  • Do not rely on a deny for one path to protect a file that may have other names. A deny matches names, not files.
  • Keep fs.protected_hardlinks and fs.protected_symlinks at 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 deny with l, as in audit 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 than l.
  • Other profiles and unconfined programs judge the file by its new name.
  • Links created by unconfined programs are not checked by AppArmor. fs.protected_hardlinks and the file permissions are the only limits for them.
  • rename has no subset test and can add x or m in the destination.
  • Bind mounts give a second name through mount rules.
  • Shipped rules with l in 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_disconnected is set, and the kernel then does not apply its default. linkat on an O_TMPFILE descriptor would fail with ENOENT and info="Failed name lookup - deleted entry" under flags=(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.sh marks the case "tmpdir and tmpfile (w), link" as xpass, 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

WhatWhere
aa_path_linkfile.c:437-467
profile_path_link: names, link permission, target, subsetfile.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 usefile.c:322-329, file.c:401-407
target= in the record; ouidfile.c:73-76, file.c:413-415
owner condition: filled, testedfile.c:443-448, file.c:202-206, file.c:227-228
apparmor_path_link, apparmor_path_renamelsm.c:367-384, lsm.c:433-442
name constructionpath.c:88-128; deleted entries path.c:160-164
path flags default at unpackpolicy_unpack.c:1246-1252
parser writing path flagsparser_interface.c:530-545
filename_linkatnamei.c:5996-6010; AT_SYMLINK_FOLLOW namei.c:5988-5989
may_linkat, safe_hardlink_sourcenamei.c:1366-1387, namei.c:1323-1342
the sysctl variable and tablenamei.c:1211, namei.c:1226-1234
inode_owner_or_capableinode.c:2770-2785
manual: l and its link-rule equivalentapparmor.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

IN PRACTICE · general-purpose apps

IN PRACTICE · security-sensitive programs

SECURITY · threat model and limits

RUNNING THE PARSER

IN THE KERNEL