parser/apparmor.d.pod: more fully document child profiles, including:

- cx and Cx
  - change_profile()

parser/apparmor.d.pod

@@ -55,9 +55,9 @@ B<COMMENT> = '#' I<TEXT>
 
 B<TEXT> = any characters
 
-B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
 
-B<SUBPROFILE> = [ I<COMMENT> ... ] I<PROGRAMHAT> '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
+B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
 
 B<CAPABILITY> = (lowercase capability name without 'CAP_' prefix; see
 capabilities(7))
@@ -74,13 +74,15 @@ B<PROGRAM> = (non-whitespace characters except for '^', must start with '/'. Emb
 
 B<PROGRAMHAT> = '^'  (non-whitespace characters; see change_hat(2) for a description of how this "hat" is used.)
 
+B<PROGRAMCHILD> = I<SUBPROFILE> name
+
 B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
 
 B<RULE QUALIFIER> = [ 'audit' ] [ 'deny' ] [ 'owner' ]
 
 B<FILEGLOB> = (must start with '/' (after variable expansion), B<?*[]{}^> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
 
-B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'm' ) [ I<ACCESS> ... ]  (not all combinations are allowed; see below.)
+B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I<PROGRAMCHILD> | 'Cx -> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ]  (not all combinations are allowed; see below.)
 
 B<VARIABLE> = '@{' I<ALPHA> [ I<ALPHANUMERIC> ... ] '}'
 
@@ -94,14 +96,19 @@ B<ALPHANUMERIC> = ('1', '2', '3', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ...
 
 =back
 
-All resources and programs need a full path. There may be any number
+All resources and programs need a full path. There may be any number of
-of subprofiles ("hats") in a profile, limited only by kernel memory.
+subprofiles (aka child profiles) in a profile, limited only by kernel
-Subprofile names are limited to 974 characters.
+memory. Subprofile names are limited to 974 characters.  Child profiles can
-Not all profiles benefit from subprofiles
+be used to confine an application in a special way, or when you want the
---- applications must either be written or modified to use change_hat(2)
+child to be unconfined on the system, but confined when called from the
-to take advantage of subprofiles. Several change_hat(2)-aware
+parent.  Hats are a special child profile that can be used with the
+change_hat(2) API call.  Applications written or modified to use
+change_hat(2) can take advantage of subprofiles to run under different
+confinements, dependent on program logic. Several change_hat(2)-aware
 applications exist, including an Apache module, mod_apparmor(5); a PAM
-module, pam_apparmor; and a Tomcat valve, tomcat_apparmor.
+module, pam_apparmor; and a Tomcat valve, tomcat_apparmor. Applications
+written or modified to use change_profile(2) transition permanently to the
+specified profile. libvirt is one such application.
 
 =head2 Access Modes
 
@@ -124,6 +131,10 @@ modes:
 
 =item B<Px> 	- discrete profile execute -- scrub the environment
 
+=item B<cx> 	- transition to subprofile on execute
+
+=item B<Cx> 	- transition to subprofile on execute -- scrub the environment
+
 =item B<ix>	- inherit execute
 
 =item B<m>	- allow PROT_EXEC with mmap(2) calls
@@ -179,7 +190,7 @@ over the callee.  Use this mode only if the child absolutely must be
 run unconfined and LD_PRELOAD must be used. Any profile using this mode
 provides negligible security. Use at your own risk.
 
-Incompatible with 'Ux', 'px', 'Px', 'ix'.
+Incompatible with 'Ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
 
 =item B<Ux - unconfined execute -- scrub the environment>
 
@@ -193,7 +204,7 @@ designated child processes to be run without any AppArmor protection.
 Use this mode only if the child absolutely must be run unconfined. Use
 at your own risk.
 
-Incompatible with 'ux', 'px', 'Px', 'ix'.
+Incompatible with 'ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
 
 =item B<px - Discrete Profile execute mode>
 
@@ -205,7 +216,7 @@ B<WARNING> 'px' does not scrub the environment of variables such as
 LD_PRELOAD; as a result, the calling domain may have an undue amount of
 influence over the callee.
 
-Incompatible with 'Ux', 'ux', 'Px', 'ix'.
+Incompatible with 'Ux', 'ux', 'Px', 'cx', 'Cx', 'ix'.
 
 =item B<Px - Discrete Profile execute mode -- scrub the environment>
 
@@ -214,7 +225,28 @@ will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
 the environment, similar to setuid programs. (See ld.so(8) for some
 information on setuid/setgid environment scrubbing.)
 
-Incompatible with 'Ux', 'ux', 'px', 'ix'.
+Incompatible with 'Ux', 'ux', 'px', 'cx', 'Cx', 'ix'.
+
+=item B<cx - Transition to Subprofile execute mode>
+
+This mode requires that a local security profile is defined and forces an
+AppArmor domain transition to the named profile. If there is no profile
+defined then the access will be denied.
+
+B<WARNING> 'cx' does not scrub the environment of variables such as
+LD_PRELOAD; as a result, the calling domain may have an undue amount of
+influence over the callee.
+
+Incompatible with 'Ux', 'ux', 'px', 'Px', 'Cx', 'ix'.
+
+=item B<Cx - Transition to Subprofile execute mode -- scrub the environment>
+
+'Cx' allows the named program to run in 'cx' mode, but AppArmor
+will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
+the environment, similar to setuid programs. (See ld.so(8) for some
+information on setuid/setgid environment scrubbing.)
+
+Incompatible with 'Ux', 'ux', 'px', 'Px', 'cx', 'ix'.
 
 =item B<ix - Inherit execute mode>
 
@@ -228,7 +260,7 @@ profile, or losing the permissions of the current profile. There is no
 version to scrub the environment because 'ix' executions don't change
 privileges.
 
-Incompatible with 'Ux', 'ux', 'Px', 'px'. Implies 'm'.
+Incompatible with 'Ux', 'ux', 'Px', 'px', 'cx', 'Cx'. Implies 'm'.
 
 =item B<m - Allow executable mapping>
 
@@ -528,7 +560,7 @@ generated profiles.
 
 An example AppArmor profile:
 
-	# a variable definition
+	# a variable definition in the preamble
 	@{HOME} = /home/*/ /root/
 
 	# a comment about foo.
@@ -545,13 +577,23 @@ An example AppArmor profile:
   	  /tmp/foo.pid        wr,
   	  /tmp/foo.*          lrw,
 	  /@{HOME}/.foo_file  rw,
+	  /usr/bin/baz        Cx -> baz,
 
-	  # a comment about foo's subprofile, bar.
+	  # a comment about foo's hat (subprofile), bar.
   	  ^bar {
   	    /lib/ld-*.so*       rmix,
   	    /usr/bin/bar        rmix,
   	    /var/spool/*        rwl,
   	  }
+
+	  # a comment about foo's subprofile, baz.
+	  profile baz {
+	    #include <abstractions/bash>
+	    owner /proc/[0-9]*/stat r,
+	    /bin/bash ixr,
+	    /var/lib/baz/ r,
+	    owner /var/lib/baz/* rw,
+	  }
   	}
 
 =head1 FILES