The binary policy format
binary layout for AppArmor developers for security researchers
A compiled profile is a stream of tagged elements - names and integers and strings and blobs and structs and arrays. Each profile and child and hat is one unit that starts with a version word. The three DFAs travel as aligned blobs and take most of the bytes. The stream may be compressed with zstd and the cache stores the same bytes. The kernel reads the fields in a fixed order and verifies the tables.
On the map: the dfa engine
▶ Watch this deck — 10 scenes, ~8 min
Worth seeing first
- Table compression — the packed arrays this format wraps
- Permissions in the DFA — the permission masks stored in each row
Part of journeys
- From profile text to kernel tables, step 12 of 13 · previous: Table compression · next: Unpacking and verifying policy (no slides yet)
- How a rule becomes a permission, step 10 of 12 · previous: Permissions in the DFA · next: Matching at run time
01 5009 bytes for three rules
apparmor_parser -S writes the binary policy to stdout: 5009 bytes for the three-rule example, starting with the element version.
Everything the other decks of this district built ends up as one run of bytes. The capital S option makes the parser print it instead of loading it. For demo's three rules that's five thousand and nine bytes. Look at the first lines of a hex dump and you can already make out some of it: the word version, the word profile, the name demo, and then something called aadfa. There's no trace of the profile text, no paths, no globs. It's a stream of named, typed values, and three of those values are the packed tables of the three DFAs. This deck goes through it in order, up to the write that hands it to the kernel.
Details and sources
Details
- The command is
apparmor_parser -Q -S -K demo3.sd, run with the parser built from the AppArmor tree and a feature set that has thepolicyentries the kernel exports; nothing was loaded into a kernel.-Swrites the binary policy to standard output and loads nothing;-Kskips the cache. - The profile (file
demo3.sd):
abi <abi/5.0>,
include <tunables/global>
profile demo /usr/bin/demo {
/etc/demo/** r,
audit deny @{HOME}/.ssh/** rw,
/usr/bin/[a-z]* ix,
}
- The writer is parser/parser_interface.c; the reader is linux:security/apparmor/policy_unpack.c.
- The offsets and values in this deck were decoded from those 5009 bytes with a short script written for the purpose, not with code from the tree.
- For comparison: a one-rule profile compiled with the tree's
abi/5.0feature set is 4529 bytes. - Seen the machine walked? That is How the kernel checks an access.
Read more
- wiki: Apparmorbinarypolicy: design notes, marked work in progress by their authors; where they and the code differ, this deck follows the code.
- apparmor_parser(8); The backend pipeline; How the kernel checks an access.
02 One element: a name, a type, a value
Element codes (parser/parser_interface.c:162-177): 0 U8, 1 U16, 2 U32, 3 U64, 4 NAME, 5 STRING, 6 BLOB, 7 STRUCT, 8 STRUCTEND, 11 ARRAY, 12 ARRAYEND. Stream integers are little-endian. The first element is version.
A value is a type byte followed by data. In front of it there may be a name, which is itself an element: code four, a sixteen bit length, and the characters with a closing NUL. So the first eleven bytes of the stream say: name, version. The next five say u32, and give the number, low byte first. The number is the interface version: kernel ABI seven in the low bits, and above it the parser's ABI and the policy version. The other codes are few: integers of four widths, strings, blobs with a thirty-two bit length, and brackets for structs and arrays. Compiled against the tree's own feature file, the word comes out as plain five.
Details and sources
Details
- The codes are
enum class sd_code(parser_interface.c:162-177). The forms (parser_interface.c:197-331): a name is04, a 16-bit length that includes the NUL, and the bytes (parser_interface.c:252-261); a string is05with the same layout (parser_interface.c:286-297); a blob is06, a 32-bit length and the bytes (parser_interface.c:263-269); an array is0b, a 16-bit count, the elements and0c(parser_interface.c:310-320); a struct is07, the elements and08(parser_interface.c:299-308). - Codes 9 LIST, 10 LISTEND and 13 OFFSET are defined and not written. The kernel's
enum aa_codehas the same values up to ARRAYEND and no OFFSET (policy_unpack.h:63). - The version word is built by
ENCODE_VERSION(parser.h:315-332, parser_common.c:61-63): bits 0-9 are the kernel ABI; when that is above 5, bit 11 is force complain, bits 12-19 the parser ABI (2) and bits 20-27 the policy version (2).kernel_abi_versionis 7 or 6 when the features havepolicy/versions/v7orv6, and 5 otherwise (parser_main.c:1763-1766). - Kernel readers:
aa_unpack_nameX,aa_unpack_u32,aa_unpack_array,aa_unpack_blob,aa_unpack_str(policy_unpack.c:242, policy_unpack.c:291); every bounds check goes throughaa_inbounds(policy_unpack.c:180). verify_header(policy_unpack.c:1442) refuses a kernel ABI below 5 or above 9 with "unsupported interface version" (-EPROTONOSUPPORT). The force complain bit isFORCE_COMPLAIN_FLAG, 0x800 (policy_unpack.c:1224, policy_compat.h:17).- Kernel statements are read from the kernel source and were not run.
- Known discrepancy:
aa_features_supports(features, "policy/versions/v7")is false for a feature set that haspolicy/notify_versions, because the lookup matchesversionsagainst the end ofnotify_versions(features.c:361-444). The tree'sabi/5.0file has that entry, so with it the parser writes version 5, without policy version, parser ABI or force complain bit, and leaves the file class marker out of policydb. This was confirmed by running the tree's parser; the kernel's own feature directory has nonotify_versions.
03 The profile struct, field by field
sd_serialize_profile (parser/parser_interface.c:480-604) writes name, xmatch, flags, capabilities, optional structs, policydb, then the file permission table and DFA. unpack_profile (linux:security/apparmor/policy_unpack.c:1121-1432) reads them in the same order.
Inside the profile struct the fields come in a fixed order. First the name, as a bare string. Then the attachment DFA, as a blob called aadfa, followed by the xmatch length: thirteen, the length of demo's path. Then a small struct of flags: flag bits, the mode, zero for enforce, and audit. Then eight words of capabilities. Then a struct called policydb, with its permission table and its DFA. And last, at the top level again, the file rules: a permission table, a version marker, and the third blob. The kernel asks for each optional field by name, and if the next element has another name, it steps back and moves on.
Details and sources
Details
void sd_serialize_profile(std::ostringstream &buf, Profile *profile, int flattened)(parser_interface.c:480-604); the reader isunpack_profile(policy_unpack.c:1121). All fields, in order (writer lines in parser_interface.c, reader lines in policy_unpack.c):
| # | Field | Written when | Writer | Reader |
|---|---|---|---|---|
| 1 | string: name (parent//child when flattened) | always | 488-493 | 1140-1158 |
| 2 | xmatch: blob aadfa, then u32 xmatch_len | xmatch exists | 496-501 | 1175-1196 |
| 3 | string disconnected | flag attach_disconnected.path= | 504-507 | 1199 |
| 4 | string disconnected_ipc | set, and feature domain/disconnected.ipc | 509-512 | not read |
| 5 | u32 kill | set, and feature domain/kill.signal | 514-517 | 1203-1207 |
| 6 | u32 error | set, and feature policy/profile/error | 519-522 | not read |
| 7 | struct flags: flag bits, mode, audit | always | 524-529 | 1209-1244 |
| 8 | u32 path_flags | any path flag | 530-545 | 1247-1252 |
| 9 | four u32: capability allow, audit, quiet, 0 | always | 549-553 | 1255-1262 |
| 10 | struct caps64: the high halves | always | 555-560 | 1265-1277 |
| 11 | array identity | feature domain/identity | 562-563, 333-344 | not read |
| 12 | struct xattrs: array of names | xattrs= | 565, 458-478 | 1290, 591-620 |
| 13 | struct rlimits: mask, array of 16 u64 | any rlimit | 567, 398-411 | 1295, 667-701 |
| 14 | array net_allowed_af | old network encoding only | 570-584 | not read |
| 15 | struct policydb: perms, blob aadfa, xtable | policydb DFA exists | 586-595 | 1305-1331 |
| 16 | perms, permsv, blob aadfa (file DFA) | file DFA exists | 597-598 | 1333-1352 |
| 17 | struct xtable | file DFA exists and a named exec target | 599-602 | 1075 (in unpack_pdb) |
| 18 | struct end | always | 603 | 1407 |
- The kernel also takes fields this parser does not write:
rename,attach(policy_unpack.c:1169),capsx(policy_unpack.c:1280),secmark(policy_unpack.c:1300),tags,startanddfa_start(policy_unpack.c:1026), and adatastruct (policy_unpack.c:1354). - Fields 4, 6, 11 and 14 are written only for a feature set that has the entry, and the kernel at this commit does not read them. A field the kernel does not know makes the next mandatory read fail ("profile missing flags").
- The flags struct: flag bit 1 is a hat (
PACKED_FLAG_HAT); mode 0 enforce, 1 complain, 2 kill, 3 unconfined, 4 user (policy_unpack.h:32). - Capability words: quiet is
deny & quiet, and audit is limited to allowed capabilities (parser_interface.c:549-558). - Kernel error strings, in the
infofield of the audit record: "bad xmatch", "missing xmatch len", "profile missing flags", "failed to unpack profile flags", "failed to unpack profile capabilities", "failed to unpack policydb", "failed to unpack end of profile" (policy_unpack.c:1126). - Optional fields work through
aa_unpack_nameX, which steps back when the name differs (policy_unpack.c:242). - Kernel statements are read from the kernel source and were not run.
- Known discrepancies, by title: "
attach_disconnected.ipcis dropped without a warning and its bit is written anyway"; "mediate_deletedis packed with the bit the kernel callsPATH_DELEGATE_DELETED".
04 Where the bytes go
Of 5009 bytes, 4040 are the table sets of the three DFAs (1344, 1168, 1528). In the file DFA's 1528 bytes, next and check take 1136.
Let's see where five thousand bytes go. Draw the stream to scale. The attachment DFA's tables: thirteen hundred and forty-four bytes, for fifteen states. policydb: eleven hundred and sixty-eight, for five states. The file DFA: fifteen hundred and twenty-eight, for twenty-two. Together that's four thousand and forty bytes, four fifths of everything. The thin strips between them are the actual profile fields and the two permission tables. And inside each table set the picture repeats: next and check dominate, because of the rule from the tables deck that the arrays reach two hundred and fifty-six slots past the highest base. So a profile with almost no rules still weighs a few kilobytes.
Details and sources
Details
- The elements of the 5009-byte stream (offsets hexadecimal; decoded from the
-Soutput made with a feature set that has the kernel'spolicyentries):
| Offset | Element | Value |
|---|---|---|
| 0000 | name version, u32 | 0x202007 |
| 0010 | name profile, struct | |
| 001c | string | demo |
| 0024 | name aadfa, blob | size 1350 = 6 pad + table set of 1344 at 0038 (xmatch, 15 states) |
| 0578 | u32 | xmatch_len 13 |
| 057d | name flags, struct of 3 u32 | 0, 0 (enforce), 0 |
| 0597 | 4 u32 | capability allow, audit, quiet, 0: all 0 |
| 05ab | name caps64, struct of 4 u32 | all 0 |
| 05cb | name policydb, struct | |
| 05d8 | name perms, struct: version 1, array of 2 rows | allow 0x8000, 0x8004 |
| 0683 | name aadfa, blob | size 1175 = 7 pad + table set of 1168 at 0698 (5 states) |
| 0b28 | struct end (policydb) | |
| 0b29 | name perms, struct: version 1, array of 8 rows | allow 0x200 four times, 0x244 twice, 0x10201 twice |
| 0d78 | name permsv, u32 | 3 |
| 0d87 | name aadfa, blob | size 1531 = 3 pad + table set of 1528 at 0d98 (22 states) |
| 1390 | struct end (profile) | total 0x1391 = 5009 |
- Inside the file table set: header at 0d98, accept 0db0, accept2 0e18, base 0e80, default 0ee8, next 0f20, check 1158.
- A permission table row is 14 u32 of 5 bytes each: 140 bytes for 2 rows, 560 for 8.
- For comparison (tree's
abi/5.0feature set): the one-rule profile of 4529 bytes has DFAs of 15, 5 and 13 states and 3840 bytes of table sets; a profile with three abstractions is 46041 bytes for 1695 states in the file DFA. - Why the minimum: the arrays extend 255 slots past the highest base (chfa.cc:269-276), which the kernel requires (match.c:188).
- Kernel statements are read from the kernel source and were not run.
Read more
- Table compression: the scenes "The base word" and "The table set". The backend pipeline: sizes of larger profiles.
05 A blob with padding in front
sd_write_aligned_blob (parser/parser_interface.c:274-284) pads so the table set starts at a multiple of 8 within the unit; the blob length includes the pad. unpack_dfa skips size & 7 bytes (linux:security/apparmor/policy_unpack.c:442-468).
The three DFAs travel as blobs: code six, a thirty-two bit length, then the bytes. But the writer wants the table set to start at a multiple of eight, counted from the start of this profile's buffer, so it puts zero bytes in front and counts them into the blob's length. Here: name aadfa, blob, length thirteen fifty, six zero bytes, and at offset fifty-six, the magic number of the table set. The pad isn't stored anywhere. The kernel recomputes it: a table set is always a multiple of eight long, so the pad is just the low three bits of the blob size. The blob length is little-endian; the size inside the table set is big-endian.
Details and sources
Details
sd_write_aligned_blob(parser_interface.c:274-284) writes the pad and the data as one blob;sd_serialize_dfa(parser_interface.c:383-396) writes the optional permission table and then the blob.- The kernel's formula in
unpack_dfaissz = blob - start - ((pos - start) & 7); pad = ALIGN(sz, 8) - sz, withposalready past the blob; that equalssize & 7(policy_unpack.c:442). aa_dfa_unpackcopies each table into its own allocation with unaligned reads (match.c:34), so the alignment of the data in the buffer does not matter to it.- In a buffer with several units the second unit does not start at a multiple of 8, so its DFAs are aligned to the unit, not to the buffer. In the 15416-byte example of the scene "One unit per profile" (a child and a hat; the same under both feature sets), the hat's unit starts at 0x1c96 and its policydb table set at 0x1dd6.
- Byte order: the stream is little-endian (parser_interface.c:207-226), the table set big-endian (chfa.cc:399-415).
- The pads and sizes on the slide were decoded from the 5009-byte stream of the example.
- Kernel statements are read from the kernel source and were not run.
Read more
- Table compression, scene "The table set"; Unpacking and verifying policy.
06 Permission rows and the exec name table
perms: version 1 and an array of rows of 14 u32 (parser/parser_interface.c:346-374). permsv 3 follows the file table. xtable: names for exec slots 4 to 15, written inside policydb and after the file DFA (413-456, 590-602).
The DFAs don't travel alone. In front of the policydb blob and in front of the file blob sits a struct called perms: a version number, and an array of rows. Each row is fourteen thirty-two bit words. You know allow, deny, prompt, audit, quiet and xindex from the permissions deck. The others are zero. For our example the file table has eight rows, and after it comes permsv equals three, which tells the kernel that accept2 carries the owner flag. Give a profile exec rules with named targets and one more structure appears: xtable, an array of the target names. A row's xindex points into it.
Details and sources
Details
- Row field order: reserved, allow, deny, subtree, cond, kill, complain, prompt, audit, quiet, hide, xindex, tag, label (parser_interface.c:346-362). The table is written when
kernel_supports_permstable32_version >= 2and it is not empty (parser_interface.c:387-390);permsvis written at parser_interface.c:376-380. - The row values on the slide are from the 5009-byte stream of the three-rule example.
- In the kernel:
unpack_perms_table(policy_unpack.c:925);unpack_permrefuses a version other than 1 (policy_unpack.c:905);unpack_pdb(policy_unpack.c:968): with a table the accept table is an index and accept2 is expected only whenpermsvis above 2 (policy_unpack.c:996); without a table both accept tables are required (policy_unpack.c:1002). - The xtable dump is from a different profile, compiled with
apparmor_parser -Q -K -Sand a feature set that has the kernel'spolicyentries (15416 bytes; the tree'sabi/5.0feature set gives the same size and the same table):
abi <abi/5.0>,
profile :ns1:demo /usr/bin/demo flags=(complain) {
capability net_bind_service,
set rlimit nofile <= 1024,
/usr/bin/demo-helper Px -> demo-helper,
/usr/bin/other Px -> :ns2:other,
/usr/lib/demo/worker Cx -> worker,
profile worker { /tmp/w r, }
^admin { /etc/demo/admin.conf rw, }
}
- The three names are not in the order of the three rules:
demo//worker(theCxrule, written last) comes first anddemo-helper(written first) comes last. The array is at 0x0bd8 insidepolicydband again after the file DFA. sd_serialize_xtable(parser_interface.c:413-456) writes nothing when slot 4 is empty (parser_interface.c:417-418); a target in another namespace is written as:ns, NUL, name, NUL (parser_interface.c:433-449). The index in a row is the slot minus 4 (policy_compat.cc:59-62). The table is written insidepolicydband after the file DFA (parser_interface.c:590-602). The xmatch DFA has no table.- In the kernel:
unpack_strs_table(e, "xtable", false, &pdb->trans)(policy_unpack.c:1075, policy_unpack.c:528);process_strs_entryrefuses an entry that starts with NUL or white space and turns the NUL after a namespace back into:(policy_unpack.c:470);verify_permschecks each table index and trims unused tail entries (policy_unpack.c:1534). - Kernel statements are read from the kernel source and were not run.
- Known discrepancy: array counts and string lengths are 16 bit with no check on the writer side (parser_interface.c:286-292, parser_interface.c:310-315); latent.
- Known discrepancy:
sd_serialize_xtableskips empty slots, which would shift later indexes if the table ever had a gap (parser_interface.c:417-430); not determined whether it can. - Known discrepancy, by title: "
->on a rule without exec or link permission is accepted and takes an exec table slot".
07 One unit per profile, child and hat
__sd_serialize_profile writes a profile and then each child and hat as its own unit named parent//child (parser/parser_interface.c:683-791). aa_unpack loops over the units (linux:security/apparmor/policy_unpack.c:1745-1838).
In the profile text, a child profile or a hat sits inside its parent's braces. In the stream it doesn't. The writer serialises the parent, then calls the same function again for each child and hat, and each becomes a separate unit after the parent: its own version element, its own profile struct, and a flattened name, parent//child. A hat has one flag bit set to say so. Here's a profile in a namespace with a child and a hat: three units in a row. The kernel loops over the buffer until it runs out. The twelve bytes that open each unit, the name version plus the u32 code, also mark where a unit begins.
Details and sources
Details
sd_serialize_top_profile(parser_interface.c:666-681) writesversion, thennamespacewhen the profile has one, then the profile struct; the name is flattened toparent//childwhen the profile has a parent (parser_interface.c:488-490).__sd_serialize_profile(parser_interface.c:683-791) then callsload_flattened_hats(parser_interface.c:783-786, parser_policy.c:70-89).- The example on the slide, compiled with
apparmor_parser -Q -K -Sand a feature set that has the kernel'spolicyentries (the tree'sabi/5.0feature set gives the same size and offsets):
abi <abi/5.0>,
profile :ns1:demo /usr/bin/demo flags=(complain) {
capability net_bind_service,
set rlimit nofile <= 1024,
/usr/bin/demo-helper Px -> demo-helper,
/usr/bin/other Px -> :ns2:other,
/usr/lib/demo/worker Cx -> worker,
profile worker { /tmp/w r, }
^admin { /etc/demo/admin.conf rw, }
}
- Its output is 15416 bytes with units at 0x0000 (
demo, withnamespacens1), 0x1c96 (demo//admin, flags 1, 0, 0) and 0x3027 (demo//worker). The first unit also has mode 1 (complain), capability allow 0x400 andrlimitswith mask 0x80 and 16 values. The slide draws the bodies of the child and the hat as{ ... }; with empty bodies the output is 13361 bytes and the units start at 0x0000, 0x1c96 and 0x2e5f. - In the kernel,
aa_unpack(policy_unpack.c:1745) loops over the units; the version element is required only for the first unit (policy_unpack.c:1761).verify_headerreports anamespacethat differs from an earlier unit's as "invalid ns change" (policy_unpack.c:1442). - Who uses the 12 bytes
\x04\x08\x00version\0\x02as a marker. The kernel does not search for them:aa_unpackparses unit after unit in order (policy_unpack.c:1759). libapparmor splits a buffer at\x04\x08\x00version\0(11 bytes) and writes the units one by one, for kernels withoutset_load(kernel_interface.c:68-124). The kernel uses its 12-byteaa_hdr_magiconce, to recognise an uncompressed stream behind an 8-byte user header (apparmorfs.c:604, apparmorfs.c:649). The parser uses the same 12 bytes, followed by the version word, to accept a cache file that is not compressed (policy_cache.c:36-69). - Kernel statements are read from the kernel source and were not run.
- Known discrepancies, by title: "Children and hats of a profile that names its namespace are serialised without the namespace"; "A child or hat that the kernel refuses is reported and then ignored: exit status 0"; "next_profile_buffer reads past the end of the policy buffer on kernels without set_load".
Read more
08 Compressed, and cached
With policy/compressed_load and policy/set_load the stream is zstd-compressed (level 3 unless -c, -O compress-default or -O compress-small): the 5009 bytes become 565 in all, an 8-byte header and a 557-byte frame. A cache file that is not compressed is accepted by its version marker and version word (parser/policy_cache.c:36-69); a compressed one by its header.
Two things can happen to the stream on its way. If the kernel's feature set says it can load compressed policy, the parser compresses each unit with zstd. Printed to standard output, our five thousand bytes become five hundred and sixty-five: an eight byte header with a version and the level, then the frame. The level you get without asking is three. The other thing is the cache. A cache file holds this stream as it is, or with compression as that header and one frame. Before using one, the parser checks how it starts: the version marker and the version word it would write today, or for a compressed file the header.
Details and sources
Details
set_compression_level(parser_main.c:480-506, constants at parser.h:98-100): an explicit-clevel is kept; otherwise there is no compression unless the kernel has bothpolicy/set_loadandpolicy/compressed_load; then the level is 10 with-O compress-default, 20 with-O compress-small, else 3.compress_policy_zstdcompresses one unit (parser_interface.c:646-664). For-Sand-othe output isstruct compr_user_header(version 1, level, six bytes of padding) followed by the frame (lib.c:46-69, apparmor_private.h:41-47).- The 565 bytes and the first twelve bytes on the slide come from compiling the three-rule example with
-Sand a feature set that has the kernel'spolicyentries pluscompressed_load: 565 bytes in all, an 8-byte header and a 557-byte frame. The header is written for-S,-oand cache files (parser_interface.c:757-763, policy_cache.c:336); a direct load writes the bare frame (parser_interface.c:747-756). The one-rule profile of 4529 bytes compresses to 497. - The cache. While a file is compiled, the temporary cache file receives the uncompressed units (parser_interface.c:768-770). Without compression that file is installed as it is. With compression,
install_compressed_cachereads it back, compresses all units of the file into one zstd frame and installs the 8-byte header plus that frame (parser_main.c:1428-1435, policy_cache.c:311-343). - What the parser checks before using a cache file. A compressed file:
is_valid_precompressed_profilelooks at the header version, the zstd magic and the level (policy_cache.c:80-96, policy_cache.c:136-146, private.c:37-55); the version word is inside the frame and is not tested. A file that is not compressed:valid_cached_file_versioncompares the first 16 bytes, the 12-byteversionmarker and the version word the parser would write now (policy_cache.c:36-69, called at policy_cache.c:170-176). So a changed version word makes the uncompressed cache files stale; for compressed ones this check does not run. - In the kernel,
policy_updatelooks for the zstd magic at offset 0 or after an 8-bytestruct aa_user_hdr, or for the 12-byteversionmarker after such a header, and decompresses before unpacking (apparmorfs.c:598). The two feature entries exist only withCONFIG_SECURITY_APPARMOR_COMPRESSED_POLICY(apparmorfs.c:2642). - Errors:
Compression error: out of memory,Compression error: %s(parser_interface.c:651, parser_interface.c:660). Warning, classWARN_DEBUG_CACHE:WARNING: Kernel does not support compressed policies. Defaulting to uncompressed(parser_main.c:501-503). - Kernel statements are read from the kernel source and were not run.
- Known discrepancy: the default level is 3, while
--helpprints "default: 10" and apparmor_parser(8) says "a default value of 10 is used" (parser_main.c:490-498 against parser_main.c:267-277; apparmor_parser.pod:376). - Known discrepancies, by title: "Cache hit on an uncompressed cache loads the profile twice and writes the cache without -W"; "
-ndoes not skip the policy cache, so a cached profile can be loaded into the wrong namespace". - Not determined: the kernel's limits on decompressed size. Cache directory layout and time stamp rules were not re-verified for this deck.
09 The kernel reads it back
Load path: policy_update (decompress), aa_unpack (units), verify_header, unpack_profile, unpack_pdb, unpack_dfa, aa_dfa_unpack, then verify_dfa, verify_dfa_accept_index and verify_perms.
The write lands in policy_update, which decompresses. aa_unpack walks the buffer unit by unit. verify_header checks that the kernel ABI in the version word is between five and nine. unpack_profile asks for each field by name, and aa_dfa_unpack copies each table out into its own allocation. Then comes verification. Every access to the buffer was bounds-checked on the way. With paranoid load on, verify_dfa checks that every base plus two fifty-five is in range, that state numbers are in range, and that diff chains end. Accept values must be valid rows. No row may both allow and deny a bit. What the kernel can't check is whether the tables mean what your profile said. So who may write policy matters.
Details and sources
Details
- The chain:
policy_updatedetects compression and decompresses (apparmorfs.c:598);aa_unpackloops over the units (policy_unpack.c:1745);verify_headerchecks the version word and the namespace (policy_unpack.c:1442);unpack_profiletakes the fields in order (policy_unpack.c:1121);unpack_pdbtakes the permission table, the DFA blob and the name table (policy_unpack.c:968);unpack_dfaskips the pad (policy_unpack.c:442);aa_dfa_unpackchecks the magic and copies the tables out (match.c:333). verify_dfa(match.c:154) runs whenaa_g_paranoid_loadis set (policy_unpack.c:458, lsm.c:2006).verify_dfa_accept_indexchecks, for the file and policydb DFAs, that the accept value, and the accept value plus 1 with the owner flag, are inside the table;verify_permschecks all three tables (policy_unpack.c:1492);verify_permrejects a row with a bit in both allow and deny (policy_unpack.c:1511).aa_dfa_unpackdoes not use the version string orth_ssizeof the table set header.- A kernel ABI below 5 or above 9 gives "unsupported interface version".
- Kernel statements are read from the kernel source and were not run. Nothing in this deck was loaded into a kernel.
- Known discrepancy:
verify_profilecallsverify_dfa_accept_indexforrules->fileandrules->policyonly. Forattach.xmatchwith its ownpermsstruct,aa_lookup_permswould index without a bound (policy.h:156, domain.c:349). Reaching it needs a hand-built stream and the right to administer policy; not reproduced.
10 Where to go from here
Next: unpacking and verifying policy, matching at run time. Operations: the policy cache, loading policy into the kernel. Security: who can change policy. Back: table compression, the backend pipeline.
That's the end of the road that started with three lines of profile text: a tree, thirty-eight states, their permissions, twenty-two states, tables, and now five thousand and nine bytes, or five hundred and sixty-five compressed. From here the story continues in the kernel: later decks go through the unpacking in detail, and through matching, which uses the tables. If you operate systems, later decks on the cache and on loading cover where these bytes are kept and how they get written. And who gets to write them at all is a question for a later deck on policy administration.
Details and sources
Details
- The journey of the three rules: 3 groups in one tree; 38 states; 4 permission sets; 22 states after filter deny and minimize; 277 next/check slots and 8 permission rows; 5009 bytes, 565 compressed.
- Unpacking and verifying policy and Matching at run time: the kernel side. apparmorfs: the files the stream is written to.
- The policy cache, Loading policy into the kernel, The policy cache and kernel interface API.
- Who can change policy. Hats, Child profiles.
- Table compression, Permissions in the DFA, The backend pipeline, How the kernel checks an access.
- Sources for this deck: AppArmor 836052d21 and Linux 97d73c825.
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit 836052d21 (6.0.0~alpha2) was run with -Q -K -S, and the output was decoded with a short script written for the purpose (not code from the tree); nothing was loaded into a kernel. The three-rule example was compiled with a feature set that has the policy entries the kernel exports (version word 0x202007); the other examples with the tree's abi/5.0 file (version word 5). "code" means the parser source, or the kernel source, was read and not run; "derived" means the result was reasoned from that code. Nothing here was observed on a running kernel.
Element encoding
| Code | Name | Form |
|---|---|---|
| 0, 1, 2, 3 | U8, U16, U32, U64 | the code byte, then the integer, little-endian |
| 4 | NAME | 04, 16-bit length including the NUL, bytes; precedes the value it names |
| 5 | STRING | 05, 16-bit length including the NUL, bytes |
| 6 | BLOB | 06, 32-bit length, bytes |
| 7, 8 | STRUCT, STRUCTEND | 07, elements, 08 |
| 11, 12 | ARRAY, ARRAYEND | 0b, 16-bit count, elements, 0c |
| 9, 10, 13 | LIST, LISTEND, OFFSET | defined, not written |
Code: parser_interface.c:162-331; kernel readers at policy_unpack.c:242 and policy_unpack.c:291.
The version word
| Bits | Meaning |
|---|---|
| 0-9 | kernel ABI: 7 or 6 with policy/versions/v7 or v6, else 5 |
| 11 | force complain (only when the kernel ABI is above 5) |
| 12-19 | parser ABI, 2 (only above 5) |
| 20-27 | policy version, 2 (only above 5) |
- 0x202007 with the kernel's
policyentries; 5 with the tree'sabi/5.0(tree). - The kernel refuses a kernel ABI below 5 or above 9: "unsupported interface version" (code).
Profile struct
| # | Field | Written when |
|---|---|---|
| 1 | string: name (parent//child when flattened) | always |
| 2 | blob aadfa (xmatch), u32 xmatch_len | xmatch exists |
| 3 | string disconnected | attach_disconnected.path= |
| 4 | string disconnected_ipc | set, and feature domain/disconnected.ipc |
| 5 | u32 kill | set, and feature domain/kill.signal |
| 6 | u32 error | set, and feature policy/profile/error |
| 7 | struct flags: flag bits, mode, audit | always |
| 8 | u32 path_flags | any path flag |
| 9 | four u32: capability allow, audit, quiet, 0 | always |
| 10 | struct caps64 | always |
| 11 | array identity | feature domain/identity |
| 12 | struct xattrs | xattrs= |
| 13 | struct rlimits: mask, 16 u64 | any rlimit |
| 14 | array net_allowed_af | old network encoding only |
| 15 | struct policydb: perms, blob aadfa, xtable | policydb DFA exists |
| 16 | perms, permsv, blob aadfa (file DFA) | file DFA exists |
| 17 | struct xtable | a named exec target |
| 18 | struct end | always |
- Writer: parser_interface.c:480-604; reader: policy_unpack.c:1121 (code). The line numbers of each field are in the details of the scene "The profile struct, field by field".
- Read by the kernel and not written by this parser:
rename,attach,capsx,secmark,tags,start,dfa_start, adatastruct (code). - Written only for a feature set with the entry, and not read by the kernel at this commit: fields 4, 6, 11, 14 (code).
The running example decoded
| Offset | Element | Value |
|---|---|---|
| 0000 | name version, u32 | 04 08 00 "version\0" 02 07 20 20 00 = 0x202007 |
| 0010 | name profile, struct | |
| 001c | string | demo |
| 0024 | name aadfa, blob | size 1350 = 6 pad + table set of 1344 at 0038 (xmatch: 15 states, accept[14] = 1) |
| 0578 | u32 | xmatch_len 13 |
| 057d | name flags, struct of 3 u32 | 0, 0 (enforce), 0 |
| 0597 | 4 u32 | capability allow, audit, quiet, 0: all 0 |
| 05ab | name caps64, struct of 4 u32 | all 0 |
| 05cb | name policydb, struct | |
| 05d8 | name perms, struct: version 1, array of 2 rows | allow 0x8000, 0x8004 |
| 0683 | name aadfa, blob | size 1175 = 7 pad + table set of 1168 at 0698 (5 states) |
| 0b28 | struct end (policydb) | |
| 0b29 | name perms, struct: version 1, array of 8 rows | allow 0x200 four times, 0x244 twice, 0x10201 twice |
| 0d78 | name permsv, u32 | 3 |
| 0d87 | name aadfa, blob | size 1531 = 3 pad + table set of 1528 at 0d98 (22 states) |
| 1390 | struct end (profile) | total 0x1391 = 5009 |
Tree. Table sets: 1344 + 1168 + 1528 = 4040 bytes; permission tables 140 + 560 bytes; everything else 269 bytes.
DFA blobs
- The blob is the pad followed by the table set; the pad makes the table set start at a multiple of 8 from the start of the unit (parser_interface.c:274-284) (code).
- The kernel skips
size & 7bytes (policy_unpack.c:442) (code). - The stream is little-endian, the table set big-endian (code).
Permission table
perms { version 1, array N [ row ... ] }; a row is 14 u32: reserved, allow, deny, subtree, cond, kill, complain, prompt, audit, quiet, hide, xindex, tag, label (parser_interface.c:346-374) (code).permsv3 follows the file table; above 2 the kernel expects an accept2 table with the owner flag (code).- Kernel checks: version 1; each accept index inside the table; no bit in both allow and deny (code).
Exec name table
xtable: an array of strings for exec slots 4 to 15; a row's xindex is the slot minus 4 (code).- A target in another namespace is written
:ns, NUL, name, NUL; the kernel turns the NUL back into:(code). - Written inside
policydband after the file DFA when permission tables are used (tree).
Units
- A profile, and after it each child and hat, is one unit:
version, an optionalnamespace, and the profile struct (code). - A child or hat is named
parent//child; a hat has flag bit 1 (code, tree). - The 12 bytes
04 08 00 "version\0" 02mark the start of a unit (code).
Compression
| Option | zstd level |
|---|---|
none, kernel has policy/set_load and policy/compressed_load | 3 |
-O compress-default | 10 |
-O compress-small | 20 |
-c N | N |
kernel lacks either entry, no -c | not compressed |
- Header in front of the frame: version 1, level, six bytes of padding (code). The example: 5009 bytes become 565 with
-S(the 8-byte header and a 557-byte frame; a direct load writes the bare frame), starting01 03 00 00 00 00 00 00 28 b5 2f fd(tree). - The kernel finds the zstd magic at offset 0 or after the 8-byte header (code).
Cache file check
- Without compression a cache file is the uncompressed stream. The parser accepts it only if its first 16 bytes are the 12-byte
versionmarker and the version word the parser would write now (policy_cache.c:36-69) (code). - With compression (
policy/compressed_loadandpolicy/set_load) a cache file is the 8-byte header and one zstd frame over all units of the file. The parser accepts it by the header version, the zstd magic and the level; the version word is not tested (policy_cache.c:80-96, policy_cache.c:148-181) (code).
What the kernel verifies
| Check | Function | When |
|---|---|---|
| every access inside the buffer | aa_inbounds | always |
| kernel ABI field of the version word 5 to 9; no namespace change between units | verify_header | always |
| magic number and header flags of a table set | aa_dfa_unpack | always |
| table sizes agree | aa_dfa_unpack | always |
| base + 255 inside next/check; state numbers in range; diff chains end | verify_dfa | paranoid load |
| accept index, and index + 1 with the owner flag, inside the table | verify_dfa_accept_index | file and policydb DFAs |
| xindex in range; no bit in both allow and deny | verify_perms, verify_perm | always |
All rows: code.
Kernel error strings
"unsupported interface version", "invalid ns change", "bad xmatch", "missing xmatch len", "profile missing flags", "failed to unpack profile flags", "failed to unpack profile capabilities", "failed to unpack policydb", "failed to unpack end of profile". They appear in the info field of the audit record (code).
Known discrepancies
- With the tree's
abi/5.0file as kernel features the parser writes version word 5: the lookup ofpolicy/versions/v7matches the end ofnotify_versions(features.c:361-444) (tree). - The default compression level is 3; the help text and the man page say 10 (code).
- Accept indexes of an xmatch DFA with its own permission table are not range-checked by the kernel (code; not reproduced; this parser writes no such table).
- Array counts and string lengths are 16 bit with no check on the writer side (code; latent).
sd_serialize_xtableskips empty slots (code; not determined whether a gap can occur).- By title: "
attach_disconnected.ipcis dropped without a warning and its bit is written anyway"; "mediate_deletedis packed with the bit the kernel callsPATH_DELEGATE_DELETED"; "->on a rule without exec or link permission is accepted and takes an exec table slot"; "Children and hats of a profile that names its namespace are serialised without the namespace"; "A child or hat that the kernel refuses is reported and then ignored: exit status 0"; "next_profile_buffer reads past the end of the policy buffer on kernels without set_load"; "Cache hit on an uncompressed cache loads the profile twice and writes the cache without -W"; "-ndoes not skip the policy cache, so a cached profile can be loaded into the wrong namespace".
Not determined
- Whether kernels that advertise
policy/notify_versionstreat a version 5 stream differently. - Cache directory layout, time stamp rules and the recompress path.
- The kernel's limits on decompressed size.
- Whether the exec table can have an empty slot between two used ones.
Roads from here
START HERE
- How the kernel checks an access — the machine these bytes describe
PROFILE STRUCTURE
- Hats — hats in the profile language
- Child profiles — child profiles in the profile language
SECURITY · threat model and limits
- Who can change policy (no slides yet) — who is allowed to write policy
RUNNING THE PARSER
- The policy cache (no slides yet) — where these bytes are cached
- Loading policy into the kernel (no slides yet) — the load and replace commands
LIBAPPARMOR
- The policy cache and kernel interface API (no slides yet) — the library calls that write the stream
IN THE KERNEL
- Unpacking and verifying policy (no slides yet) — the kernel code that reads this stream
- Matching at run time — verification and use of the DFA tables
- apparmorfs (no slides yet) — the files the stream is written to
THE DFA ENGINE · libapparmor_re
- Table compression — the table set inside every blob
- Permissions in the DFA — what the rows of a permission table mean
- The backend pipeline — where the three DFAs come from