.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "AA_STACK_PROFILE 2" .TH AA_STACK_PROFILE 2 2024-03-25 "AppArmor 3.0.13" AppArmor .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME aa_stack_profile, aa_stack_onexec \- combine multiple profiles to confine a task .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fB#include \fR .PP \&\fBint aa_stack_profile(const char *profile);\fR .PP \&\fBint aa_stack_onexec(const char *profile);\fR .PP Link with \fB\-lapparmor\fR when compiling. .SH DESCRIPTION .IX Header "DESCRIPTION" AppArmor supports stacking two or more profiles when confining a task. The result is an intersection of all profiles which are stacked. Stacking profiles together is desirable when wanting to ensure that confinement will never become more permissive. When changing between two profiles, as performed with \&\fBaa_change_profile\fR\|(2), there is always the possibility that the new profile is more permissive than the old profile but that possibility is eliminated when using \fBaa_stack_profile()\fR. .PP To stack a profile with the current confinement context, a task can use the \&\fBaa_stack_profile()\fR function. The \fIprofile\fR parameter is a NUL-terminated string indicating a profile name that should be stacked with the current confinement. .PP Calling aa_stack_profile("profile_a") while unconfined is equivalent to calling aa_change_profile("profile_a") since the intersection of unconfined and "profile_a" is "profile_a". Calling aa_stack_profile("profile_b") while confined by "profile_a" results in the task's confinement to be the intersection of "profile_a" and "profile_b". The resulting confinement context will be represented as "profile_a//&profile_b" in audit log messages, the return value of \fBaa_getcon\fR\|(2), etc. .PP Confined programs wanting to use \fBaa_stack_profile()\fR need to have rules permitting stacking the named profile. See \fBapparmor.d\fR\|(8) for details. .PP Open file descriptors may not be remediated after a call to \fBaa_stack_profile()\fR so the calling program must \fBclose\fR\|(2) open file descriptors to ensure they are not available after calling \fBaa_stack_profile()\fR. .PP The \fBaa_stack_onexec()\fR function is like the \fBaa_stack_profile()\fR function except it specifies that the stacking 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 stacking 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. .SH "RETURN VALUE" .IX Header "RETURN VALUE" On success zero is returned. On error, \-1 is returned, and \&\fBerrno\fR\|(3) is set appropriately. .SH ERRORS .IX Header "ERRORS" .IP \fBEINVAL\fR 4 .IX Item "EINVAL" AppArmor is not loaded, neither a profile nor a namespace was specified, or the communication via the \fI/proc/*/attr/current\fR file did not conform to protocol. .IP \fBENOMEM\fR 4 .IX Item "ENOMEM" Insufficient kernel memory was available. .IP \fBENOENT\fR 4 .IX Item "ENOENT" The specified profile does not exist, or is not visible from the current namespace. .SH NOTES .IX Header "NOTES" Using \fBaa_stack_profile()\fR and related libapparmor functions are the only way to ensure compatibility between varying kernel versions. However, there may be some situations where libapparmor is not available and directly interacting with the AppArmor filesystem is required to stack a profile. .PP To immediately stack a profile named "profile_a", as performed with aa_stack_profile("profile_a"), the equivalent of this shell command can be used: .PP .Vb 1 \& $ echo \-n "stack profile_a" > /proc/self/attr/current .Ve .PP To stack a profile named "profile_a" at the next exec, as performed with aa_stack_onexec("profile_a"), the equivalent of this shell command can be used: .PP .Vb 1 \& $ echo \-n "stack profile_a" > /proc/self/attr/exec .Ve .PP These raw AppArmor filesystem operations must only be used when using libapparmor is not a viable option. .SH EXAMPLE .IX Header "EXAMPLE" The following example shows a simple, if contrived, use of \&\fBaa_stack_profile()\fR. .PP .Vb 8 \& #include \& #include \& #include \& #include \& #include \& #include \& #include \& #include \& \& static void read_passwd() \& { \& int fd; \& char buf[10]; \& \& if ((fd=open("/etc/passwd", O_RDONLY)) < 0) { \& perror("Failure opening /etc/passwd"); \& _exit(1); \& } \& \& /* Verify that we can read /etc/passwd */ \& memset(&buf, 0, 10); \& if (read(fd, &buf, 10) == \-1) { \& perror("Failure reading /etc/passwd"); \& _exit(1); \& } \& buf[9] = \*(Aq\e0\*(Aq; \& printf("/etc/passwd: %s\en", buf); \& close(fd); \& } \& \& int main(int argc, char * argv[]) \& { \& printf("Before aa_stack_profile():\en"); \& read_passwd(); \& \& /* stack the "i_cant_be_trusted_anymore" profile, which \& * should not have read access to /etc/passwd. */ \& if (aa_stack_profile("i_cant_be_trusted_anymore") < 0) { \& perror("Failure changing profile \-\- aborting"); \& _exit(1); \& } \& \& printf("After aa_stack_profile():\en"); \& read_passwd(); \& _exit(0); \& } .Ve .PP This code example requires a profile similar to the following to be loaded with \fBapparmor_parser\fR\|(8): .PP .Vb 6 \& # Confine stack_p to be able to read /etc/passwd and aa_stack_profile() \& # to the \*(Aqi_cant_be_trusted_anymore\*(Aq profile. \& /tmp/stack_p { \& /etc/ld.so.cache mr, \& /lib/ld\-*.so* mrix, \& /lib/libc*.so* mr, \& \& /etc/passwd r, \& \& # Needed for aa_stack_profile() \& change\-profile \-> &i_cant_be_trusted_anymore, \& /usr/lib/libapparmor*.so* mr, \& /proc/[0\-9]*/attr/current w, \& } .Ve .PP As well as the profile to stack: .PP .Vb 5 \& profile i_cant_be_trusted_anymore { \& /etc/ld.so.cache mr, \& /lib/ld\-*.so* mrix, \& /lib/libc*.so* mr, \& } .Ve .PP The output when run: .PP .Vb 6 \& $ /tmp/stack_p \& Before aa_stack_profile(): \& /etc/passwd: root:x:0: \& After aa_stack_profile(): \& Failure opening /etc/passwd: Permission denied \& $ .Ve .SH BUGS .IX Header "BUGS" None known. If you find any, please report them at . Note that using \&\fBaa_stack_profile\fR\|(2) without \fBexecve\fR\|(2) provides no memory barriers between different areas of a program; if address space separation is required, then separate processes should be used. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBapparmor\fR\|(7), \fBapparmor.d\fR\|(5), \fBapparmor_parser\fR\|(8), \fBaa_change_profile\fR\|(2), \&\fBaa_getcon\fR\|(2) and .