[apparmor] [PATCH 6/6] Update documentation for change_hatv, change_hat_varags and change_onexec

Fri Feb 18 02:51:02 UTC 2011

On 02/17/2011 06:07 PM, Seth Arnold wrote:
> Yay! A few comments inline, none so important to delay committing, but
> if it easy to fix before committing, please consider. :)

Hehe we all know what a master word smith I am so, any and all improvements
are more than welcome :)


> 
> Thanks!
> 
> On Thu, Feb 17, 2011 at 5:22 PM, John Johansen
> <john.johansen at canonical.com> wrote:
>> Signed-off-by: John Johansen <john.johansen at canonical.com>
>> ---
>>  libraries/libapparmor/doc/aa_change_hat.pod     |   27 ++++++++++++++++++----
>>  libraries/libapparmor/doc/aa_change_profile.pod |   10 +++++++-
>>  2 files changed, 31 insertions(+), 6 deletions(-)
>>
>> diff --git a/libraries/libapparmor/doc/aa_change_hat.pod b/libraries/libapparmor/doc/aa_change_hat.pod
>> index c32dcc8..77116f0 100644
>> --- a/libraries/libapparmor/doc/aa_change_hat.pod
>> +++ b/libraries/libapparmor/doc/aa_change_hat.pod
>> @@ -29,6 +29,8 @@ aa_change_hat  - change to or from a "hat" within a AppArmor profile
>>  B<#include E<lt>sys/apparmor.hE<gt>>
>>
>>  B<int aa_change_hat (char *subprofile, unsigned long magic_token);>
>> +B<int aa_change_hatv (char *subprofiles[], unsigned long magic_token);>
>> +B<int aa_change_hat_vargs (unsigned long magic_token, ...);>
>>
>>  Link with B<-lapparmor> when compiling.
>>
>> @@ -37,11 +39,29 @@ Link with B<-lapparmor> when compiling.
>>  An AppArmor profile applies to an executable program; if a portion of
>>  the program needs different access permissions than other portions,
>>  the program can "change hats" to a different role, also known as a
>> -subprofile. To change into a new hat, it calls the aa_change_hat()
>> -function to do so. It passes in a pointer to the I<subprofile> which it
>> +subprofile.
>> +
>> +To change into a new hat, it calls one of the family of change_hat
>> +functions to do so. It passes in a pointer to the I<subprofile> which it
>>  wants to change into, and a 64bit I<magic_token>.  The I<magic_token>
>>  is used to return out of the subprofile at a later time.
>>
>> +The aa_change_hat() function allows specifying the name of a single
>> +I<subprofile> that the application wants to change into.  A pointer to the
>> +name of the I<subprofile> is pass along with the I<magic_token>.  If the
>> +profile is not present the call will fail with the appropriate error.
> 
> s/is pass/is passed/
> 
>> +The aa_change_hatv() function allows passing a I<NULL> terminated vector
>> +of pointers to I<subprofile> names which will be tried in order.  The
>> +first I<subprofile> in the vector that exists will be transitioned to
>> +and if none of the I<subprofiles> exist the call will fail with the
>> +appropriate error.
>> +
>> +The aa_change_hat_vargs() function is a convience wrapper for the
> 
> convenience
> 
>> +aa_change_hatv() function.  After the I<magic_token> it takes an arbitrary
>> +number of pointers to I<subprofile> names.  It will assembles list
>> +I<subprofile> names into a vector and call aa_change_hatv().
>> +
> 
> Suggest replacing "It will assembles ..." with this:
> 
> Similar to execl(3), aa_change_hat_vargs() assembles the list of
> I<subprofile> names into a vector and calls aa_change_hatv().
> 
>>  If a program wants to return out of the current subprofile to the
>>  original profile, it calls aa_change_hat() with a pointer to NULL as
>>  the I<subprofile>, and the original I<magic_token> value. If the
>> @@ -51,9 +71,6 @@ original profile will not happen, and the current task will be killed.
>>  If the I<magic_token> matches the original token, then the process will
>>  change back to the original profile.
>>
>> -If the program wants to change to a subprofile that it can never
>> -change back out of, the application should call aa_change_hat() with a
>> -I<magic_token> of I<0>.
>>
>>  As both read(2) and write(2) are mediated, a file must be listed in a
>>  subprofile definition if the file is to be accessed while the process
>> diff --git a/libraries/libapparmor/doc/aa_change_profile.pod b/libraries/libapparmor/doc/aa_change_profile.pod
>> index a1d4110..fc6e98a 100644
>> --- a/libraries/libapparmor/doc/aa_change_profile.pod
>> +++ b/libraries/libapparmor/doc/aa_change_profile.pod
>> @@ -23,7 +23,7 @@
>>  =head1 NAME
>>
>>  aa_change_profile  - change to another profile within an AppArmor profile
>> -
>> +aa_change_onexec - change to another profile at the next exec
>>  =head1 SYNOPSIS
>>
>>  B<#include E<lt>sys/apparmor.hE<gt>>
>> @@ -53,6 +53,14 @@ are not available after calling aa_change_profile(). As aa_change_profile()
>>  is typically used just before execve(2), you may want to use open(2) or
>>  fcntl(2) with close-on-exec.
>>
>> +The aa_change_onexec() function is like the aa_change_profile() function
>> +except it specifies that the profile transition should take place on the
>> +next exec instead of immediately.  The delayed profile change takes
>> +precedence over any exec transition rules within the confining profile.
>> +Delaying the profile boundry has a couple of advantages, it removes the
> 
> boundary
> 
>> +need for stub transition profiles and the exec boundry is a natural security
> 
> boundary
> 
>> +layer where potentially sensative memory is unmapped.
> 
> sensitive
> 
>> +
>>  =head1 RETURN VALUE
>>
>>  On success zero is returned. On error, -1 is returned, and
>> --
>> 1.7.1
>>
>>
>> --
>> AppArmor mailing list
>> AppArmor at lists.ubuntu.com
>> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
>>