parser: add a man page for xattrs

Signed-off-by: Eric Chiang <ericchiang@google.com>

parser/Makefile

@@ -30,7 +30,7 @@ SYSTEMD_UNIT_DIR=${DESTDIR}/usr/lib/systemd/system
 CONFDIR=/etc/apparmor
 INSTALL_CONFDIR=${DESTDIR}${CONFDIR}
 LOCALEDIR=/usr/share/locale
-MANPAGES=apparmor.d.5 apparmor.7 apparmor_parser.8 aa-teardown.8
+MANPAGES=apparmor.d.5 apparmor.7 apparmor_parser.8 aa-teardown.8 apparmor_xattrs.7
 
 YACC	:= bison
 YFLAGS	:= -d

parser/apparmor.d.pod

@@ -66,7 +66,7 @@ B<COMMENT> = '#' I<TEXT> [ '\r' ] '\n'
 
 B<TEXT> = any characters
 
-B<PROFILE> = ( I<PROFILE HEAD> ) [ I<ATTACHMENT SPECIFICATION> ] [ I<PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
+B<PROFILE> = ( I<PROFILE HEAD> ) [ I<ATTACHMENT SPECIFICATION> ] [ I<PROFILE XATTR CONDS> ] [ I<PROFILE FLAG CONDS> ] '{' ( I<RULES> )* '}'
 
 B<PROFILE HEAD> = [ 'profile' ] I<FILEGLOB> | 'profile' I<PROFILE NAME>
 
@@ -78,6 +78,12 @@ B<UNQUOTED PROFILE NAME> = (must start with alphanumeric character (after variab
 
 B<ATTACHMENT SPECIFICATION> = I<FILEGLOB>
 
+B<PROFILE XATTR CONDS> =  [ 'xattrs=' ] '(' comma or white space separated list of I<PROFILE XATTR> ')'
+
+B<PROFILE XATTR> = extended attribute name '=' I<XATTR VALUE FILEGLOB>
+
+B<XATTR VALUE FILEGLOB> = I<FILEGLOB>
+
 B<PROFILE FLAG CONDS> =  [ 'flags=' ] '(' comma or white space separated list of I<PROFILE FLAGS> ')'
 
 B<PROFILE FLAGS> = 'complain' | 'audit' | 'enforce' | 'mediate_deleted' | 'attach_disconnected' | 'chroot_relative'
@@ -1371,6 +1377,18 @@ Directories anywhere underneath F</tmp>.
 
 =back
 
+=head2 Extended Attributes
+
+AppArmor profiles have the ability to target files based on their xattr(7)
+values in addition to their path. For example, the following profile matches
+files in /usr/bin with the attribute "security.apparmor" and value "trusted":
+
+  /usr/bin/* xattrs(security.apparmor="trusted") {
+    # ...
+  }
+
+See apparmor_xattrs(7) for further details.
+
 =head2 Rule Qualifiers
 
 There are several rule qualifiers that can be applied to permission rules.
@@ -1609,7 +1627,7 @@ negative values match when specifying one or the other. Eg, 'rw' matches when
 
 =head1 SEE ALSO
 
-apparmor(7), apparmor_parser(8), aa-complain(1),
+apparmor(7), apparmor_parser(8), apprmor_xattrs(7), aa-complain(1),
 aa-enforce(1), aa_change_hat(2), mod_apparmor(5), and
 L<https://wiki.apparmor.net>.
 

parser/apparmor_xattrs.pod

@@ -0,0 +1,108 @@
+# ----------------------------------------------------------------------
+#    Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
+#                  2008, 2009
+#    NOVELL (All rights reserved)
+#
+#    Copyright (c) 2010
+#    Canonical Ltd. (All rights reserved)
+#
+#    Copyright (c) 2013
+#    Christian Boltz (All rights reserved)
+#
+#    This program is free software; you can redistribute it and/or
+#    modify it under the terms of version 2 of the GNU General Public
+#    License published by the Free Software Foundation.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program; if not, contact Novell, Inc.
+# ----------------------------------------------------------------------
+
+
+=pod
+
+=head1 NAME
+
+AppArmor profile xattr(7) matching
+
+=head1 DESCRIPTION
+
+AppArmor profiles can conditionally match files based on the presence and value
+of extended attributes in addition to file path. The following profile applies
+to any file under "/usr/bin" where the "security.apparmor" extended attribute
+has the value "trusted":
+
+	profile trusted /usr/bin/* xattrs=(security.apparmor="trusted") {
+		# ...
+	}
+
+Note that "security.apparmor" and "trusted" are arbitrary, and profiles can
+match based on the value of any attribute.
+
+The xattrs value may also contain a path regex:
+
+	profile trusted /usr/bin/* xattrs=(user.trust="tier/*") {
+
+		# ...
+	}
+
+The getfattr(1) and setfattr(1) tools can be used to view and manage xattr
+values:
+
+	$ setfattr -n 'security.apparmor' -v 'trusted' /usr/bin/example-tool
+	$ getfattr --absolute-names -d -m - /usr/bin/example-tool
+	# file: usr/bin/example-tool
+	security.apparmor="trusted"
+
+The priority of each profile is determined by the length of the path, then the
+number of xattrs specified. A more specific path is preferred over xattr
+matches:
+
+	# Highest priority, longest path.
+	profile example1 /usr/bin/example-tool {
+		# ...
+	}
+
+	# Lower priority than the longer path, but higher priority than a rule
+	# with fewer xattr matches.
+	profile example2 /usr/** xattrs=(
+		security.apparmor="trusted"
+		user.domain="**"
+	) {
+		# ...
+	}
+
+	# Lowest priority. Same path length as the second profile, but has 
+	# fewer xattr matches.
+	profile example2 /usr/** {
+		# ...
+	}
+
+xattr matching requires the following kernel feature:
+
+	/sys/kernel/security/apparmor/features/domain/attach_conditions/xattr
+
+=head1 KNOWN ISSUES
+
+AppArmor profiles currently can't reliably match extended attributes with
+binary values such as security.evm and security.ima. In the future AppArmor may
+gain the ability to match based on the presence of certain attributes while
+ignoring their values.
+
+=head1 SEE ALSO
+
+apparmor(8),
+apparmor_parser(8),
+apparmor.d(5),
+xattr(7),
+aa-autodep(1), clean(1),
+auditd(8),
+getfattr(1),
+setfattr(1),
+and L<https://wiki.apparmor.net>.
+
+=cut