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

01 A profile with more than one name

IDENTITIES profile demo /usr/bin/demo + identities=(demo-role) { demo demo-role the profile and its extra name another profile signal send peer=demo-role, the manual: a role that peers can refer to the kernel the kernel: not sent accepted by the parser today; do not build confinement on it
The head of the profile demo with an identities group, the profile drawn with a second name tag demo-role that another profile could refer to, and a dashed line showing that the tag is not sent to a the kernel.

+ 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, after xattrs=( ) and before flags=( ).
  • 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 identity entry among the files of /sys/kernel/security/apparmor/features/domain/ (apparmorfs.c:2600-2615). Check a running kernel with ls /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

GRAMMAR + identities = ( VALUE ) space or comma word "quoted" at least one repeat: + identities=( ) + identities=( ) profile NAME ATTACHMENT xattrs=(...) + identities=(...) flags=(...) { a fixed seat in the head: after xattrs, before flags profile demo /usr/bin/demo + identities=(demo-role) flags=(complain) { the space after the plus is optional: +identities=(demo-role)
Syntax diagram of an identities group: a plus sign, the word identities, an equals sign and a parenthesised list of one or more values, repeatable, placed in the profile head between the xattrs condition and the flags.

+ 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).
  • identities is 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 SUBPROFILE and HAT (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

for AppArmor developers for security researchers

In the code

03 Three spellings, one list

EXAMPLES profile demo /usr/bin/demo + identities=(demo-role) { ... + identities=(demo-role, web) { ... + identities=(demo-role) + identities=("/srv/demo svc") { the identities of demo demo-role demo-role, web demo-role, /srv/demo svc groups accumulate into one list "/srv/demo svc" a value with a space must be quoted and start with / "demo svc" refused: this rule exists only for identities
Three profile heads for demo: one identities group with one value, one group with two values, and two groups one of which holds a quoted value with a space. Each feeds a single list of identities on the profile.

+ 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) and profile 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.

for AppArmor developers for security researchers

In the code

04 Where identities stop today

WHAT REACHES THE KERNEL + identities=(demo-role) apparmor_parser domain/identity ? kernel features abi <abi/5.0>, both must list it the kernel: no abi/5.0 in this tree: no kernel demo the loaded profile has no identities $ apparmor_parser --warn=all demo (no warning about identities) the manual: policy must not rely on identities for confinement
An identities group flows into apparmor_parser and reaches a gate that asks for the domain/identity feature in both the kernel features and the policy ABI. Both say no, so the line to the kernel is dashed and the loaded profile demo has no identities. No warning is printed.

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/identity must 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 the abi <...>, rule in the profile file (or --policy-features FILE).
  • When the test passes, the parser writes an array named identity with 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/ has change_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.signal and version; no identity (apparmorfs.c:2600-2615).
  • The profile unpacker of the kernel reads no identity field: 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/identity entry.
  • Checked with the parser built from the AppArmor tree at 836052d21: a head with + identities=(demo-role) under abi <abi/5.0>,, dumped with -S, contains the strings flags, path_flags, xattrs and no identity.

05 Identities inside the parser for AppArmor developers for security researchers

PARSER scanner parser_lex.l:826 "+" -> TOK_PLUS, state IDENTITY_VALUE 408-416 identities= -> TOK_IDENTITIES 479-488 LIST_VAL_MODE grammar: identities parser_yacc.y:631-648 identities TOK_PLUS identity_item 650-670 identitiesvals: one or more TOK_VALUE Profile::identities profile.h:394 struct value_list *identities set at parser_yacc.y:441; every group appended to one list features_supports_identity_names parser_main.c:1123-1125 domain/identity kernel AND policy features; tested at parser_interface.c:562 sd_serialize_identity parser_interface.c:333-344 array "identity", one string per value kernel: unpack_profile policy_unpack.c:1265-1293 no "identity" field: caps64, capsx, then unpack_xattrs
The path of identities through the parser: the scanner's IDENTITY_VALUE state, the identities grammar rule, the value list on the Profile object, the features_supports_identity_names check guarding sd_serialize_identity, and the kernel's unpack_profile, which has no identity field.

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} returns TOK_PLUS and pushes IDENTITY_VALUE (parser_lex.l:826). In that state identities/{WS}*= returns TOK_IDENTITIES and switches to EXTCOND_MODE (parser_lex.l:408-416). IDENTITY_CHAR is [^ \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 not identities=, as in profile demo /usr/bin/demo + {, ends with flex scanner jammed and 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 in Profile::identities, a struct 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) writes sd_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() reads caps64, capsx, then calls unpack_xattrs(); there is no identity (policy_unpack.c:1265-1293).

06 Wrong seat, no plus, empty list

COMMON MISTAKES ... flags=(complain) + identities=(demo-role) { identities come before flags syntax error, unexpected TOK_PLUS, expecting TOK_OPEN ... identities=(demo-role) { the plus is required syntax error, unexpected TOK_IDENTITIES, expecting TOK_OPEN ... + identities=() { a group needs at least one value syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUE ... + identities=("demo role") { a space, and no leading slash Space character not allowed in identities: 'demo role' and the one with no message: the kernel lacks the feature and the identities are dropped
Four wrong profile heads and the parser's message for each: identities after flags, identities without a plus sign, an empty identities list, and a quoted value with a space that does not start with a slash. A fifth line notes that dropped identities print nothing.

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 in profile 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 in profile 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

07 Around identities

ROADS profile NAME ATTACHMENT xattrs=(...) + identities=(...) flags=(...) { syn-xattrs written before syn-flags-modes written after syn-profile-name the name itself domain/identity ? adm-features what the kernel advertises syn-abi what the policy asks for k-unpack what the kernel reads from a profile syntax-map the whole profile on one page
The profile head with the identities slot highlighted and roads to its neighbours syn-profile-name, syn-xattrs and syn-flags-modes, to adm-features and syn-abi for the feature check, and to k-unpack and syntax-map.

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 after xattrs=( ) and before flags=( ); all values end up in one list.
  • The parser passes them on only when domain/identity is 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

ElementMeaning
+starts a group. The blank after it is optional: +identities=(foo)
identitiesa keyword only when followed by = (white space may come between)
( ... )the list; values are separated by white space, commas or both
VALUEa 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

ConditionWhat the parser writes
domain/identity is in the kernel's features and in the policy ABIan array named identity, one string per value
either side lacks domain/identitynothing, and no warning, even with --warn=all
  • Mainline Linux 7.4-rc2 does not advertise domain/identity and its profile unpack code reads no identity field (read in the source, not run).
  • The abi/5.0 file in the AppArmor tree has no domain/identity entry.
  • The head profile demo /usr/bin/demo xattrs=(user.demo=trusted) + identities=(demo-role) flags=(complain, attach_disconnected) { under abi <abi/5.0>,, compiled by the tree's parser and dumped with -S, contains the strings flags, path_flags, xattrs and user.demo and no identity.

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 as peer=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

MessageCause
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_OPENidentities written after the flags
syntax error, unexpected TOK_IDENTITIES, expecting TOK_OPENidentities=( ) without the +
syntax error, unexpected TOK_CLOSEPAREN, expecting TOK_VALUEan 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 SUBPROFILE and HAT, 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

StepWhere
+ gives TOK_PLUS and pushes the IDENTITY_VALUE stateparser/parser_lex.l:826
identities before = gives TOK_IDENTITIESparser/parser_lex.l:408-416
IDENTITY_CHAR and the IDENTITY_VALUE value ruleparser/parser_lex.l:265, 472-477
the list in LIST_VAL_MODE; commas are skippedparser/parser_lex.l:479-488
profile_base: the seat between the conditions and the flagsparser/parser_yacc.y:391
identities, identity_item, identitiesvals, identitiesvalparser/parser_yacc.y:631-670
the space checkparser/parser_yacc.y:663-664
prof->identities = $4parser/parser_yacc.y:441
Profile::identities, a struct value_list *; freed in the destructorparser/profile.h:394, parser/profile.cc:60-61
features_supports_identity_names: kernel and policy features intersected for domain/identityparser/parser_main.c:1123-1125, 1000-1003
sd_serialize_identity() and its callparser/parser_interface.c:333-344, 562-563
kernel unpack_profile(): caps64, capsx, then unpack_xattrs(); no identitylinux:security/apparmor/policy_unpack.c:1265-1293
kernel aa_sfs_entry_domain[]: no identity entrylinux:security/apparmor/apparmorfs.c:2600-2615
man page textparser/apparmor.d.pod:540-561, grammar 178-180
fixturesparser/tst/simple_tests/profile/identities/

Roads from here

START HERE

PREAMBLE AND REUSE

PROFILE HEAD

RUNNING THE PARSER

IN THE KERNEL