Quoting and escaping

quotes and escapes for application developers for security researchers

How to write a name or path that contains a space or a comma or a quote or a byte you cannot type. Double quotes and backslash escapes and the two stages in which the parser decodes them. Quotes do not switch off patterns.

On the map: profile structure

▶ Watch this deck — 8 scenes, ~6 min

Worth seeing first

01 A path with a space in it

QUOTING directory /srv/demo/My Files/ a.txt b.txt a space in the name /srv/demo/My Files/** r, syntax error, unexpected TOK_ID, expecting TOK_MODE nothing about a space path permissions? "/srv/demo/My Files/**" r, one word again
A directory named My Files; the rule written without quotes is cut into words at the space and rejected with a syntax error; the same rule with the path in double quotes is one word.

A space ends a word. /srv/demo/My Files/** r, fails with "syntax error, unexpected TOK_ID, expecting TOK_MODE". Quoted, "/srv/demo/My Files/**" r, is one path. Both were run through the tree's parser.

Demo serves files from a directory called My Files, with a space in the name. You write the rule the obvious way, and the parser rejects it with a syntax error about an unexpected token. It doesn't say space anywhere. Here's what happened. A rule is a row of words separated by white space. The parser took everything up to the space as the path, then expected permissions, and found the word Files instead. To keep the path together, you have to tell the parser that the space belongs to it. Put the path in double quotes and it's one word again. This deck is about that, and about the other characters that need help.

Details and sources

Details

  • /srv/demo/My Files/** r, fails with syntax error, unexpected TOK_ID, expecting TOK_MODE; "/srv/demo/My Files/**" r, is accepted. Both run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel).
  • In the message TOK_ID is a word (here Files/**) and TOK_MODE is a permission string such as r.
  • The parser's own tests have the same pair: bad_embedded_spaces_1.sd (/abc def r,, expected FAIL) and ok_embedded_spaces_2.sd ("/abc def" r,, expected PASS).
  • apparmor.d(5) mentions it only inside the grammar: "Rules with embedded spaces or tabs must be quoted" (apparmor.d.pod:403).
  • Quoting is the parser's business. The kernel receives the compiled pattern, in which the blank is an ordinary byte.
  • The directory My Files and the profile are invented for the map.

Read more

for AppArmor developers for security researchers

In the code

02 A word is bare or quoted

GRAMMAR WORD bare word no blank, tab, new line, " or ! a final , ends it " any characters " \" for a quote inside ESCAPE \" \\ \t \n \r \a \e \f \NNN octal \xHH hex \dDDD decimal in both branches PATTERN \* \? \[ \] \{ \} \, kept for the pattern stage: this character, literally profile "demo service" /usr/bin/demo { ^"night shift" { } "/srv/demo/My Files/**" r, as a path in a rule, a quoted string must begin with / @ : or &
Syntax diagram: a word is either a bare word, which cannot contain a blank, tab, new line, double quote or exclamation mark, or a double-quoted string of any characters; a strip of byte escapes valid in both forms; a strip of pattern escapes; and a profile fragment with a quoted profile name, a quoted hat name and a quoted path.

A word is bare or "quoted". Quotes admit blanks, tabs, new lines, ! and ,. Escapes work in both: \", \\, \t, \n, \r, \a, \e, \f, \NNN (octal), \xHH (hex), \dDDD (decimal). The pattern escapes such as \* are a second group, in the scenes that follow. As a path in a rule a quoted string must begin with /, @, : or &.

Everywhere in the language, where a name, a path or a value goes, you can write a bare word or a string in double quotes. A bare word can't contain a blank, a tab, a new line, a double quote or an exclamation mark, and a comma with nothing after it ends the word. Inside quotes all of those are fine, and a quote itself is written \". Backslash escapes work in both forms: \t for a tab, backslash and three octal digits for any byte, backslash x and two hex digits. Profile and hat names can be quoted too.

Details and sources

Details

  • A bare word cannot contain a blank, a tab, a carriage return, a new line, " or !; a comma belongs to it only when a word character follows.
  • A quoted word is ", any bytes except NUL and ", and ". A quote inside is written \".
  • Escapes decoded in every word, bare or quoted: \\, \", \a, \e (ESC, octal 033), \f, \n, \r, \t, \NNN (one to three octal digits), \xHH (one or two hex digits), \dDDD (one to three decimal digits). The numeric forms stop at the value 255: \378 is \37 followed by 8 (lib.c:158-219).
  • Quotes are not part of the name: profile "demo" { } and profile demo { } define the same profile.
  • profile "demo service" /usr/bin/demo { ^"night shift" { } } gives the names demo service and demo service//night shift (apparmor_parser -N, parser built from the AppArmor tree at 836052d21).
  • At the start of a rule a quoted string must begin with /, @, : or &.
  • Quoted strings are also accepted for include file names, values after =, list values such as flags, variable values and change_profile operands.
  • Fixtures: ok_quoted_1.sd ("/bin/alpha\tbeta" rix,) and ok_octal_1.sd (/bin/\141bcde rix,).

Read more

for AppArmor developers for security researchers

In the code

03 Quotes, or a backslash before the space

SPACES "/srv/demo/My Files/**" r, /srv/demo/My\ Files/** r, /srv/demo/My Files/** the same path pattern $ apparmor_parser --warn=format ... the backslash spelling only Character was quotedunnecessarily, dropped preceding quote ('\') character /srv/demo/end\ r, the backslash swallows the space before r syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE prefer quotes
Two spellings of the same rule, one with the path in quotes and one with a backslash before the space, both lead to the same path pattern; the backslash spelling earns a format warning, and a backslash before the space that precedes the permissions gives a syntax error.

"/srv/demo/My Files/**" and /srv/demo/My\ Files/** are the same path. The backslash form draws the --warn=format warning "Character was quotedunnecessarily, dropped preceding quote ('\') character"; the character it names is the blank. Run with the tree's parser.

There are two ways to keep that space. Quotes around the whole path, or a backslash right before the space. Both give the same path pattern: the parser's rule dump prints the same expression for the two spellings. But they aren't equally good. Ask the parser for format warnings and the backslash version earns one: character was quoted unnecessarily, with the two words run together exactly like that. And the backslash has a sharp edge. If the space you escape is the one before the permissions, the permissions become part of the path, and you get a syntax error. So use quotes. They're also easier to read.

Details and sources

Details

  • "/srv/demo/My Files/**" r, and /srv/demo/My\ Files/** r, compile to the same expression, /srv/demo/My Files/[^/\x00][^\x00]*. Printed by the parser built from the AppArmor tree at 836052d21 with -D rule-exprs (-Q -K --skip-kernel-load, nothing loaded into a kernel).
  • The backslash form draws Warning from FILE (FILE line N): Character was quotedunnecessarily, dropped preceding quote ('\') character. The text has no blank between "quoted" and "unnecessarily", and the character it names is the blank.
  • The warning's class is format, "warn on unnecessary or confusing formatting" (parser_main.c:291). It is off by default; turn it on with --warn=format or --warn=all. The line number it prints is past the end of the profile.
  • A backslash before the blank that precedes the permissions joins them to the path: /srv/demo/end\ r, gives syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE.
  • Fixtures, all expected to pass: ok_embedded_spaces_1.sd ("/abc\ def" r,), ok_embedded_spaces_2.sd ("/abc def" r,), ok_embedded_spaces_4.sd (/abc\ def r,).

Read more

for AppArmor developers for security researchers

In the code

  • The escaped blank is part of a bare word by the scanner's ID definition (parser_lex.l:266).
  • The backslash is dropped, with pwarn(WARN_FORMAT, ...), in the default branch of convert_aaregex_to_pcre (parser_regex.c:382-401).

04 Quotes do not switch off patterns

QUOTES AND PATTERNS report1.txt report*.txt "/srv/demo/report*.txt" r, still a glob /srv/demo/report\*.txt r, a literal star \* \? \[ \] \{ \} \, \\ backslash = this character itself "/srv/demo/My Files/report\*.txt" r, both: quotes for the space, backslash for the star this is not a shell: no single quotes, and no quoting that makes text literal
A quoted rule with a star still reaches both report1.txt and a file literally named report star dot txt; the rule with a backslash before the star reaches only the file with the star in its name; a path with a space and a literal star uses quotes and a backslash together.

"/srv/demo/report*.txt" is still a glob. \*, \?, \[, \], \{, \}, \, and \\ stand for the characters themselves, inside or outside quotes. The matches drawn follow from the expressions the tree's parser printed; they were not run against a kernel.

If you come from the shell, here's a habit to drop. In a shell, quotes switch off wildcards. Here they don't. A star inside double quotes is still a star: the parser compiles the quoted rule into a pattern that fits report one, report two and everything else. Quotes only keep a word together. To mean the character itself, a file that really has a star in its name, put a backslash in front of it. That works for all the pattern characters: star, question mark, square brackets, curly braces, and a comma inside braces. When a path has both a space and a literal star, use both tools: quotes around it, and a backslash before the star.

Details and sources

Details

  • "/srv/demo/q*" is converted to /srv/demo/q[^/\x00]*: still a glob. /srv/demo/report\*.txt is converted to /srv/demo/report\*\.txt: a literal star. Both printed by the parser built from the AppArmor tree at 836052d21 with -D rule-exprs.
  • Literal forms, inside or outside quotes: \*, \?, \[, \], \{, \}, \, and \\.
  • \, matters inside { } and character classes: /srv/demo/c\,d is converted to /srv/demo/c,d.
  • ., +, (, ) and the vertical bar are always literal, escaped or not. ^ and $ are literal outside a character class.
  • Known discrepancy: [\^a] loses its escape and becomes the negated class [^a]; /k[\^a] r, and /k[^a] r, compile to identical output (run with the released parser 5.0.2). Put ^ anywhere but first in the class.
  • What a pattern matches is derived from the printed expression. Nothing on this slide was run against a kernel.

for AppArmor developers for security researchers

In the code

05 Decoded in two stages

TWO STAGES "/srv/demo/My Files/\x41\*.txt" every word: quotes off, bytes decoded " " removed \x41 becomes A \* kept /srv/demo/My Files/A\*.txt paths only: pattern conversion \* a literal star . a literal dot matches exactly /srv/demo/My Files/A*.txt $ apparmor_parser -Q -D rule-exprs demo aare: /srv/demo/My Files/A\*.txt -> /srv/demo/My Files/A\*\.txt prints the text between the stages, and what stage two made of it
One quoted path passes through two stations: the first, applied to every word, removes the quotes and decodes backslash x 41 to A while keeping backslash star; the second, applied to paths only, turns backslash star into a literal star; the result matches exactly one file name, and the parser's rule expression dump prints the text between the stages.

Stage 1 (every word): remove quotes, decode \t, \NNN, \xHH, \dDDD and the like to bytes. Stage 2 (patterns): \*, \?, \[, \{, \,, \\ become literal characters. apparmor_parser -D rule-exprs shows the text between the stages; the line drawn is what the tree's parser printed.

Why are there two groups of escapes? Because the parser decodes in two stages. Take a path with a bit of everything: quotes, a space, \x41, and \*. Stage one happens to every word in the file. The quotes come off, and escapes that stand for a single byte are decoded: \x41 becomes a capital A. Backslash star is left alone, on purpose. Stage two happens only where a pattern is expected. It reads the remaining backslashes: \* means a real star. The result matches one file name exactly. You can watch the middle step yourself: the parser's rule expression dump prints each path as it leaves stage one.

Details and sources

Details

  • apparmor_parser -D rule-exprs ("Dump rule to expr tree conversions", common_optarg.c:31) prints each path as aare: BEFORE -> AFTER. BEFORE is the text after stage one, AFTER the regular expression that stage two produced.
  • The slide's example, printed by the parser built from the AppArmor tree at 836052d21: "/srv/demo/My Files/\x41\*.txt" gives /srv/demo/My Files/A\*.txt -> /srv/demo/My Files/A\*\.txt.
  • Stage one (every word): quotes removed; \a \e \f \n \r \t, \NNN, \xHH, \dDDD, \" decoded to one byte.
  • Stage one leaves alone: a decoded value of 0 (\000, \x00, \d0), whose escape text is kept; a decoded value that is one of * ? [ ] { } ^ , or a backslash, which is stored with a backslash in front (\d123 becomes \{, run with the released parser 5.0.2); and a backslash before anything else.
  • Stage two (patterns only): \*, \?, \[, \], \{, \}, \,, \\ become literal characters; \000 and \x00 become a zero byte.
  • More conversions: /srv/demo/\141bc gives /srv/demo/abc; /srv/demo/e\x41\d066\103 gives /srv/demo/eABC.

for AppArmor developers for security researchers

In the code

06 processunquoted and convert_aaregex_to_pcre for AppArmor developers for security researchers

PARSER stage one parser_misc.c:468-535 processid() -> processquoted() strips " and " -> processunquoted() strn_escseq() lib.c:158-219 value 0 -> copy the escape text value in *?[]{}^,\ -> store \ + char other value -> store the byte not a sequence -> copy \ and char stage two parser_regex.c:118-445 convert_aaregex_to_pcre() \ sets bEscape (152-167) \* \[ \] \{ \} -> escaped in output \? -> ? \, -> , other: str_escseq() (382-401) valid -> copied for the regex parser invalid -> drop \, pwarn(WARN_FORMAT) trailing \ -> error (418-422) libapparmor_re/parse.y:182 decodes \x0 with the same str_escseq . + | ( ) always emitted escaped; ^ $ literal outside classes (358-380)
Two boxes: on the left processid, processquoted and processunquoted with the four outcomes of strn_escseq; on the right convert_aaregex_to_pcre with its bEscape flag, the pattern characters it emits escaped, and what happens to other escaped characters; below, the regex scanner in libapparmor_re that decodes what was passed on.

Stage 1: processid() → processquoted() → processunquoted() using strn_escseq(). Stage 2: convert_aaregex_to_pcre() with bEscape; leftovers go through str_escseq() and reach the regex scanner in libapparmor_re/parse.y.

The two stages by name. Stage one is processid, which strips the quotes and calls processunquoted. That loops over the text with strn_escseq. A decoded value of zero isn't stored; the escape text is copied instead, so that no zero byte cuts the C string short. A decoded value that is a pattern character gets a backslash put back in front. Anything else is stored as the byte. Stage two is convert_aaregex_to_pcre. A backslash sets the escape flag for the next character. Pattern characters come out escaped. Anything else is tried as an escape sequence, and either passed on to the regex parser, or dropped with a format warning. Dots, pluses, bars and parentheses always come out escaped.

Details and sources

for AppArmor developers for security researchers

Details

  • char *processid(const char *string, int len) calls processquoted when the text starts with ", else processunquoted; processquoted strips the quotes and calls processunquoted(string + 1, len) (parser_misc.c:506-535).
  • char *processunquoted(const char *string, int len) (parser_misc.c:468-503): for each backslash it calls strn_escseq(&pos, "", len). A result of 0 copies the escape text; a result in "*?[]{}^,\\" is stored as backslash plus the character; any other result is stored as the byte; -1 copies the backslash unchanged.
  • int strn_escseq(const char **pos, const char *chrs, size_t n) (lib.c:158-219): octal by strntol(*pos, &end, 8, 255, min(3, n)), \d decimal with at most 3 digits, \x hex with at most 2, then the letters a e f n r t; returns -1 for anything else.
  • pattern_t convert_aaregex_to_pcre(const char *aare, int anchor, int glob, std::string& pcre, int *first_re_pos) (parser_regex.c:118-445). A backslash sets bEscape (parser_regex.c:152-167).
  • Default branch: with bEscape, str_escseq(&pos, "") is tried; a valid escape is passed on with its backslash, anything else gets pwarn(WARN_FORMAT, "Character %c was quotedunnecessarily, dropped preceding quote ('\\') character\n", ...) (parser_regex.c:382-401).
  • ., +, |, (, ) always get a backslash; ^ and $ outside a character class too (parser_regex.c:356-380).
  • A pattern that ends in a backslash: Regex error: trailing '\' escape character (parser_regex.c:418-422; read, not run).
  • The regex scanner decodes passed-on escapes with str_escseq(pos, "*+.|^$-[](){}") (parse.y:182).
  • escape_re() puts a backslash before {}[]*? when @{profile_name} is expanded (parser_variable.c:87-103).
  • Unit tests: test_processunquoted, test_processquoted (parser_misc.c:1387-1460).

Read more

07 When quoting goes wrong

COMMON MISTAKES "My Files/**" r, Lexer found unexpected character: '"' (0x22) in state: INITIAL a quoted path must start with / /srv/demo/wow!.txt r, Lexer found unexpected character: '!' (0x21) in state: INITIAL write \! or use quotes 2 3 4 "/srv/demo/My Files/** r, /etc/demo/** r, "/var/lib/demo/x y" rw, one string: from the first quote to the next quote in the file line 2: syntax error, unexpected TOK_ID, expecting TOK_MODE the error is real; the place and the line number are not where the quote is missing /srv/demo/x\q r, accepted; with --warn=format: Character q was quotedunnecessarily, dropped preceding quote ('\') character
Four quoting mistakes with the parser's answer: a quoted path that does not begin with a slash, a bare exclamation mark, a missing closing quote that makes the string run on to a quote two lines later with a syntax error naming the wrong line, and a backslash before an ordinary letter that draws a format warning.

A quoted path in a rule must begin with /, @, : or &. ! needs a backslash or quotes. A missing closing quote extends the string to the next " in the file; the resulting error and its line number point elsewhere. The uncounted new lines are a known discrepancy, not intended behaviour.

Quoting errors rarely name the real problem. A quoted path that doesn't start with a slash is rejected at the quote character. An exclamation mark in a bare word is rejected too. The nasty one is a missing closing quote. The string runs on, across your next rules, until the next quote character in the file, and the syntax error you get describes whatever came after that. New lines inside a quoted string aren't counted either, so the line number can be too low. When an error makes no sense, look upward for an unbalanced quote. And a backslash before an ordinary letter is just dropped, with a format warning if you ask.

Details and sources

Details

Run with the parser built from the AppArmor tree at 836052d21 (-Q -K --skip-kernel-load --warn=all, nothing loaded into a kernel):

  • A quoted path that does not start with /, @, : or &: Lexer found unexpected character: '"' (0x22) in state: INITIAL.
  • A bare !: Lexer found unexpected character: '!' (0x21) in state: INITIAL. Write \! or quote the word.
  • A missing closing quote: the string runs to the next " in the file, and the usual result is syntax error, unexpected TOK_ID, expecting TOK_MODE. With no later quote at all the unexpected character message above is reported at the line of the opening quote.
  • Known discrepancy: new lines inside a quoted string are not counted, so later messages report a line number that is too low. An error on line 4 was reported as line 3.
  • Known discrepancy: a quoted string that ends in an escaped backslash, "/a\\", is extended to the next " in the file, because the second backslash and the quote are read as the pair \".
  • profile "" { }: Empty named transition profile name: .
  • A backslash before an ordinary character, such as \q or \., is dropped; with --warn=format the parser prints Character C was quotedunnecessarily, dropped preceding quote ('\') character. Fixture: ok_slashquote_1.sd (/bingo/bang\o/bongo rw,).
  • A pattern that ends in a backslash: Regex error: trailing '\' escape character, then Unable to parse input line (read from the source, not run).

for AppArmor developers for security researchers

In the code

08 Around quoting

ROADS a backslash makes these literal * ? [ ] { } syn-globbing quotes hold these in a word space , ! " syn-comments commas and braces as structure where quoted words appear syn-file-rules syn-profile-name syn-variables a zero byte, escaped syn-unix \000 in abstract socket names the two stages, and the whole profile fe-lexer stage one fe-aare stage two syntax-map
Roads: the characters a backslash makes literal lead to syn-globbing; the characters quotes hold in a word lead to syn-comments; quoted words appear in syn-file-rules, syn-profile-name and syn-variables; escaped zero bytes lead to syn-unix; the two decoding stages are fe-lexer and fe-aare; syntax-map shows the whole profile.

Pattern characters: syn-globbing. Structure characters: syn-comments. Zero bytes in socket names: syn-unix. The two stages: fe-lexer, fe-aare.

Two neighbours explain what you were protecting. The pattern characters that a backslash makes literal are the subject of the globbing deck. The structure characters that quotes keep inside a word, the comma above all, are in the comments and line structure deck. Quoted words turn up in file rules, in profile names and in variables, and each has a deck. One special use of escapes: abstract unix socket names contain zero bytes, written \000; the unix rules deck shows that. And the two stages each have a deck in the parser district.

Details and sources

Details

  • Quotes keep a word together; they do not switch off patterns. A backslash makes a pattern character literal.
  • Escapes for single bytes (\t, \NNN, \xHH, \dDDD) are decoded in every word; pattern escapes (\*, \?, \[, \{, \,) only where a pattern is expected.
  • Zero bytes: apparmor.d(5) says of abstract unix socket names "null characters must be specified by using an escape sequence \000 or \x00" (apparmor.d.pod:1583-1585).
  • The fixtures bad_embedded_0_1.sd, _2 and _3 (\000, \x00, \d00 in a file path) are marked as passing despite their names; the parser has no check for a zero byte in a file path.
  • Commit read for this deck: AppArmor 836052d21 (6.0.0~alpha2). Nothing in it was run against a kernel.

Read more

Basis of the statements on this page: "tree" means the parser built from the AppArmor commit above was run on the fragment (-Q -K --skip-kernel-load --warn=all, with -D rule-exprs for conversions) and nothing was loaded into a kernel; "5.0.2" means the released parser 5.0.2 was run; "code" means the parser source was read, not run. What a pattern matches is derived from the expression the parser printed.

Words

WORD:    BARE | QUOTED
BARE:    one or more of: any character except blank, tab, CR, LF, " ! ,
                         , followed by a word character
                         the pairs  \blank  \tab  \"  \!  \,
                         \# (as the first character only)
QUOTED:  '"' { any byte except NUL and "  |  \" } '"'
  • Quotes are not part of the name: profile "demo" { } and profile demo { } define the same profile.
  • At the start of a rule a quoted string must begin with /, @, : or &.
  • Quoted strings are accepted for include file names, names after profile, hat, ^ and ->, values after =, identity values, list values such as flags, variable values, change_profile operands, ids in keyword rules and if expressions. A quoted value in a conditional list needs at least one character.
  • profile "demo service" /usr/bin/demo { ^"night shift" { } } gives the names demo service and demo service//night shift (tree, -N).
  • Quotes do not switch off patterns: "/srv/demo/q*" is a glob (tree).
  • A quoted string may contain raw new lines; see Known discrepancies for the effect on line numbers.

Escapes decoded in every word

Decoded in quoted and bare words alike, in paths, profile names, flag values, variable values and conditional values (code).

EscapeResult
\\a backslash, kept escaped for the pattern stage
\""
\aBEL
\eESC (octal 033)
\fform feed
\nnew line
\rcarriage return
\ttab
\NNNone to three octal digits, value at most 255; \378 is \37 followed by 8
\xHHone or two hex digits
\dDDDone to three decimal digits, value at most 255; not a digit class
  • A decoded value of 0 (\0, \000, \x00, \d0) is not stored as a byte: the escape text is kept for the pattern stage.
  • A decoded value that is one of * ? [ ] { } ^ , or a backslash is stored with a backslash in front, so the pattern stage reads it as literal: \d123 becomes \{ (tree).
  • A backslash followed by anything else is copied unchanged and left to the pattern stage.

Escapes interpreted in patterns

WrittenMeaning
\* \? \[ \] \{ \}the character itself
\,a literal comma; matters inside { } and character classes
\\a literal backslash
. + ( ) and the vertical baralways literal, escaped or not
^ $literal outside a character class, escaped or not
\000 \x00 \d0a zero byte
any other escaped character, such as \q, \!, \. or backslash blankthe backslash is dropped, with the format warning below

Pattern characters themselves: syn-globbing.

Worked conversions

Printed by the tree's parser with -D rule-exprs as aare: BEFORE -> AFTER.

WrittenBefore conversionAfter conversion
"/srv/demo/My Files/**"/srv/demo/My Files/**/srv/demo/My Files/[^/\x00][^\x00]*
/srv/demo/My\ Docs/**/srv/demo/My\ Docs/**/srv/demo/My Docs/[^/\x00][^\x00]*, with the format warning
"/srv/demo/q*"/srv/demo/q*/srv/demo/q[^/\x00]*
/srv/demo/report\*.txt/srv/demo/report\*.txt/srv/demo/report\*\.txt
"/srv/demo/My Files/\x41\*.txt"/srv/demo/My Files/A\*.txt/srv/demo/My Files/A\*\.txt
/srv/demo/\141bc/srv/demo/abc/srv/demo/abc
/srv/demo/e\x41\d066\103/srv/demo/eABC/srv/demo/eABC
"/srv/demo/a\tb"/srv/demo/a, a tab byte, bthe same
/srv/demo/nul\000x/srv/demo/nul\000x/srv/demo/nul\x0x (in the rule line)
/srv/demo/c\,d/srv/demo/c\,d/srv/demo/c,d
"/srv/demo/a,b"/srv/demo/a,bthe same
"/srv/demo/trailing,"/srv/demo/trailing,the same
/srv/demo/it\"s/srv/demo/it"sthe same

Spaces

  • "/srv/demo/My Files/**" r, and /srv/demo/My\ Files/** r, are the same rule (tree). The second draws the format warning.
  • A backslash before the blank that precedes the permissions joins them to the path: /srv/demo/end\ r, is a syntax error (tree).
  • In identities a blank is allowed only in a value that starts with /: syn-identities.
  • The man page mentions quoting only in passing ("Rules with embedded spaces or tabs must be quoted", parser/apparmor.d.pod:139, 403); the backslash spelling and the escape list are not in its grammar.

Errors and warnings

MessageCause
syntax error, unexpected TOK_ID, expecting TOK_MODEan unquoted space in a path; also the usual result of a missing closing quote (tree)
Lexer found unexpected character: '"' (0x22) in state: INITIALa quoted path that does not start with /, @, : or &; or an opening quote with no later quote in the file, reported at the line of the opening quote (tree)
Lexer found unexpected character: '!' (0x21) in state: INITIALa bare !; write \! or quote the word (tree)
syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODEa backslash before the blank that precedes the permissions (tree)
Empty named transition profile name: profile "" { } (tree)
Regex error: trailing '\' escape character, then Unable to parse input linea pattern that ends in a backslash (code; not run)
Warning: Character C was quotedunnecessarily, dropped preceding quote ('\') charactera backslash before a character that needs none; class format, off by default, enabled by --warn=format or --warn=all; printed as Warning from FILE (FILE line N): ... with a line number past the end of the profile (tree)
  • The warning text has no blank between "quoted" and "unnecessarily". For backslash blank the character C is the blank, so the message reads Character was quotedunnecessarily, ....
  • The warning is also printed for \., although the output is the same with or without the backslash.

Known discrepancies

  • New lines inside a quoted string are not counted. Every message after a multi-line quoted string, or after a missing closing quote that pairs with a later quote, reports a line number that is too low: an error on line 4 was reported as line 3 (tree).
  • A quoted string that ends in an escaped backslash, "/a\\", is extended to the next " in the file, because the scanner reads the second backslash and the quote as the pair \". Two quoted paths, the first ending in \\, fail with syntax error, unexpected TOK_ID, expecting TOK_MODE (tree).
  • A bare \\ before a blank is read as a backslash plus an escaped blank: /a\\ r, fails with syntax error, unexpected TOK_END_OF_RULE, expecting TOK_MODE (tree).
  • [\^a] loses its escape and becomes the negated class [^a], broader than written: /k[\^a] r, and /k[^a] r, compile to identical output (tree). Put ^ anywhere but first in the class.
  • The fixtures parser/tst/simple_tests/file/bad_embedded_0_1.sd, _2 and _3 (\000, \x00, \d00 in a file path) are marked as passing despite their names; the parser has no check for a zero byte in a file path.
  • Zero bytes are useful in abstract socket addresses: syn-unix.

for AppArmor developers for security researchers

Code map

StepWhere
bare word character classes ID_CHARS, ID_FIRST, IDparser/parser_lex.l:262-267
QUOTED_LIST_VALUE_IDparser/parser_lex.l:273-275
ALLOWED_QUOTED_ID, QUOTED_ID; \\ is not treated as a unit, the cause of the two backslash discrepanciesparser/parser_lex.l:287-288
QUOTED_LABEL, the quoted form accepted at the start of a rule, and its actionparser/parser_lex.l:302, 838-841
processid(), processquoted(), processunquoted()parser/parser_misc.c:468-535
strn_escseq()parser/lib.c:158-219
unit tests test_processunquoted, test_processquotedparser/parser_misc.c:1387-1460
convert_aaregex_to_pcre(); bEscape set at 152-167parser/parser_regex.c:118-445
^ $ and the always-escaped charactersparser/parser_regex.c:358-380
other escaped characters: str_escseq(), else pwarn(WARN_FORMAT)parser/parser_regex.c:382-401
trailing backslash errorparser/parser_regex.c:418-422
--warn=formatparser/parser_main.c:291
the regex scanner decodes passed-on escapes with str_escseq()parser/libapparmor_re/parse.y:182
escape_re() adds a backslash before pattern characters when @{profile_name} is expandedparser/parser_variable.c:87-103
  • Fixtures: parser/tst/simple_tests/file/ok_embedded_spaces_*.sd, bad_embedded_spaces_1.sd, ok_quoted_*.sd, ok_octal_*.sd, ok_slashquote_1.sd.
  • The decks for the two stages: fe-lexer, fe-aare.

Roads from here

START HERE

FILE ACCESS

PREAMBLE AND REUSE

PROFILE HEAD

RULE CLASSES

PROFILE STRUCTURE

INSIDE THE PARSER