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

[Seth Arnold]

Yay! A few comments inline, none so important to delay committing, but
if it easy to fix before committing, please consider. :)

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
>