io_uring rules
io_uring operations for application developers for administrators for security researchers
An io_uring rule allows two features of io_uring. sqpoll is a kernel thread that polls the submission queue. override_creds is running a request with other registered credentials and label= limits whose. Creating a ring and submitting requests are not mediated by this class. A profile compiled for a feature set that lists io_uring denies both features without a rule.
On the map: rule classes
▶ Watch this deck — 9 scenes, ~5 min
Worth seeing first
- Rule conditionals — the conditional syntax the label condition uses
- User namespace rules — the rule class whose defaults work the same way
01 demo asks for a polling thread
io_uring sqpoll, allows a ring with a submission-queue polling thread. A plain ring needs no rule.
Demo handles its sockets with io_uring, the kernel's interface for queuing many requests at once. Setting up a plain ring needs nothing from the profile. But demo wants the kernel to poll its queue with a thread of its own, so it doesn't have to make a system call per batch. That option is one of two io_uring features AppArmor puts behind a rule. Without the rule the setup call is refused. Line twenty-two allows it: io_uring sqpoll.
Details and sources
Details
- The LSM hook is
uring_sqpoll(lsm.c:683-704, registered at lsm.c:1889). It is called when a ring is created withIORING_SETUP_SQPOLL(sqpoll.c:505). - The feature file is
/sys/kernel/security/apparmor/features/io_uring/mask, which readssqpoll override_creds(apparmorfs.c:2679-2682). io_uring sqpoll,is line 22 of demo's profile; it compiles with no warning (run with the tree's parser). The programdemoand its profile are invented for the map.- Kernel statements are read from the kernel source and were not run.
Read more
02 Two permissions and a label
[QUALIFIERS] io_uring [sqpoll | override_creds | (sqpoll, override_creds)] [label=LABEL],.
The keyword is io_uring, with an underscore. Then the permissions: sqpoll, override_creds, or both in parentheses. Then one conditional, label, which only means something for override_creds. Leave the permissions out and you get both. The usual qualifiers go in front.
Details and sources
Details
- The permissions are
sqpollandoverride_creds. A rule without a permission has both. labeltakes=only, one value, and may appear once:only "=" allowed in conditions of io_uring rules,io_uring conditional "label" only supports a single value,io_uring conditional "label" can only be specified once. Blanks around=are allowed (label = /bar, ok_io_uring_09.sd).- Seats:
audit,allow,deny,promptandpriority=are taken;ownerandotherare refused:owner io_uring,givesowner prefix not allowed on io_uring rules(run with the tree's parser). - Known discrepancy, on the bug list as "Variables in
io_uring ... label=are not expanded": the label does not take variables.io_uring override_creds label=@{profile_name},fails when the policy is compiled, withUnable to parse input line '@{profile_name}'and no line number (run with the tree's parser). - Examples in the tree: ok_io_uring_05.sd, ok_io_uring_07.sd.
for AppArmor developers for security researchers
In the code
- The
io_uring_ruleproductions: parser_yacc.y:1620-1627; the permissions: parser_yacc.y:1597-1618.sqpollis 0x10 andoverride_creds0x8 (io_uring.h:29-33); the conditional checks: io_uring.cc:35-50; the default to both: io_uring.cc:62-64; theownerrefusal: io_uring.h:46-52. - Known discrepancy, on the bug list as "Scanner state
IOURING_MODEcan never be entered": the keyword has no scanner state of its own and is scanned inINITIAL; the declared stateIOURING_MODEis never entered. See Known bugs.
03 Two features, not io_uring as a whole
Mediated: IORING_SETUP_SQPOLL and requests that use a registered personality. Not mediated by this class: creating a ring, submitting requests.
It's easy to read io_uring sqpoll as: may use io_uring. It isn't that. AppArmor doesn't mediate creating a ring or submitting requests through this class. What a request does, opening a file or connecting a socket, is still checked by the rules for files and sockets. The class covers exactly two things: starting the polling thread, and submitting a request that runs with credentials other than the task's own. A profile with no io_uring rule refuses those two, and nothing else.
Details and sources
Details
- The kernel has four io_uring LSM hooks; AppArmor registers two,
uring_override_credsanduring_sqpoll(lsm.c:1888-1889).security_uring_allowed(io_uring.c:3401) andsecurity_uring_cmd(uring_cmd.c:236) have no AppArmor implementation. - The default: a confined profile compiled for a feature set with
io_uringmediates the class, so both features are refused without a rule. Without the feature the rule is dropped (warningio_uring rules not enforced, classrule-not-enforced, off by default) and the kernel allows both, because there is nothing to check (lsm.c:627-654). - In the tree only
abi/5.0andabi/5.0-interfacelistio_uring. - "The file and network rules still apply to what a request touches" states the general design of LSM hooks, which sit on the operations themselves; it was not traced for each io_uring request type.
- Kernel statements are read from the kernel source and were not run.
for security researchers
Attack surface
- A profile cannot forbid io_uring as such with this class: there is no permission for ring creation, and passthrough commands (
uring_cmd) are not seen by AppArmor. - A profile pinned to an ABI before 5.0, or with no
abirule, cannot denysqpolloroverride_credseither;deny io_uring,there compiles to nothing.
04 override_creds: whose credentials
io_uring override_creds label=L, allows requests under registered credentials whose label matches L. Without label=, any.
The second feature is subtler. A program can register a set of credentials with its ring, called a personality, and later submit a request that runs with those credentials instead of its own. That's a way to act as someone else, so AppArmor asks. The question is about the label on those credentials. The permission override_creds with label=demo-helper lets demo use credentials that carry the demo-helper label, and nothing else. Leave the label out and any credentials will do. And note that label has no effect on sqpoll.
Details and sources
Details
- The LSM hook is
uring_override_creds(const struct cred *new)(lsm.c:663-682, registered at lsm.c:1888). It is called when a request with registered credentials is submitted (io_uring.c:1989). - For each confined profile that mediates the class, the label of the new credentials is matched and the
override_credspermission is required (lsm.c:642-647, perms.h:51-53). - A personality is a copy of the credentials of the task that registers it, at that moment (register.c:90-96). Its label differs from the submitter's when the ring was registered before a profile change or by another process that shares the ring; in the tree's fixture
tcontextequalsprofile. - The label in the rule is a pattern. A refusal carries
tcontext=with the label of the credentials. io_uring sqpoll label=demo-helper,compiles to the same rule asio_uring sqpoll,(run with the tree's parser).- The personality numbers and the demo-helper credentials are invented for the slide. "Refused" for personality 2 is derived from the match of the target label and was not run.
- Kernel statements are read from the kernel source and were not run.
Read more
for AppArmor developers for security researchers
In the code
- The kernel's name for the permission is
AA_MAY_OVERRIDE_CRED(0x8) (perms.h:51-53).
05 What demo and the log see
operation="uring_sqpoll" and operation="uring_override", class="io_uring"; tcontext= is the label for label=.
The setup call fails with EACCES. A refused request doesn't fail a call: it completes with -EACCES as its result. In the log they have different operation names: uring_sqpoll for the polling thread, uring_override for the credentials. Denied gives you the permission word for the rule. And the override record has one more field, tcontext: that's the label of the credentials demo tried to use, and it's exactly what goes after label=.
Details and sources
Details
- Both records on the slide are assembled from fixtures, with demo's values, which are illustrative: testcase_io_uring_01.in (
operation="uring_sqpoll" class="io_uring" ... requested="sqpoll" denied="sqpoll") and testcase_io_uring_02.in (operation="uring_override" ... requested="override_creds" denied="override_creds" tcontext=...). requested=anddenied=aresqpolloroverride_creds;tcontext=is printed when there is a target label (lsm.c:598-625). The error isEACCES(lib.c:440):io_uring_setupreturns it (sqpoll.c:505-507); foroverride_credsit is theresof the request's completion entry, andio_uring_enteritself succeeds (io_uring.c:1989-1993, io_uring.c:2000-2026).- A plain
denyrefuses without a record; in complain mode the record isALLOWED. - Kernel statements are read from the kernel source and were not run.
06 One state for sqpoll, a label walk for override_creds for AppArmor developers for security researchers
io_uring.cc:116-164 writes \x16 with the permissions, a marker, and \x16 + label for override_creds; lsm.c:627-654 reads them.
Like userns, this class keeps permissions on the state right after the class byte, twenty-two. So each rule writes its permissions there and a marker at the same priority, and the generic marker goes to the bottom priority. When override_creds is among the permissions, a second rule continues from that state through the label, or through any label if none was given. In the kernel, the sqpoll check reads the class state. The override check walks the label of the new credentials from there.
Details and sources
for AppArmor developers for security researchers
Details
- Dumps from the tree's parser (
-D rule-exprs):io_uring sqpoll,gives\x16with 0x10 and\x16with 0x4;io_uring override_creds label=demo-helper,gives\x160x8,\x160x4 and\x16demo-helper0x8; the line on the slide gives\x160x18,\x160x4 and\x16demo-helper0x18;io_uring,gives\x160x18,\x160x4 and\x16[^\000]*0x18. The generic marker is\d22at priority -1001. - The rule: io_uring.cc:53-70, io_uring.cc:116-164. Class
AA_CLASS_IO_URINGis 22 (policydb.h:46). The generic marker is added for confined profiles only (parser_regex.c:1450-1452). - Kernel:
profile_uring(lsm.c:627-654). - Known discrepancy, on the bug list as "
io_uringaccepts a conditional group with any name": the grammar accepts one conditional group of any name after the conditionals and treats its contents as plain conditionals:io_uring override_creds peer=(label=foo),andio_uring override_creds xattrs=(label=foo),meanlabel=foo(run with the tree's parser). - Kernel statements are read from the kernel source and were not run.
for AppArmor developers for security researchers
Read more
- User namespace rules for the marker scheme, rule classes in the parser, compiled permissions.
07 An unknown word inside the parentheses for AppArmor developers for security researchers
io_uring (sqpol), compiles exactly like io_uring, (parser_yacc.y:1597-1608, io_uring.cc:56-64). Checked with the tree's parser.
One for reviewers. Misspell a permission without parentheses and the parser stops you. Put the same misspelling in parentheses and it's skipped without a word. That's harmless when a correct word is next to it. But if the misspelt word is the only one, the list is empty, and for this rule an empty permission set means all of them. So a line that was meant to allow only the polling thread allows overriding credentials with any label as well. When you audit a profile, compare the words in io_uring parentheses letter by letter.
Details and sources
for AppArmor developers for security researchers
Details
- Run with the tree's parser (
-D rule-exprs):io_uring (sqpol),gives\x160x18,\x160x4 and\x16[^\000]*0x18, the same three rules asio_uring,;io_uring (sqpoll, bogus),gives\x160x10 and\x160x4;io_uring sqpol,givessyntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE. - The grammar action for a word in the list returns 0 for an unknown word instead of failing (parser_yacc.y:1597-1608), and the constructor treats 0 as "default to all" (io_uring.cc:56-64).
- The other classes with lists fail on an unknown word; compare
mqueue (create, bogus) /q,, which givesInternal: unexpected mqueue perms character 'b' in input. - Known discrepancy, on the bug list as "An unknown permission inside
io_uring ( ... )is ignored, and a list of unknown words means all permissions". Nothing here was run on a kernel.
for AppArmor developers for security researchers
Attack surface
- The effect is a silent widening from one permission to both, including
override_credsfor any label. - With
deny, a misspelt single word denies both, which is wider than written; with a correct word beside it, the misspelt one is silently not denied. - Reproduce with
apparmor_parser -Q -K --skip-kernel-load -D rule-exprs. It is on the bug list as confirmed; see Known bugs.
for AppArmor developers for security researchers
Read more
08 Mistakes and their messages
Words: sqpoll, override_creds. Conditional: label= with one value.
The permissions are sqpoll and override_creds, and any other word outside parentheses is a syntax error. The conditional is label, not peer. It takes one value. Owner isn't allowed. Two permissions need parentheses. And take care with spelling inside them, because there the parser doesn't complain.
Details and sources
Details
- The parser prints an error as
AppArmor parser error for FILE in profile FILE at line N: MESSAGE; the slide shows MESSAGE. All five rows were run with the tree's parser. In row 1 the unexpected token isTOK_READbecausereadis a keyword; an unknown word such assqpolgivesunexpected TOK_ID. - When the feature set lacks
io_uring, the rule is dropped;--warn=rule-not-enforcedprintsio_uring rules not enforced. - A variable in the label fails when the policy is compiled; see the details of "Two permissions and a label".
- A failing example in the tree: bad_io_uring_01.sd.
for AppArmor developers for security researchers
In the code
- The conditional checks: io_uring.cc:35-50. The message
perms contains invalid permissions for io_uring: io_uring.cc:58. Theownerrefusal: io_uring.h:46-52.
09 Next to io_uring
io_uring rules cover sqpoll and override_creds only.
That's the io_uring rule: the polling thread, and other people's credentials. Labels have their own deck in the kernel district. The userns rule works the same way when it comes to defaults. And the deck on what isn't mediated puts the rest of io_uring in context.
Details and sources
Details
[QUALIFIERS] io_uring [PERMISSIONS] [label=LABEL],: the permissions aresqpollandoverride_creds; without a list the rule has both.- A refused setup returns
EACCES; a refused request completes with-EACCES. Both are logged, asoperation="uring_sqpoll"oroperation="uring_override". - Commits read for this deck: AppArmor 836052d21 (6.0.0~alpha2) and the kernel tree named on the page. The kernel behaviour was read from the source, not observed on a running kernel.
Read more
Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the line (-Q -K --skip-kernel-load --warn=all, -D rule-exprs for compiled forms), with nothing loaded into a kernel; "code" means the parser source or the kernel source was read, not run. Nothing here was observed on a running kernel.
Grammar
IO_URING RULE: [QUALIFIERS] io_uring [PERMISSIONS] [label=LABEL] , PERMISSIONS: sqpoll | override_creds | ( sqpoll, override_creds ) QUALIFIERS: [priority=N] [audit] [allow|deny|prompt]
- Without permissions the rule has both (tree).
labeltakes=, one value, once; blanks around=are allowed (tree). It applies tooverride_credsonly.
| Seat | On an io_uring rule |
|---|---|
priority= | taken |
audit | taken |
allow, deny, prompt | taken: deny is not logged; prompt is in syn-prompt |
owner, other | refused: owner prefix not allowed on io_uring rules (tree) |
Permissions
| Word | The io_uring feature | Kernel hook | Operation in the log |
|---|---|---|---|
sqpoll | a ring with a kernel thread that polls the submission queue (IORING_SETUP_SQPOLL) | uring_sqpoll | uring_sqpoll |
override_creds | a request that runs with credentials registered with the ring (a personality) | uring_override_creds | uring_override |
Hooks: linux:security/apparmor/lsm.c:663-704 (code).
What the class does not cover
| Operation | Seen by AppArmor through this class |
|---|---|
creating a ring (io_uring_setup without IORING_SETUP_SQPOLL) | no |
submitting requests (io_uring_enter) | no |
passthrough commands (LSM hook uring_cmd) | no: no AppArmor implementation |
the LSM hook uring_allowed | no: no AppArmor implementation |
Read from linux:security/apparmor/lsm.c:1785-1890 (code).
Feature set and default
| The feature set | No io_uring rule | With a rule |
|---|---|---|
lists io_uring (abi/5.0, abi/5.0-interface) | both features refused | as the rule says |
does not list it (abi/3.0, abi/4.0, abi/4.0-ip, the kernel-5.4 files, no abi rule (the parser's built-in default)) | both allowed | the rule is dropped, also a deny; both allowed |
The warning for a dropped rule is io_uring rules not enforced, class rule-not-enforced, off by default (tree). The feature file is /sys/kernel/security/apparmor/features/io_uring/mask, which reads sqpoll override_creds (code).
The log records
| Field | Meaning |
|---|---|
operation= | uring_sqpoll or uring_override |
class="io_uring" | always |
requested=, denied= | sqpoll or override_creds |
tcontext= | the label of the credentials, for uring_override |
Records from the tree (libraries/libapparmor/testsuite/test_multi/testcase_io_uring_01.in and testcase_io_uring_02.in):
apparmor="DENIED" operation="uring_sqpoll" class="io_uring" profile="/root/apparmor/tests/regression/apparmor/io_uring" pid=1320 comm="io_uring" requested="sqpoll" denied="sqpoll" apparmor="DENIED" operation="uring_override" class="io_uring" profile="/root/apparmor/tests/regression/apparmor/io_uring" pid=1193 comm="io_uring" requested="override_creds" denied="override_creds" tcontext="/root/apparmor/tests/regression/apparmor/io_uring"
A refused setup returns EACCES; a refused request completes with -EACCES (linux:io_uring/sqpoll.c:505-507, linux:io_uring/io_uring.c:1989-1993, code).
Errors and warnings
| Rule | Message |
|---|---|
io_uring read, | syntax error, unexpected TOK_READ, expecting TOK_END_OF_RULE |
io_uring sqpol, | syntax error, unexpected TOK_ID, expecting TOK_END_OF_RULE |
io_uring sqpoll override_creds, | syntax error, unexpected TOK_OVERRIDE_CREDS, expecting TOK_END_OF_RULE |
io_uring override_creds peer=demo-helper, | invalid io_uring conditional "peer" |
io_uring sqpoll label=(a b), | io_uring conditional "label" only supports a single value |
label given twice | io_uring conditional "label" can only be specified once |
an operator other than = | only "=" allowed in conditions of io_uring rules |
owner io_uring, | owner prefix not allowed on io_uring rules |
io_uring override_creds label=@{profile_name}, | Unable to parse input line '@{profile_name}', no line number |
io_uring (sqpol), | none; compiles like io_uring, |
any io_uring rule, no io_uring in the feature set, --warn=rule-not-enforced | warning io_uring rules not enforced |
Rows with a rule are from the tree's parser; the two others are read from the parser source (code).
for AppArmor developers for security researchers
In the parser and the kernel
- Class
AA_CLASS_IO_URING22 (parser/policydb.h:46);sqpoll0x10,override_creds0x8 (parser/io_uring.h:29-33). - A rule writes up to three policydb rules (
parser/io_uring.cc:116-164):\x16with the permissions,\x16with the marker 0x4 at the rule's priority, and, whenoverride_credsis among the permissions,\x16+ label (or[^\000]*) with the permissions. - The generic marker
\d22is added at the minimum priority for confined profiles (parser/parser_regex.c:1450-1452); the scheme is the one of syn-userns. - Kernel:
profile_uring(linux:security/apparmor/lsm.c:627-654) reads the class state forsqpolland callsaa_label_matchon the new credentials' label foroverride_creds. - Grammar:
parser/parser_yacc.y:1597-1627.
for AppArmor developers for security researchers
Known discrepancies
None of these is taught as intended behaviour. All are on the bug list as confirmed; see Known bugs.
- An unknown word inside the parentheses is ignored; a list of only unknown words compiles as both permissions:
io_uring (sqpol),equalsio_uring,(tree). - The label does not take variables:
io_uring override_creds label=@{profile_name},fails at compile time without a line number (tree). - A conditional group of any name is read as plain conditionals:
io_uring override_creds peer=(label=foo),meanslabel=foo(tree). - The scanner state
IOURING_MODEis declared and never entered (code).
Roads from here
START HERE
- The profile language at a glance — every kind of line on one page
PREAMBLE AND REUSE
- The abi rule and the abi files — the feature set that turns the class on
QUALIFIERS
- allow and deny — deny and audit on io_uring rules
RULE CLASSES
- Rule conditionals — label= and the three spellings of a label
- User namespace rules — the other class with a default deny of this kind
- Capability rules — the privilege checks the kernel makes on its own
- The all rule — the rule that includes io_uring
SECURITY · threat model and limits
- What is not mediated — what of io_uring no rule covers
RUNNING THE PARSER
- Reading a denial — reading the uring records
IN THE KERNEL
- Labels in the kernel — what a label on credentials is