File access modes

r w a l k m for application developers for security researchers

What each file permission letter allows in the kernel. w covers create and delete and attribute changes. a covers only opens for append. k is locking and m is mapping a file as executable.

On the map: file access

▶ Watch this deck — 9 scenes, ~7 min

Worth seeing first

  • File rules — the rule whose letters this deck explains

Part of journeys

01 Seven letters

FILE ACCESS MODES owner /var/lib/demo/** rwk , r w a l k m x read write append link lock map exec execute r w k ... operation="mkdir" ... requested_mask="c" denied_mask="c" ... there is no letter c in a profile x and l have decks of their own
The rule owner /var/lib/demo/** rwk with its mode word highlighted, the seven file letters r w a l k m x with one word each, and a log record whose requested mask is c, a letter that cannot be written in a profile.

The file letters are r w a l k m and x with a transition type. They may appear in any order.

The rule for demo's state directory ends in three letters: rwk. There are seven such letters, and this rule uses three of them: read, write and lock. They look obvious, and mostly they are. But a few things surprise people. The letter w is also what lets a program create and delete files. The letter a is narrower than you'd guess. And the log sometimes shows a letter, c or d, that you can't write in a profile at all. This deck takes the letters one at a time and tells you which system calls ask for each in the kernel. Two of them, x and l, have decks of their own.

Details and sources

Details

  • The letters a profile may use in a file rule: r w a l k m and x with a transition type. The scanner's set is [RrWwaLlMmkXx] plus the exec forms (parser_lex.l:257-258).
  • The letters the kernel prints in requested_mask and denied_mask come from its own string, x w r a c d k m l, in the kernel (lib.c:253). c (create) and d (delete) exist only there; both are granted by w.
  • A record with c from the log fixtures in the AppArmor tree: apparmor="ALLOWED" operation="mkdir" profile="/usr/sbin/sshd" name="/run/user/1000/kakoune/" ... requested_mask="c" denied_mask="c" (testcase_socklogd_mkdir.in:1).
  • The statements about what the kernel asks for in this deck were read from the kernel source; they were not observed on a running kernel.
  • The manual page describes the letters under "Access Modes" (apparmor.d.pod:1 is its source).

02 The mode word

GRAMMAR r w a l k m MODE: one word exec mode ix px Px cx Cx ux Ux pix ... see exec modes any order, repeats allowed accepted r rw rwk mr rwlk wr = rw refused wa w and a exclude each other rx x needs a type, except in deny rules R W L M old spellings, deprecated P C U exec modes, not old spellings no spaces inside the word; white space or the comma ends it
Syntax diagram: a loop that picks one of r, w, a, l, k, m or an exec mode and may repeat; accepted examples r, rw, rwk, mr, rwlk and wr; refused examples wa and rx.

MODE = ( r | w | a | l | k | m | EXEC MODE )+. w with a is an error. Bare x is valid only after deny.

The mode is a single word. You build it from six plain letters: r, w, a, l, k and m. If the rule is about running the file, you add an exec mode such as ix or px. Order doesn't matter: rw and wr mean the same. Two combinations are refused. The letters w and a can't share a word, and an x with nothing in front of it is valid only in a deny rule. Capital R, W, L and M still parse as old spellings, with a deprecation warning, but capital P, C and U are real exec modes. And keep it one word: white space or the comma ends it.

Details and sources

Details

  • MODE = ( 'r' | 'w' | 'a' | 'l' | 'k' | 'm' | EXEC MODE )+. One word; letters in any order, repeats allowed; white space or a comma ends it.
  • The scanner's definition: MODE_CHARS ([RrWwaLlMmkXx])|(([Pp]|[Cc])[Xx])|(([Pp]|[Cc])?([IiUu])[Xx]) and MODES {MODE_CHARS}+ (parser_lex.l:257-258).
  • w with a in one word: Conflict 'a' and 'w' perms are mutually exclusive. (parser_misc.c:595, parser_misc.c:602; test bad_append_1.sd).
  • A bare x in a rule that is not a deny rule: Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u'. An exec mode in a deny rule: Invalid perms, in deny rules 'x' must not be preceded by exec qualifier 'i', 'p', or 'u' (parser_misc.c:1090-1104).
  • Uppercase R W L M X I are lowered with a warning (parser_misc.c:704-718). Uppercase P, C and U are exec modes: see exec modes and safe and unsafe. A and K are not accepted.
  • The full form of an error is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

Read more

03 r: read

r /etc/demo/** r, demo /etc/demo/demo.conf asks for r open(O_RDONLY) read() readdir needs /etc/demo/ r, mmap(PROT_READ) also checked: a descriptor passed in by another process rename(old, new) old name: r and w the file being exec'ed is not checked for r at open
The program demo, the kernel requests that ask for r (open read-only, read, readdir, mmap with PROT_READ, and rename on the old name) and the file /etc/demo/demo.conf, under the rule /etc/demo/** r.

r allows open for reading, read, directory listing and PROT_READ mappings. A rename needs r and w on the source name.

The letter r is what you'd expect, and a little more. Demo's configuration rule gives r on everything under its configuration directory. That covers opening a file for reading and the reads that follow. Listing the directory needs r on the directory's own name. Mapping a file readable asks for r. A file descriptor received from another process is checked again for whatever it was opened for. The less obvious one is rename: moving a file asks for read as well as write on the old name, so a profile that can write a file but not read it can't rename it. And the program you execute is checked for x, not for r.

Details and sources

Details

All kernel facts are from the kernel source, read and not run.

  • open: the LSM hook apparmor_file_open asks for the permissions computed from the open flags by aa_map_file_to_perms; FMODE_READ gives MAY_READ (lsm.c:498-500, file.h:119-120). A directory opened for listing is an open of the directory's own name.
  • read: hook apparmor_file_permission passes the mask from the VFS (lsm.c:547-550).
  • Receiving a descriptor from another process: hook apparmor_file_receive, with the permissions of the open mode (lsm.c:542-545).
  • mmap or mprotect with PROT_READ asks for MAY_READ (lsm.c:570-571).
  • Rename: hook apparmor_path_rename asks on the old name for MAY_READ | AA_MAY_GETATTR | MAY_WRITE | AA_MAY_SETATTR | AA_MAY_DELETE (lsm.c:433-437).
  • The file named in an exec: its open is not checked for r; the kernel records MAY_EXEC | MAY_READ | AA_EXEC_MMAP for it (lsm.c:482-485).
  • r in a profile also grants reading attributes and open: the old read bit maps to AA_MAY_GETATTR | AA_MAY_OPEN (policy_compat.c:82-83).

Read more

04 w: write, create, delete

w /var/lib/demo/** rw, w write to an open file open for writing, O_TRUNC create: O_CREAT, mkdir, mknod, symlink delete: unlink, rmdir rename (both names) truncate chmod, chown ... operation="mkdir" ... requested_mask="c" ... operation="unlink" ... requested_mask="d" c and d in a log line: add w to create /var/lib/demo/x you need w on /var/lib/demo/x, not on the directory
One letter w fanning out into seven kinds of request: write, open for writing, create, delete, rename, truncate, chmod and chown; log records show create as c and delete as d.

w allows write, create, delete, rename, truncate, chmod and chown. Logs show create as c and delete as d; both are granted by w.

The letter w is the big one. Besides writing to an open file, and opening one for writing, it's the letter that lets demo create a file or a directory, delete it, rename it, truncate it, and change its mode or owner. There are no separate letters for those. The kernel does keep them apart internally, and that shows in the log: a refused mkdir says requested mask c, and a refused unlink says d. When you see c or d, the fix is a w rule. And the rule has to match the new file's own path. Write permission on the directory isn't what the kernel asks for.

Details and sources

Details

All kernel facts are from the kernel source, read and not run.

  • What w grants: the old write bit maps to AA_MAY_SETATTR | AA_MAY_CREATE | AA_MAY_DELETE | AA_MAY_CHMOD | AA_MAY_CHOWN | AA_MAY_OPEN, next to MAY_WRITE and MAY_APPEND themselves (policy_compat.c:80, policy_compat.c:84-86).
  • LSM hooks and what they ask for (lsm.c:327-365):
  • apparmor_path_unlink, apparmor_path_rmdir: AA_MAY_DELETE.
  • apparmor_path_mkdir, apparmor_path_mknod, apparmor_path_symlink: AA_MAY_CREATE.
  • apparmor_path_truncate, apparmor_file_truncate: MAY_WRITE | AA_MAY_SETATTR.
  • apparmor_path_rename asks for MAY_WRITE | AA_MAY_SETATTR | AA_MAY_CREATE on the new name (lsm.c:439-443); apparmor_path_chmod and apparmor_path_chown ask for AA_MAY_CHMOD and AA_MAY_CHOWN (lsm.c:450-458).
  • Open flags: FMODE_WRITE gives MAY_WRITE, O_TRUNC adds MAY_WRITE, O_CREAT adds AA_MAY_CREATE (file.h:117-128).
  • The path checked for create and delete is built from the directory's mount and the entry itself, so a rule must match the object's own name (lsm.c:271-278).
  • Log letters: aa_file_perm_chrs is "xwracd km l " (lib.c:253); setattr, chmod and chown are printed as w, getattr as r (file.c:28-38).
  • Fixture record: operation="mkdir" ... requested_mask="c" denied_mask="c" (testcase_socklogd_mkdir.in:1).

for security researchers

Attack surface

  • w is wider than "write": by the old-format mapping it also grants create, delete, setattr, chmod and chown on every name the rule matches (policy_compat.c:78-98; read from the kernel source, not observed on a running kernel). The only narrower letter is a.
  • Reading attributes is granted on every name that any file rule matches, with or without r: compute_fperms_allow adds AA_MAY_GETATTR unconditionally (policy_compat.c:100-103). By that code a profile cannot hide the existence, size or owner of a file it names for another purpose.
  • a narrows the open, not necessarily the descriptor: whether a later write(2) on a descriptor opened with O_APPEND under an a-only rule is refused was not determined (see "Not determined" in the reference below).
  • The log letters c and d cannot be written in a profile, so a policy cannot allow create without delete, or the reverse.

Read more

05 a: append only

a /var/log/demo.log a, open("/var/log/demo.log", O_WRONLY|O_APPEND) asks for a: allowed open(..., O_WRONLY) asks for w: refused open(..., O_WRONLY|O_APPEND|O_TRUNC) O_TRUNC asks for w open(..., O_WRONLY|O_APPEND|O_CREAT) O_CREAT asks for create w includes a. Writing both in one word is an error.
Under the rule /var/log/demo.log a, four open calls and the permission each asks for: O_APPEND asks for a and is allowed; without O_APPEND, with O_TRUNC or with O_CREAT the open asks for more than a grants.

a grants the append permission only: an open with O_APPEND of an existing file. O_TRUNC, O_CREAT, delete and chmod need w.

Demo should add lines to its log and not be able to rewrite history. That's what the letter a is for. When a file is opened for writing with O_APPEND, the kernel asks for the append permission instead of write, and the append letter grants exactly that. Open without O_APPEND and the request is for w. Add O_TRUNC and it's w again. Add O_CREAT and the open also asks for create, which the append letter doesn't give, so demo can't create the log this way. Deleting, truncating and chmod stay out of reach too. And since w already contains the append permission, you write one letter or the other, not both.

Details and sources

Details

  • Parser: a sets AA_MAY_APPEND; w sets AA_MAY_WRITE | AA_MAY_APPEND; the two letters in one word are an error (parser_misc.c:599-604). Tests: ok_append_1.sd, bad_append_1.sd.
  • Two separate rules, /a a, and /a w,, are merged without error (observed with the released parser 5.0.2).
  • Kernel, read and not run. aa_map_file_to_perms turns the open flags into the request (file.h:117-128):
  • O_WRONLY | O_APPEND: MAY_APPEND replaces MAY_WRITE.
  • O_TRUNC adds MAY_WRITE; O_CREAT adds AA_MAY_CREATE, whether or not the file exists.
  • O_RDWR | O_APPEND: MAY_READ and MAY_APPEND, so the rule needs r as well.
  • The append bit is kept as it is; create, delete, chmod and chown are added only for the write bit (policy_compat.c:80-86).
  • Not determined: whether a later write(2) on a descriptor opened under an a-only rule is allowed by a running kernel. The open records the granted request (lsm.c:502) and each write arrives as MAY_WRITE (lsm.c:547-550, file.c:655-669). The AppArmor regression tests have no append test.

06 k and m: lock and map

k m /var/lib/demo/** rwk, demo /var/lib/demo/state.db flock(), fcntl(F_SETLK) shared lock: k write lock: k and w operation="file_lock" requested_mask="k" /usr/lib/** mr, demo /usr/lib/libdemo.so mmap(PROT_READ|PROT_EXEC) every shared library and the ELF loader need mr /usr/bin/[a-z]* ix, ix already includes m for that path
Left: demo locking /var/lib/demo/state.db under a rule with k; a write lock needs k and w. Right: demo mapping /usr/lib/libdemo.so as executable under a rule with mr; an ix rule already includes m for its path.

k allows flock and fcntl locks (a write lock also needs w). m allows mmap or mprotect with PROT_EXEC; libraries need mr.

Two smaller letters. The letter k is locking: flock and fcntl locks both ask for it, and a write lock asks for w as well. If demo's database complains that it can't lock its file, look in the log for requested mask k. The letter m is for mapping a file into memory as executable code. That's how shared libraries get loaded, which is why library rules read mr. An ix rule adds m for the same path, so a program that stays in demo's profile can map itself. But every library, and the loader too, needs mr in the profile the program runs under.

Details and sources

Details

Kernel facts are from the kernel source, read and not run.

  • Locks: LSM hook apparmor_file_lock asks for AA_MAY_LOCK, plus MAY_WRITE when the command is F_WRLCK (lsm.c:552-560). The log operation is file_lock (audit.h:66).
  • Fixture record: operation="file_lock" requested_mask="k" denied_mask="k" name="/var/run/samba/unexpected.tdb" ... profile="/usr/sbin/nmbd" (testcase14.in:1).
  • Mapping: common_mmap, called from the hooks apparmor_mmap_file and apparmor_file_mprotect, asks for MAY_READ for PROT_READ, MAY_WRITE for a PROT_WRITE mapping that is not MAP_PRIVATE, and AA_EXEC_MMAP for PROT_EXEC (lsm.c:562-595).
  • The file named in an exec is recorded with MAY_EXEC | MAY_READ | AA_EXEC_MMAP without a rule lookup at open (lsm.c:482-485). Shared libraries and the ELF loader are opened and mapped later, under the profile the program runs in.
  • apparmor_parser -X (--readimpliesX, "Map profile read permissions to mr") makes r imply m (parser_main.c:243).

Read more

for AppArmor developers for security researchers

In the code

  • ix implies m: add_implied_ix_mmap adds the mapping bit for the owner and the other half when the priority of the mapping bit is not higher than that of the exec bit (hfa.cc:1497-1524).

07 Fourteen bits, twice for AppArmor developers for security researchers

PARSER AND KERNEL: THE PERMISSION WORD owner (AA_USER_SHIFT 0) other (AA_OTHER_SHIFT 14) onexec / change_profile x 0x1 w 0x2 r 0x4 a 0x8 l 0x10 k 0x20 m 0x40 pux 0x80 unsafe 0x100 inherit 0x200 type 0x3c00 r -> 0x10004 owner r -> 0x4 rw -> 0x3800e w sets write and append: 0xe per half map_old_perms (policy_compat.c:78) r -> MAY_READ | AA_MAY_GETATTR | AA_MAY_OPEN w -> MAY_WRITE | AA_MAY_SETATTR | AA_MAY_CREATE | AA_MAY_DELETE | AA_MAY_CHMOD | AA_MAY_CHOWN | AA_MAY_OPEN a -> MAY_APPEND k -> AA_MAY_LOCK | AA_LINK_SUBSET m -> AA_EXEC_MMAP the parser runs the same mapping when it writes a permission table (libapparmor_re/policy_compat.cc:127)
A 32-bit permission word with a 14-bit owner half and a 14-bit other half; the bits of one half from x 0x1 to the transition type 0x3c00; example values for r, rw and owner r; and the kernel function map_old_perms expanding each bit into the kernel permission set.

parse_sub_perms (parser/parser_misc.c:560) sets bits from parser/immunix.h:35-48; map_old_perms (linux:security/apparmor/policy_compat.c:78-98) expands them.

parse_sub_perms walks the letters and sets bits in a fourteen bit field. parse_perms then copies that field into both halves of one word: owner at shift zero, other at shift fourteen. The owner and other qualifiers just clear a half. Each plain letter is one bit, except w, which sets write and append; that's why rw comes out as 0x3800e. On the kernel side, map_old_perms spreads those few bits over the real permission set, and that's where w picks up create, delete, chmod and chown. The parser calls the same mapping when it builds a permission table itself, so the letter table holds for either format.

Details and sources

for AppArmor developers for security researchers

Details

  • Bits of one half (immunix.h:35-48): AA_MAY_EXEC 0x1, AA_MAY_WRITE 0x2, AA_MAY_READ 0x4, AA_MAY_APPEND 0x8, AA_OLD_MAY_LINK 0x10, AA_OLD_MAY_LOCK 0x20, AA_OLD_EXEC_MMAP 0x40, AA_EXEC_PUX 0x80, AA_EXEC_UNSAFE 0x100, AA_EXEC_INHERIT 0x200, transition type 0x3c00.
  • parse_sub_perms walks the letters (parser_misc.c:560-734); perm32_t parse_perms(const char *str_perms) stores the field at AA_USER_SHIFT 0 and AA_OTHER_SHIFT 14 (parser_misc.c:736-745, immunix.h:24-25).
  • Bit 30 is AA_ONEXEC and AA_CHANGE_HAT, bit 31 is AA_CHANGE_PROFILE (immunix.h:63-65).
  • Dumps from the parser built from the AppArmor tree at 836052d21: /a r, is 0x10004, /a rw, is 0x3800e; owner leaves only the low half.
  • Kernel: map_old_perms keeps the low four bits and adds AA_MAY_GETATTR | AA_MAY_OPEN for read, AA_MAY_SETATTR | AA_MAY_CREATE | AA_MAY_DELETE | AA_MAY_CHMOD | AA_MAY_CHOWN | AA_MAY_OPEN for write, AA_MAY_LINK for 0x10, AA_MAY_LOCK | AA_LINK_SUBSET for 0x20 and AA_EXEC_MMAP for 0x40 (policy_compat.c:78-98). The owner and other halves are read with dfa_user_allow and dfa_other_allow (policy_compat.c:53-70); the exec bits of a half become an index through dfa_map_xindex (policy_compat.c:24-48).
  • compute_fperms_allow adds AA_MAY_GETATTR to every allow set (policy_compat.c:100-103).
  • The parser has the same mapping for the permission tables it writes itself (map_old_perms at policy_compat.cc:127-147, dfa_map_xindex at policy_compat.cc:41-65).

08 Letters the parser refuses

COMMON MISTAKES /var/log/demo.log wa, Conflict 'a' and 'w' perms are mutually exclusive. write w or a, not both /usr/bin/demo-helper rx, Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u' x needs a type /var/lib/demo/lock K, syntax error, unexpected TOK_ID, expecting TOK_MODE k has no uppercase form /etc/demo/demo.conf Rw, Uppercase qualifiers "RWLIMX" are deprecated, please convert to lowercase only with --warn=deprecated mark r, "mark" is four mode letters, not a name
Four faulty rules with the parser's message: wa is a conflict, rx lacks an exec qualifier, K is a syntax error, and Rw gives a deprecation warning; a word such as mark is read as mode letters.

"Conflict 'a' and 'w' perms are mutually exclusive." "Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u'". Uppercase R W L M X I are deprecated spellings of lowercase.

Four ways the parser says no. Put w and the append letter in one word and it reports a conflict: pick one. Write an x with nothing before it in an allow rule and it's refused, because the kernel needs to know which profile the new program gets. A letter that isn't on the list, capital K for instance, isn't a mode, so you get a syntax error that asks for one. Capital R and W are accepted as lowercase, with a deprecation warning you see only on request. One more trap: a word made only of mode letters is always read as a mode, so a name like mark confuses the parser.

Details and sources

Details

Messages of the parser built from the AppArmor tree at 836052d21. The full form is AppArmor parser error for FILE in profile FILE at line N: MESSAGE.

Read more

09 Where to go from here

ROADS r w a l k m x syn-exec-modes which profile runs next syn-safe-unsafe upper and lower case x syn-link-rules l needs more than a letter syn-file-rules syn-globbing syn-owner the rule, the path, the owner half adm-denials requested_mask and denied_mask use these letters, plus c and d re-perms bits become tables k-match the kernel reads them syntax-map every kind of line
The seven letter tiles with roads: from x to syn-exec-modes and syn-safe-unsafe, from l to syn-link-rules, from the whole row to syn-file-rules, syn-globbing and syn-owner, then adm-denials for log records, and re-perms, k-match and syntax-map.

Next: syn-exec-modes for x, syn-link-rules for l, adm-denials for the letters in log records.

You now know what each plain letter buys. The letter x is a subject of its own, because executing a program also decides which profile it runs under, so exec modes is the deck to take next. The letter l needs more than a letter; that's in link rules. The rule these letters sit in, the path patterns they apply to and the owner qualifier each have a deck too. When a denial shows up in the log, its masks use these same letters, and the denials deck shows how to read them. And if you want to watch the bits become tables, there's the permissions deck in the compiler district.

Details and sources

Details

  • r: open for reading, read, directory listing, PROT_READ mappings, the old name of a rename.
  • w: write, create, delete, rename, truncate, chmod, chown; the log shows create as c and delete as d.
  • a: an open with O_APPEND of an existing file, nothing else. k: flock and fcntl locks. m: PROT_EXEC mappings.
  • x needs a transition type and l needs a link target; each has its own deck.
  • Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Kernel behaviour was read from the source and not run.

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment, with nothing loaded into a kernel; "code" means the kernel source of mainline Linux 7.4 (7.4-rc2, 97d73c825) or the parser source was read, not run. Nothing on this page was run against a kernel: every statement about what the kernel asks for or grants is "code".

Grammar

MODE = ( 'r' | 'w' | 'a' | 'l' | 'k' | 'm' | EXEC MODE )+
  • The scanner's letter set is [RrWwaLlMmkXx] plus the exec forms (ix, px, Px, cx, Cx, ux, Ux and the fallback forms such as pix); exec modes are in syn-exec-modes.
  • A mode is one word. Letters may be in any order and may repeat: wr is rw.
  • White space or a comma ends the word. There are no spaces inside it.
  • A word made only of mode letters is always read as a mode, also where a path or a name is expected.
  • Where the mode sits in a rule: syn-file-rules.

Letters

LetterAllowsRequests that ask for itAlso needs
rreadopen for reading; read; listing a directory; mmap or mprotect with PROT_READ; receiving a descriptor from another process; the source name of a renamea rename source also needs w
wwrite, create, delete, attribute changesopen for writing; O_TRUNC; write; create through O_CREAT, mkdir, mknod, symlink; unlink; rmdir; truncate; chmod; chown; both names of a rename; a shared writable mapping; a write locka rename source also needs r; a write lock also needs k
aappendopen for writing with O_APPENDnothing else is granted: see the next section
la hard link with this namelink on the new namea link rule or a matching target: syn-link-rules
kfile locksflock; fcntl locksa write lock (F_WRLCK) also needs w
mmapping the file as executablemmap or mprotect with PROT_EXEClibraries are normally given mr
xexecuteexecvea transition type in allow rules: syn-exec-modes
  • Create, delete and rename are checked on the path of the object itself, built from the directory and the entry name. To create /var/lib/demo/x a rule must give w on /var/lib/demo/x; w on /var/lib/demo/ is not what is asked (code).
  • A symbolic link is a create and asks for w on the new name. It is not a link request and does not need l (code).
  • A private writable mapping does not ask for w; a shared one does (code).

a compared with w

What an open asks for, from the kernel's translation of the open flags (code):

Open flagsThe open asks forUnder a rule with only a
O_WRONLY, O_APPENDappendgranted
O_WRONLYwritenot granted
O_WRONLY, O_APPEND, O_TRUNCappend and writenot granted
O_WRONLY, O_APPEND, O_CREATappend and createnot granted
O_RDWR, O_APPENDread and appendneeds r as well
  • a grants the append permission and nothing else: no create, delete, truncate, chmod or chown.
  • w sets both the write and the append bit, so every request that a satisfies is also satisfied by w.
  • w and a in one mode word are an error. Two separate rules, /a a, and /a w,, are merged without error (tree).
  • Whether later write calls on a descriptor opened under an a-only rule are allowed was not determined from the code alone and was not tested.

Letters in log records

The kernel prints requested_mask and denied_mask with its own letter string, x w r a c d k m l (code).

Letter in the logMeaningProfile letter that grants it
ccreatew
ddeletew
wwrite; also chmod, chown and other attribute changesw
rread; also reading attributesr
aappenda or w
klockk
mexecutable mappingm
llinkl
xexecutean exec mode

Sample records, shortened, from the log fixtures in the AppArmor tree:

apparmor="ALLOWED" operation="mkdir" profile="/usr/sbin/sshd" name="/run/user/1000/kakoune/" ... requested_mask="c" denied_mask="c" ...
operation="file_lock" requested_mask="k" denied_mask="k" name="/var/run/samba/unexpected.tdb" ... profile="/usr/sbin/nmbd"

Reading denial records: adm-denials.

Things that are implied

  • w includes a.
  • ix adds m on the same path, unless a rule of higher priority decided that bit (code).
  • Reading attributes (getattr) is granted wherever a rule matches the name, with or without r (code).
  • The open that the kernel does for the file named in an exec is not checked for r; the kernel records read and executable mapping for it under the label that ran the exec. Derived from the code of mainline Linux 7.4 and not run on a kernel: a profile reached through px or cx is asked again and needs mr on its own executable, because the recorded permissions count only while the task's label is the one that opened the file (linux:security/apparmor/lsm.c:482-485, linux:security/apparmor/file.c:506-520, 655-669). With ix the label stays, and the parser adds m to an ix rule (parser/libapparmor_re/hfa.cc:1497-1524). Shared libraries and the ELF loader are mapped by the new program and need mr in the profile it runs under (code).
  • apparmor_parser -X makes r imply m: the dumped permission of /a r, changes from 0x10004 to 0x110044 (tree). A parser built with FORCE_READ_IMPLIES_EXEC does the same (code).

Errors and warnings

The parser prints an error as AppArmor parser error for FILE in profile FILE at line N: MESSAGE (tree). The table gives MESSAGE.

MessageCause
Conflict 'a' and 'w' perms are mutually exclusive.wa or aw in one mode word (tree)
Invalid perms, 'x' must be preceded by exec qualifier 'i', 'p', or 'u'an allow rule with a bare x, such as rx (tree); also /a x -> b, (tree)
Invalid perms, in deny rules 'x' must not be preceded by exec qualifier 'i', 'p', or 'u'deny /a px, (tree); deny /a x, is accepted
syntax error, unexpected TOK_ID, expecting TOK_MODEa word that is not a mode where one is expected, such as K (tree)
syntax error, unexpected TOK_MODE, expecting TOK_ID or TOK_SET_VARa word of mode letters where a path is expected, such as mark r, (tree)
Uppercase qualifiers "RWLIMX" are deprecated, please convert to lowercase followed by See the apparmor.d(5) manpage for details.a warning, for uppercase R W L M X I (tree, with --warn=all). Its class is deprecated, which is off by default; --warn=deprecated turns it on. Printed once per run
Internal: unexpected perms character 'C' in inputinternal; needs a mismatch between the scanner and the mode parser (code)
Internal error generated invalid perm 0xNinternal (code)
  • Uppercase P, C and U are not deprecated spellings: they are exec modes. A and K are not accepted at all.

Known discrepancies

  • Both "Invalid perms" messages name the qualifiers 'i', 'p', or 'u' and omit c, although cx is an exec mode.
  • The deprecation text lists RWLIMX, and the code that lowers the letter also names append, but the scanner does not accept an uppercase A.
  • A comment in the parser says a bare x is valid for named transitions; the parser rejects /a x -> b, (tree).

for AppArmor developers for security researchers

Bit layout and mapping

Bits of one half, set by parse_sub_perms (parser/parser_misc.c:560-734) from parser/immunix.h:35-48:

BitNameLetter
0x1AA_MAY_EXECx
0x2AA_MAY_WRITEw (with 0x8)
0x4AA_MAY_READr
0x8AA_MAY_APPENDa, w
0x10AA_OLD_MAY_LINKl
0x20AA_OLD_MAY_LOCKk
0x40AA_OLD_EXEC_MMAPm
0x80AA_EXEC_PUXexec fallback
0x100AA_EXEC_UNSAFEexec
0x200AA_EXEC_INHERITexec
0x3c00transition typeexec
  • parse_perms (parser/parser_misc.c:736-745) stores the field twice: AA_USER_SHIFT 0 and AA_OTHER_SHIFT 14 (parser/immunix.h:24-25). /a r, dumps as 0x10004, /a rw, as 0x3800e (tree); owner leaves only the low half.
  • Bit 30 is AA_ONEXEC and AA_CHANGE_HAT; bit 31 is AA_CHANGE_PROFILE (parser/immunix.h:63-65).
  • Dump tuples read (allow/deny//prompt/audit/quiet) in this layout.

map_old_perms (linux:security/apparmor/policy_compat.c:78-98; the parser's copy is parser/libapparmor_re/policy_compat.cc:127-147):

Old bitKernel permissions
0x1 0x2 0x4 0x8kept: MAY_EXEC, MAY_WRITE, MAY_READ, MAY_APPEND
readadds AA_MAY_GETATTR, AA_MAY_OPEN
writeadds AA_MAY_SETATTR, AA_MAY_CREATE, AA_MAY_DELETE, AA_MAY_CHMOD, AA_MAY_CHOWN, AA_MAY_OPEN
0x10AA_MAY_LINK
0x20AA_MAY_LOCK, AA_LINK_SUBSET (the same value, linux:security/apparmor/include/perms.h:34,49)
0x40AA_EXEC_MMAP
  • AA_MAY_GETATTR is also added to the allow set by compute_fperms_allow (linux:security/apparmor/policy_compat.c:103).
  • aa_map_file_to_perms (linux:security/apparmor/include/file.h:112-131) turns open flags into the request: FMODE_WRITE to MAY_WRITE, FMODE_READ to MAY_READ, O_APPEND replaces MAY_WRITE by MAY_APPEND, O_TRUNC adds MAY_WRITE, O_CREAT adds AA_MAY_CREATE.
  • Log letters: aa_file_perm_chrs (linux:security/apparmor/lib.c:253); the folding of chmod, chown and setattr into w and getattr into r is in linux:security/apparmor/file.c:28-38.
  • The ix implies m step: parser/libapparmor_re/hfa.cc:1497-1524.

Hooks in linux:security/apparmor/lsm.c:

OperationHookRequest
unlink, rmdirapparmor_path_unlink, apparmor_path_rmdir (327-330, 339-342)AA_MAY_DELETE
mkdir, mknod, symlinkapparmor_path_mkdir, apparmor_path_mknod, apparmor_path_symlink (332-348, 360-365)AA_MAY_CREATE
truncateapparmor_path_truncate, apparmor_file_truncate (350-358)MAY_WRITE, AA_MAY_SETATTR
linkapparmor_path_link (367-384)see syn-link-rules
renameapparmor_path_rename (386-448)source: MAY_READ, AA_MAY_GETATTR, MAY_WRITE, AA_MAY_SETATTR, AA_MAY_DELETE; destination: MAY_WRITE, AA_MAY_SETATTR, AA_MAY_CREATE
chmod, chownapparmor_path_chmod, apparmor_path_chown (450-458)AA_MAY_CHMOD, AA_MAY_CHOWN
openapparmor_file_open (465-507)from aa_map_file_to_perms; an exec open is preset to MAY_EXEC, MAY_READ, AA_EXEC_MMAP (482-485)
receive a descriptorapparmor_file_receive (542-545)from the open mode
read, writeapparmor_file_permission (547-550)the mask from the VFS
lockapparmor_file_lock (552-560)AA_MAY_LOCK, plus MAY_WRITE for F_WRLCK
mmap, mprotectcommon_mmap (562-595)MAY_READ for PROT_READ; MAY_WRITE for a shared PROT_WRITE mapping; AA_EXEC_MMAP for PROT_EXEC

How the bits become tables: re-perms. Where the kernel looks them up: k-match.

for AppArmor developers for security researchers

Not determined

  • Whether write(2) on a descriptor opened with O_APPEND under an a-only rule is allowed by a running kernel. The open records MAY_APPEND in the file context (linux:security/apparmor/lsm.c:502) and each write arrives as MAY_WRITE (linux:security/apparmor/lsm.c:547-550; linux:security/apparmor/file.c:655-669). No kernel was available and tests/regression/apparmor has no append test.
  • Whether open with O_APPEND|O_CREAT on a file that already exists is refused under an a-only rule. O_CREAT adds AA_MAY_CREATE to the request whether or not the file exists (linux:security/apparmor/include/file.h:127-128), so by reading it is refused. Not run.
  • Whether the non-accepting state of the file DFA also carries AA_MAY_GETATTR in every policy format, that is, whether stat of a path that no rule matches is ever refused.

Roads from here

START HERE

FILE ACCESS

QUALIFIERS

RUNNING THE PARSER

IN THE KERNEL

THE DFA ENGINE · libapparmor_re