From cf68b1304218efd7794d13f405fa6f80c7458c55 Mon Sep 17 00:00:00 2001
From: John Johansen <john.johansen@canonical.com>
Date: Tue, 24 Mar 2015 03:52:31 -0700
Subject: [PATCH] Add basic documentation of change_profile rules to apparmor.d
 man page

Signed-off-by: John Johansen <john.johansen@canonical.com>
Acked-by: Christian Boltz <apparmor@cboltz.de>
---
 parser/apparmor.d.pod | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod
index f54d450e7..ebc649002 100644
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -54,7 +54,7 @@ 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> | I<CAPABILITY RULE> | I<NETWORK RULE> | I<MOUNT RULE> | I<PIVOT ROOT RULE> | I<DBUS RULE> | I<UNIX RULE> | I<FILE RULE> | 'change_profile -E<gt> ' I<PROGRAMCHILD> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | I<CAPABILITY RULE> | I<NETWORK RULE> | I<MOUNT RULE> | I<PIVOT ROOT RULE> | I<DBUS RULE> | I<UNIX RULE> | I<FILE RULE> | I<CHANGE_PROFILE RULE> ) ... ] '}'
 
 B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
 
@@ -211,6 +211,10 @@ B<ALPHA> = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
 
 B<ALPHANUMERIC> = ('0', '1', '2', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
 
+B<CHANGE_PROFILE RULE> = 'change_profile' [ I<EXEC COND> ] [ -E<gt> I<PROGRAMCHILD> ]
+
+B<EXEC COND> = I<FILEGLOB>
+
 =back
 
 All resources and programs need a full path. There may be any number of
@@ -958,6 +962,42 @@ the much wider permission rule of
 
    network unix,
 
+=head2 change_profile rules
+
+AppArmor supports self directed profile transitions via the change_profile
+api. Change_profile rules control which permissions for which profiles
+a confined task can transition to.  The profile name can contain apparmor
+pattern matching to specify different profiles.
+
+  change_profile -> **,
+
+The change_profile api allows the transition to be delayed until when
+a task executes another application. If an exec rule transition is
+specified for the application and the change_profile api is used to
+make a transition at exec time, the transition specified by the
+change_profile api takes precedence.
+
+The Change_profile permission can restrict which profiles can be transitioned
+to based off of the executable name by specifying the exec condition.
+
+  change_profile /bin/bash -> new_profile,
+
+The restricting of the transition profile to a given executable at exec
+time is only useful when then current task is allowed to make dynamic
+decisions about what confinement should be, but the decision set needs
+to be controlled. A list of profiles or multiple rules can be used to
+specify the profiles in the set. Eg.
+
+  change_profile /bin/bash -> {new_profile1,new_profile2,new_profile3},
+
+An exec rule can be used to specify a transition for the executable, if
+the transition should be allowed even if the change_profile api has not
+been used to select a transition for those available in the change_profile
+rule set.  Eg.
+
+  /bin/bash Px -> new_profile1,
+  change_profile /bin/bash -> {new_profile1,new_profile2,new_profile3},
+
 =head2 Variables
 
 AppArmor's policy language allows embedding variables into file rules