mir/apparmor
2
0
Fork 0
mirror of https://gitlab.com/apparmor/apparmor synced 2025-09-04 08:15:21 +00:00
Code Issues Releases Wiki Activity

Update documentation for change_hatv, change_hat_varags and change_onexec

Browse Source 
Signed-off-by: John Johansen <john.johansen@canonical.com>
This commit is contained in:
John Johansen
2011-02-22 03:55:53 -08:00
parent 6d62a3634e
commit ee0d5b7d50
2 changed files with 32 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
libraries/libapparmor/doc/aa_change_hat.pod
View File

@@ -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<#include E<lt>sys/apparmor.hE<gt>>
B<int aa_change_hat (char *subprofile, unsigned long magic_token);> 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. Link with B<-lapparmor> when compiling.
@@ -37,11 +39,30 @@ Link with B<-lapparmor> when compiling.
An AppArmor profile applies to an executable program; if a portion of An AppArmor profile applies to an executable program; if a portion of
the program needs different access permissions than other portions, the program needs different access permissions than other portions,
the program can "change hats" to a different role, also known as a 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() subprofile.
function to do so. It passes in a pointer to the I<subprofile> which it
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> 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. 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 passed along with the I<magic_token>. If the
profile is not present the call will fail with the appropriate error.
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 convenience wrapper for the
aa_change_hatv() function. After the I<magic_token> it takes an arbitrary
number of pointers to I<subprofile> names. 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 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 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 the I<subprofile>, and the original I<magic_token> value. If the
@@ -51,9 +72,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 If the I<magic_token> matches the original token, then the process will
change back to the original profile. 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 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 subprofile definition if the file is to be accessed while the process

10
libraries/libapparmor/doc/aa_change_profile.pod
View File

@@ -23,7 +23,7 @@
=head1 NAME =head1 NAME
aa_change_profile - change to another profile within an AppArmor profile aa_change_profile - change to another profile within an AppArmor profile
aa_change_onexec - change to another profile at the next exec
=head1 SYNOPSIS =head1 SYNOPSIS
B<#include E<lt>sys/apparmor.hE<gt>> 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 is typically used just before execve(2), you may want to use open(2) or
fcntl(2) with close-on-exec. 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 boundary has a couple of advantages, it removes the
need for stub transition profiles and the exec boundary is a natural security
layer where potentially sensitive memory is unmapped.
=head1 RETURN VALUE =head1 RETURN VALUE
On success zero is returned. On error, -1 is returned, and On success zero is returned. On error, -1 is returned, and