Profile identities
who the profile is for for application developers for security researchers
The identities part of the profile head. Extra names a profile declares for itself with plus identities. The parser accepts them everywhere a head is written but sends them only to a kernel that advertises the identity feature and mainline Linux 7.4 does not.
On the map: profile head
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- The profile name — the profile head and the name identities stand beside
- The abi rule and the abi files — why the parser drops what the declared ABI lacks
01 A profile with more than one name
+ identities=(demo-role) declares an extra name for the profile. The parser sends identities only to a kernel that advertises domain/identity; the kernel does not, so there they have no effect.
Sometimes one name isn't enough. You rename a profile, or three services play the same role, and every other profile that mentions them by name has to change. Identities are the language's answer: extra names a profile declares for itself, so a peer can say the role instead of the profile. That's the idea, and it's the manual's wording, not something this deck saw working. Now the honest part. The parser reads identities, but it only passes them on to a kernel that says it supports them, and the kernel doesn't. So this deck teaches the syntax and shows you exactly where it stops.
Details and sources
Details
- Syntax:
+ identities=(demo-role)in the profile head, afterxattrs=( )and beforeflags=( ). - Purpose, in the words of the manual page: "It allows a profile to be given a role that peers can refer to instead of naming the profile directly", and a new profile declaring
identities=(unconfined)"keeps working with peers that refer to it as peer=unconfined" (apparmor.d.pod:552-556). This was not verified in code; how a rule that names an identity as its peer is compiled was not determined. - The same page: "Identities require kernel support for the domain/identity feature. If the kernel does not support it the identities are not passed to the kernel and a peer that refers to the profile by an identity will not match it, so policy must not rely on identities for confinement." (apparmor.d.pod:558-561).
- The parser writes identities only when its feature check passes (parser_interface.c:562-563).
- The kernel has no
identityentry among the files of/sys/kernel/security/apparmor/features/domain/(apparmorfs.c:2600-2615). Check a running kernel withls /sys/kernel/security/apparmor/features/domain/. - Nothing on this slide was observed on a kernel that supports the feature.
02 A plus sign, then a list
+ identities=( VALUE ... ), one or more groups, after xattrs=( ) and before flags=( ). Values are words or quoted strings separated by white space or commas; each group needs at least one.
The spelling is unusual for this language, so look at it once. A plus sign, the word identities, an equals sign, and a list in parentheses. Inside the list the values are separated by spaces, commas, or both, and there has to be at least one. You can write several groups one after another, each with its own plus. The group has a fixed seat in the head: after the xattrs condition, before the flags. And the space after the plus is optional, so you'll see it written both ways.
Details and sources
Details
- Grammar:
{ '+' 'identities' '=' '(' VALUE { [','] VALUE } ')' }, in the head as[profile] NAME [ATTACHMENT] [xattrs=(...)] [+ identities=(...)]... [flags=(...)] {. - Zero or more groups. Each starts with its own
+and holds at least one value. - Values are words or quoted strings, separated by white space, commas or both.
- The blank after
+is optional:profile p +identities=(foo) {(ok_identity_10.sd:5). identitiesis a keyword only when=follows it (white space may come between).- Accepted by the parser built from the AppArmor tree at 836052d21:
profile demo /usr/bin/demo + identities=(demo-role, "/srv/demo svc") + identities=(web) {. - The same head is used for top-level profiles, child profiles and hats, so all three accept identities. Known discrepancy: the grammar section of the manual page shows none on
SUBPROFILEandHAT(apparmor.d.pod:178-180), while its text says they are allowed there (apparmor.d.pod:549-550). - More test profiles: parser/tst/simple_tests/profile/identities/.
Read more
- apparmor.d(5): Profile Head and FORMAT.
- xattrs, the seat before; profile modes, the seat after.
for AppArmor developers for security researchers
In the code
- The seat in the head:
profile_base: TOK_ID opt_id_or_var opt_cond_list identities flags TOK_OPEN(parser_yacc.y:391); the productionsidentities,identity_itemandidentitiesvals(parser_yacc.y:631-659). - Lexer:
+returnsTOK_PLUSand pushes the stateIDENTITY_VALUE(parser_lex.l:826);identitiesbefore=returnsTOK_IDENTITIES(parser_lex.l:408-416); the list is read inLIST_VAL_MODE, where commas are skipped (parser_lex.l:479-488).
03 Three spellings, one list
+ identities=(a, b) and + identities=(a) + identities=(b) give the same list. A value containing a space must be quoted and begin with /.
Three ways to write the same kind of thing. One group with one value. One group with two values, a comma between them. Or two groups, each with its own plus. The parser doesn't care which you pick: it pours every value into one list that belongs to the profile. Values can be quoted, too. A value with a space in it has to be quoted, and it also has to start with a slash, a rule that exists only here.
Details and sources
Details
+ identities=(a),+ identities=(a, b)and+ identities=(a) + identities=(b)are all accepted; the last two give the same list.- From the parser's tests:
profile test + identities=(foo, bar) {(ok_identity_02.sd:5) andprofile test + identities=(foo)+ identities=("/bar") {(ok_identity_05.sd:5). - The manual page: "Identities within a group are separated by commas or white space, and several groups accumulate", with the example
profile p + identities=(foo) + identities=("/bar baz") {, which "declares the two identities foo and /bar baz" (apparmor.d.pod:541-547). - Quoting: "An identity that contains white space has to be quoted and has to start with '/'." (apparmor.d.pod:546-547). Otherwise the parser says
Space character not allowed in identities: '%s'. - The order of the values and whether duplicates are removed were not examined.
Read more
for AppArmor developers for security researchers
In the code
- Every group is appended to one list:
identities: identities TOK_PLUS identity_itemwithlist_append($$, $3)(parser_yacc.y:635-643); values are appended the same way (parser_yacc.y:650-659). - The space check is
$1[0] != '/' && strchr($1, ' ')(parser_yacc.y:661-664).
04 Where identities stop today
Identities are written only when domain/identity is in both the kernel's features and the policy ABI. The kernel does not advertise it, and nothing is printed when identities are dropped.
Follow the identity on its way to the kernel. The parser has read it. Before writing it out, it asks one question: does the kernel list the identity feature, and does the policy's ABI list it too? Both have to say yes. On the kernel the answer is no, and the ABI 5.0 file shipped in this source tree doesn't list it either. So the parser leaves the identities out of the binary profile. It does that silently: turn on every warning and you still hear nothing. Which is why you shouldn't rely on identities for confinement, and the manual says the same.
Details and sources
Details
- The parser's test:
domain/identitymust be in the kernel's features and in the policy ABI; the two are intersected (parser_main.c:1000-1003, parser_main.c:1123-1125). - Kernel features come from
/sys/kernel/security/apparmor/features/(or--kernel-features FILE); the policy ABI comes from theabi <...>,rule in the profile file (or--policy-features FILE). - When the test passes, the parser writes an array named
identitywith one string per value (parser_interface.c:333-344); when it fails it writes nothing (parser_interface.c:562-563) and prints nothing, also with--warn=all. - The kernel, read from the source and not run:
features/domain/haschange_hat,change_hatv,unconfined_allowed_children,change_onexec,change_profile,stack,fix_binfmt_elf_mmap,post_nnp_subset,computed_longest_left,attach_conditions/,disconnected.path,kill.signalandversion; noidentity(apparmorfs.c:2600-2615). - The profile unpacker of the kernel reads no
identityfield: after the capability sets it goes on to xattrs (policy_unpack.c:1265-1293). - The ABI file 5.0 in the AppArmor tree has no
domain/identityentry. - Checked with the parser built from the AppArmor tree at 836052d21: a head with
+ identities=(demo-role)underabi <abi/5.0>,, dumped with-S, contains the stringsflags,path_flags,xattrsand noidentity.
Read more
- apparmor.d(5): Attachment Conditionals.
- aa-features-abi(1): extract and compare feature ABIs.
- AppArmor wiki: apparmorpolicyfeaturesABI: how the
abirule pins policy to a feature set. - What the kernel advertises, the abi rule, upstream and Ubuntu kernels.
05 Identities inside the parser for AppArmor developers for security researchers
TOK_PLUS → IDENTITY_VALUE → TOK_IDENTITIES → Profile::identities → sd_serialize_identity() if features_supports_identity_names. In the kernel, unpack_profile() has no identity field.
In the parser the path is short. A plus sign in the head pushes the scanner into the identity value state, where the word identities followed by an equals sign becomes its own token, and the list is read like a flags list. The grammar appends each group to one value list on the profile object. At serialization there is a single check, features_supports_identity_names, and behind it a function that writes an array called identity. The unpack code of the kernel has no such field: after the capability sets it goes straight on to xattrs.
Details and sources
for AppArmor developers for security researchers
Details
- Lexer:
{PLUS}returnsTOK_PLUSand pushesIDENTITY_VALUE(parser_lex.l:826). In that stateidentities/{WS}*=returnsTOK_IDENTITIESand switches toEXTCOND_MODE(parser_lex.l:408-416).IDENTITY_CHARis[^ \t\r\n"!,{}\\=](parser_lex.l:265); the state's own value rule is at parser_lex.l:472-477. - A
+followed by something that is notidentities=, as inprofile demo /usr/bin/demo + {, ends withflex scanner jammedand the parser exits (seen with the parser built from the AppArmor tree at 836052d21; the test file is bad_identity_02.sd). - Grammar:
identities,identity_item,identitiesvals,identitiesval(parser_yacc.y:631-670); the result is stored inProfile::identities, astruct value_list *(profile.h:394), freed in the destructor (profile.cc:60-61). - Feature flag:
features_supports_identity_names = features_intersect(kernel_features, policy_features, "domain/identity")(parser_main.c:1123-1125). - Serialization:
void sd_serialize_identity(std::ostringstream &buf, struct value_list* l)writessd_write_array(buf, "identity", list_sz)and one string per value (parser_interface.c:333-344); the only call is guarded by the flag (parser_interface.c:562-563). - The kernel:
unpack_profile()readscaps64,capsx, then callsunpack_xattrs(); there is noidentity(policy_unpack.c:1265-1293).
Read more
- The lexer, the grammar, the binary policy, unpacking in the kernel.
- AppArmor wiki: Apparmorbinarypolicy (marked WIP by its authors).
06 Wrong seat, no plus, empty list
Identities go before flags=( ) and each group starts with +. identities=() is a syntax error. "Space character not allowed in identities: '...'" means a value with a space that does not begin with /.
The mistakes are few. Put identities after the flags and the parser stops at the plus sign, because that seat is taken. Leave the plus out and it stops at the word identities. An empty pair of parentheses is a syntax error too; a group needs at least one value. And a value with a space that doesn't start with a slash is refused by name. The fifth problem prints nothing, and you already know it: on a kernel without the feature, the identities quietly go nowhere.
Details and sources
Details
Messages are verbatim, seen with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load, nothing loaded into a kernel).
- Identities after the flags:
syntax error, unexpected TOK_PLUS, expecting TOK_OPEN. - No
+, as inprofile p identities=(foo) {(bad_identity_04.sd):syntax error, unexpected TOK_IDENTITIES, expecting TOK_OPEN. - An empty list,
profile p + identities=() {(bad_identity_01.sd):syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE. - A value with a space that does not start with
/, as inprofile p + identities=("a a" "b") {(bad_identity_05.sd:5):Space character not allowed in identities: '%s'. - A
+with nothing after it,profile p + {(bad_identity_02.sd):flex scanner jammed, and the parser exits. - No message at all: identities dropped because the kernel or the policy ABI lacks
domain/identity. - The full form of a parser error is
AppArmor parser error for FILE in profile FILE at line N: MESSAGE.
for AppArmor developers for security researchers
In the code
- The fixed seat comes from
profile_base(parser_yacc.y:391); the "at least one value" rule and the space check fromidentitiesvalsandidentitiesval(parser_yacc.y:650-664).
07 Around identities
Before identities: syn-xattrs. After: syn-flags-modes. The feature check: adm-features and syn-abi. What the kernel reads: k-unpack.
Where next? The neighbours in the head are xattrs before and flags after, and the profile name deck covers the name these identities stand beside. If the feature check is what caught your eye, two decks explain it: one shows what your kernel advertises, the other how the ABI line in a policy file chooses what the parser may use. The unpack deck shows what the kernel reads from a loaded profile. And the syntax map takes you back to the whole profile on one page.
Details and sources
Details
+ identities=( VALUE ... ): one or more groups afterxattrs=( )and beforeflags=( ); all values end up in one list.- The parser passes them on only when
domain/identityis in both the kernel's features and the policy ABI. The kernel does not advertise it, and the parser is silent when it drops them. - The manual page's advice: "policy must not rely on identities for confinement" (apparmor.d.pod:558-561).
- Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2), the kernel-rc2 (97d73c825). Nothing in this deck was run on a kernel.
Read more
Parser results on this page come from the parser built from the AppArmor tree at the commit above, unless a row says otherwise. Kernel statements come from reading the source of mainline Linux 7.4-rc2 (97d73c825); nothing here was run on a kernel.
Grammar
identities: { '+' 'identities' '=' '(' VALUE { [','] VALUE } ')' }
[profile] NAME [ATTACHMENT] [xattrs=(...)] [+ identities=(...)]... [flags=(...)] {
- The groups sit after
xattrs=( )and before the flags. The order is fixed. - Zero or more groups; each group starts with its own
+and holds at least one value. - All values of all groups are collected into one list on the profile:
+ identities=(a, b)and+ identities=(a) + identities=(b)are the same. - The same head rule is used for top-level profiles, child profiles and hats, so all three accept identities.
- Accepted by the tree's parser:
profile demo /usr/bin/demo + identities=(demo-role, "/srv/demo svc") + identities=(web) {.
Keywords
| Element | Meaning |
|---|---|
+ | starts a group. The blank after it is optional: +identities=(foo) |
identities | a keyword only when followed by = (white space may come between) |
( ... ) | the list; values are separated by white space, commas or both |
| VALUE | a word or a quoted string. A value that contains a space must be quoted and must start with / |
Fixtures in the AppArmor tree: parser/tst/simple_tests/profile/identities/ (ok_identity_02.sd: (foo, bar); ok_identity_05.sd: two groups and a quoted "/bar"; ok_identity_10.sd: +identities=(foo)).
What is serialized
| Condition | What the parser writes |
|---|---|
domain/identity is in the kernel's features and in the policy ABI | an array named identity, one string per value |
either side lacks domain/identity | nothing, and no warning, even with --warn=all |
- Mainline Linux 7.4-rc2 does not advertise
domain/identityand its profile unpack code reads noidentityfield (read in the source, not run). - The
abi/5.0file in the AppArmor tree has nodomain/identityentry. - The head
profile demo /usr/bin/demo xattrs=(user.demo=trusted) + identities=(demo-role) flags=(complain, attach_disconnected) {underabi <abi/5.0>,, compiled by the tree's parser and dumped with-S, contains the stringsflags,path_flags,xattrsanduser.demoand noidentity.
What the manual says identities are for
This section repeats apparmor.d(5). It was not verified in code, and how a rule that names an identity as its peer is compiled was not determined.
- A profile can be given a role that peers refer to instead of naming the profile directly.
- A new profile that declares
identities=(unconfined)keeps working with peers that refer to it aspeer=unconfined, which eases a move from unconfined to confined. - Identities require kernel support for
domain/identity. Without it they are not passed to the kernel and a peer that refers to the profile by an identity will not match it, "so policy must not rely on identities for confinement".
Errors and warnings
| Message | Cause |
|---|---|
Space character not allowed in identities: '%s' | a value with a space that does not start with /, such as + identities=("demo role") |
syntax error, unexpected TOK_PLUS, expecting TOK_OPEN | identities written after the flags |
syntax error, unexpected TOK_IDENTITIES, expecting TOK_OPEN | identities=( ) without the + |
syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE | an empty list: + identities=() |
flex scanner jammed (the parser exits) | a + followed by something that is not identities=, such as profile demo /usr/bin/demo + { |
| (no message) | identities dropped because the kernel or the policy ABI lacks domain/identity |
Known discrepancies
- The grammar section of apparmor.d(5) shows no identities on
SUBPROFILEandHAT, while the text of the same page says identities can be declared on child profiles and hats, and the parser's grammar allows them.
for AppArmor developers for security researchers
Code map
| Step | Where |
|---|---|
+ gives TOK_PLUS and pushes the IDENTITY_VALUE state | parser/parser_lex.l:826 |
identities before = gives TOK_IDENTITIES | parser/parser_lex.l:408-416 |
IDENTITY_CHAR and the IDENTITY_VALUE value rule | parser/parser_lex.l:265, 472-477 |
the list in LIST_VAL_MODE; commas are skipped | parser/parser_lex.l:479-488 |
profile_base: the seat between the conditions and the flags | parser/parser_yacc.y:391 |
identities, identity_item, identitiesvals, identitiesval | parser/parser_yacc.y:631-670 |
| the space check | parser/parser_yacc.y:663-664 |
prof->identities = $4 | parser/parser_yacc.y:441 |
Profile::identities, a struct value_list *; freed in the destructor | parser/profile.h:394, parser/profile.cc:60-61 |
features_supports_identity_names: kernel and policy features intersected for domain/identity | parser/parser_main.c:1123-1125, 1000-1003 |
sd_serialize_identity() and its call | parser/parser_interface.c:333-344, 562-563 |
kernel unpack_profile(): caps64, capsx, then unpack_xattrs(); no identity | linux:security/apparmor/policy_unpack.c:1265-1293 |
kernel aa_sfs_entry_domain[]: no identity entry | linux:security/apparmor/apparmorfs.c:2600-2615 |
| man page text | parser/apparmor.d.pod:540-561, grammar 178-180 |
| fixtures | parser/tst/simple_tests/profile/identities/ |
Roads from here
START HERE
- The profile language at a glance — back to the whole profile on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — the policy side of the feature check
PROFILE HEAD
- The profile name — the name these identities stand beside
- Extended attribute conditions — the head part written just before identities
- Profile mode flags — the head part written just after identities
RUNNING THE PARSER
- Kernel features and the policy ABI — how to see which features your kernel advertises
IN THE KERNEL
- Unpacking and verifying policy (no slides yet) — what mainline Linux 7.4 reads from a profile