mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 08:24:42 +01:00
c386d93581
Move suggested bug reporting from launchpad to gitlab Signed-off-by: John Johansen <john.johansen@canonical.com> Acked-by: Steve Beattie <steve.beattie@canonical.com>
165 lines
6.9 KiB
Text
165 lines
6.9 KiB
Text
# This publication is intellectual property of Canonical Ltd. Its contents
|
|
# can be duplicated, either in part or in whole, provided that a copyright
|
|
# label is visibly located on each copy.
|
|
#
|
|
# All information found in this book has been compiled with utmost
|
|
# attention to detail. However, this does not guarantee complete accuracy.
|
|
# Neither Canonical Ltd, the authors, nor the translators shall be held
|
|
# liable for possible errors or the consequences thereof.
|
|
#
|
|
# Many of the software and hardware descriptions cited in this book
|
|
# are registered trademarks. All trade names are subject to copyright
|
|
# restrictions and may be registered trade marks. Canonical Ltd.
|
|
# essentially adhere to the manufacturer's spelling.
|
|
#
|
|
# Names of products and trademarks appearing in this book (with or without
|
|
# specific notation) are likewise subject to trademark and trade protection
|
|
# laws and may thus fall under copyright restrictions.
|
|
#
|
|
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
aa_kernel_interface - an opaque object representing the AppArmor kernel interface for policy loading, replacing, and removing
|
|
|
|
aa_kernel_interface_new - create a new aa_kernel_interface object from an optional path
|
|
|
|
aa_kernel_interface_ref - increments the ref count of an aa_kernel_interface object
|
|
|
|
aa_kernel_interface_unref - decrements the ref count and frees the aa_kernel_interface object when 0
|
|
|
|
aa_kernel_interface_load_policy - load a policy from a buffer into the kernel
|
|
|
|
aa_kernel_interface_load_policy_from_file - load a policy from a file into the kernel
|
|
|
|
aa_kernel_interface_load_policy_from_fd - load a policy from a file descriptor into the kernel
|
|
|
|
aa_kernel_interface_replace_policy - replace a policy in the kernel with a policy from a buffer
|
|
|
|
aa_kernel_interface_replace_policy_from_file - replace a policy in the kernel with a policy from a file
|
|
|
|
aa_kernel_interface_replace_policy_from_fd - replace a policy in the kernel with a policy from a file descriptor
|
|
|
|
aa_kernel_interface_remove_policy - remove a policy from the kernel
|
|
|
|
aa_kernel_interface_write_policy - write a policy to a file descriptor
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<#include E<lt>sys/apparmor.hE<gt>>
|
|
|
|
B<typedef struct aa_kernel_interface aa_kernel_interface;>
|
|
|
|
B<int aa_kernel_interface_new(aa_kernel_interface **kernel_interface, aa_features *kernel_features, const char *apparmorfs);>
|
|
|
|
B<aa_kernel_interface *aa_kernel_interface_ref(aa_kernel_interface *kernel_interface);>
|
|
|
|
B<void aa_kernel_interface_unref(aa_kernel_interface *kernel_interface);>
|
|
|
|
B<int aa_kernel_interface_load_policy(aa_kernel_interface *kernel_interface, const char *buffer, size_t size);>
|
|
|
|
B<int aa_kernel_interface_load_policy_from_file(aa_kernel_interface *kernel_interface, int dirfd, const char *path);>
|
|
|
|
B<int aa_kernel_interface_load_policy_from_fd(aa_kernel_interface *kernel_interface, int fd);>
|
|
|
|
B<int aa_kernel_interface_replace_policy(aa_kernel_interface *kernel_interface, const char *buffer, size_t size);>
|
|
|
|
B<int aa_kernel_interface_replace_policy_from_file(aa_kernel_interface *kernel_interface, int dirfd, const char *path);>
|
|
|
|
B<int aa_kernel_interface_replace_policy_from_fd(aa_kernel_interface *kernel_interface, int fd);>
|
|
|
|
B<int aa_kernel_interface_remove_policy(aa_kernel_interface *kernel_interface, const char *fqname);>
|
|
|
|
B<int aa_kernel_interface_write_policy(int fd, const char *buffer, size_t size);>
|
|
|
|
Link with B<-lapparmor> when compiling.
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The I<aa_kernel_interface> object contains information about the AppArmor
|
|
kernel interface for policy loading, replacing, and removing.
|
|
|
|
The aa_kernel_interface_new() function creates an I<aa_kernel_interface> object
|
|
based on an optional I<aa_features> object and an optional path to the apparmor
|
|
directory of securityfs, which is typically found at
|
|
"/sys/kernel/security/apparmor/". If I<kernel_features> is NULL, then the
|
|
features of the current kernel are used. When specifying a valid
|
|
I<kernel_features> object, it must be compatible with the features of the
|
|
currently running kernel. If I<apparmorfs> is NULL, then the default location
|
|
is used. The allocated I<kernel_interface> object must be freed using
|
|
aa_kernel_interface_unref().
|
|
|
|
aa_kernel_interface_ref() increments the reference count on the
|
|
I<kernel_interface> object.
|
|
|
|
aa_kernel_interface_unref() decrements the reference count on the
|
|
I<kernel_interface> object and releases all corresponding resources when the
|
|
reference count reaches zero.
|
|
|
|
The aa_kernel_interface_load() family of functions load a policy into the
|
|
kernel. The operation will fail if a policy of the same name is already loaded.
|
|
Use the aa_kernel_interface_replace() family of functions if you wish to
|
|
replace a previously loaded policy with a new policy of the same name. The
|
|
aa_kernel_interface_replace() functions can also be used to load a policy that
|
|
does not correspond to a previously loaded policy.
|
|
|
|
When loading or replacing from a buffer, the I<buffer> will contain binary
|
|
data. The I<size> argument must specify the size of the I<buffer> argument.
|
|
|
|
When loading or replacing from a file, the I<dirfd> and I<path> combination are
|
|
used to specify the location of the file. See the openat(2) man page for
|
|
examples of I<dirfd> and I<path>.
|
|
|
|
It is also possible to load or replace from a file descriptor specified by the
|
|
I<fd> argument. The file must be open for reading and the file offset must be
|
|
set appropriately.
|
|
|
|
The aa_kernel_interface_remove_policy() function can be used to unload a
|
|
previously loaded policy. The fully qualified policy name must be specified
|
|
with the I<fqname> argument. The operation will fail if a policy matching
|
|
I<fqname> is not found.
|
|
|
|
The aa_kernel_interface_write_policy() function allows for a policy, which is
|
|
stored in I<buffer> and consists of I<size> bytes, to be written to a file
|
|
descriptor. The I<fd> must be open for writing and the file offset must be set
|
|
appropriately.
|
|
|
|
=head1 RETURN VALUE
|
|
|
|
The aa_kernel_interface_new() function returns 0 on success and
|
|
I<*kernel_interface> will point to an I<aa_kernel_interface> object that must
|
|
be freed by aa_kernel_interface_unref(). -1 is returned on error, with errno
|
|
set appropriately, and I<*kernel_interface> will be set to NULL.
|
|
|
|
aa_kernel_interface_ref() returns the value of I<kernel_interface>.
|
|
|
|
The aa_kernel_interface_load() family of functions, the
|
|
aa_kernel_interface_replace() family of functions,
|
|
aa_kernel_interface_remove(), and aa_kernel_interface_write_policy()
|
|
return 0 on success. -1 is returned on error, with errno set appropriately.
|
|
|
|
=head1 ERRORS
|
|
|
|
The errno value will be set according to the underlying error in the
|
|
I<aa_kernel_interface> family of functions that return -1 on error.
|
|
|
|
=head1 NOTES
|
|
|
|
All aa_kernel_interface functions described above are present in libapparmor
|
|
version 2.10 and newer.
|
|
|
|
aa_kernel_interface_unref() saves the value of errno when called and restores
|
|
errno before exiting in libapparmor version 2.12 and newer.
|
|
|
|
=head1 BUGS
|
|
|
|
None known. If you find any, please report them at
|
|
L<https://gitlab.com/apparmor/apparmor/-/issues>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
aa_features(3), openat(2) and L<https://wiki.apparmor.net>.
|
|
|
|
=cut
|