Create a section 3 man page for the aa_kernel_interface family of functions. Additionally, update the in-code descriptions to match the descriptions in the man page.
Signed-off-by: Tyler Hicks <[email protected]> --- libraries/libapparmor/doc/Makefile.am | 2 +- libraries/libapparmor/doc/aa_kernel_interface.pod | 162 ++++++++++++++++++++++ libraries/libapparmor/src/kernel_interface.c | 18 +-- 3 files changed, 172 insertions(+), 10 deletions(-) create mode 100644 libraries/libapparmor/doc/aa_kernel_interface.pod diff --git a/libraries/libapparmor/doc/Makefile.am b/libraries/libapparmor/doc/Makefile.am index d7aae8a..6a48d99 100644 --- a/libraries/libapparmor/doc/Makefile.am +++ b/libraries/libapparmor/doc/Makefile.am @@ -5,7 +5,7 @@ PODCHECKER = podchecker if ENABLE_MAN_PAGES -man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_features.3 +man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 aa_features.3 aa_kernel_interface.3 PODS = $(subst .2,.pod,$(man_MANS)) $(subst .3,.pod,$(man_MANS)) diff --git a/libraries/libapparmor/doc/aa_kernel_interface.pod b/libraries/libapparmor/doc/aa_kernel_interface.pod new file mode 100644 index 0000000..88ed2ec --- /dev/null +++ b/libraries/libapparmor/doc/aa_kernel_interface.pod @@ -0,0 +1,162 @@ +# 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 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_features_ref() returns the value of I<kernel_features>. + +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. + +=head1 BUGS + +None known. If you find any, please report them at +L<https://bugs.launchpad.net/apparmor/+filebug>. + +=head1 SEE ALSO + +aa_features(3), openat(2) and L<http://wiki.apparmor.net>. + +=cut diff --git a/libraries/libapparmor/src/kernel_interface.c b/libraries/libapparmor/src/kernel_interface.c index 293c93d..d558ee1 100644 --- a/libraries/libapparmor/src/kernel_interface.c +++ b/libraries/libapparmor/src/kernel_interface.c @@ -196,7 +196,7 @@ static int write_policy_file_to_iface(aa_kernel_interface *kernel_interface, } /** - * aa_kernel_interface_new - create a new kernel_interface from an optional path + * aa_kernel_interface_new - create a new aa_kernel_interface object from an optional path * @kernel_interface: will point to the address of an allocated and initialized * aa_kernel_interface object upon success * @kernel_features: features representing the currently running kernel (can be @@ -266,7 +266,7 @@ int aa_kernel_interface_new(aa_kernel_interface **kernel_interface, } /** - * aa_kernel_interface_ref - increments the ref count of a kernel_interface + * aa_kernel_interface_ref - increments the ref count of an aa_kernel_interface object * @kernel_interface: the kernel_interface * * Returns: the kernel_interface @@ -278,7 +278,7 @@ aa_kernel_interface *aa_kernel_interface_ref(aa_kernel_interface *kernel_interfa } /** - * aa_kernel_interface_unref - decrements the ref count and frees the kernel_interface when 0 + * aa_kernel_interface_unref - decrements the ref count and frees the aa_kernel_interface object when 0 * @kernel_interface: the kernel_interface (can be NULL) */ void aa_kernel_interface_unref(aa_kernel_interface *kernel_interface) @@ -291,7 +291,7 @@ void aa_kernel_interface_unref(aa_kernel_interface *kernel_interface) } /** - * aa_kernel_interface_load_policy - load a policy into the kernel + * aa_kernel_interface_load_policy - load a policy from a buffer into the kernel * @kernel_interface: valid aa_kernel_interface * @buffer: a buffer containing a policy * @size: the size of the buffer @@ -306,7 +306,7 @@ int aa_kernel_interface_load_policy(aa_kernel_interface *kernel_interface, } /** - * aa_kernel_interface_load_policy_from_file - load a policy into the kernel + * aa_kernel_interface_load_policy_from_file - load a policy from a file into the kernel * @kernel_interface: valid aa_kernel_interface * @path: path to a policy binary * @@ -320,7 +320,7 @@ int aa_kernel_interface_load_policy_from_file(aa_kernel_interface *kernel_interf } /** - * aa_kernel_interface_load_policy_from_fd - load a policy into the kernel + * aa_kernel_interface_load_policy_from_fd - load a policy from a file descriptor into the kernel * @kernel_interface: valid aa_kernel_interface * @fd: a pre-opened, readable file descriptor at the correct offset * @@ -334,7 +334,7 @@ int aa_kernel_interface_load_policy_from_fd(aa_kernel_interface *kernel_interfac } /** - * aa_kernel_interface_replace_policy - replace a policy in the kernel + * aa_kernel_interface_replace_policy - replace a policy in the kernel with a policy from a buffer * @kernel_interface: valid aa_kernel_interface * @buffer: a buffer containing a policy * @size: the size of the buffer @@ -350,7 +350,7 @@ int aa_kernel_interface_replace_policy(aa_kernel_interface *kernel_interface, } /** - * aa_kernel_interface_replace_policy_from_file - replace a policy in the kernel + * aa_kernel_interface_replace_policy_from_file - replace a policy in the kernel with a policy from a file * @kernel_interface: valid aa_kernel_interface * @path: path to a policy binary * @@ -364,7 +364,7 @@ int aa_kernel_interface_replace_policy_from_file(aa_kernel_interface *kernel_int } /** - * aa_kernel_interface_replace_policy_from_fd - replace a policy in the kernel + * aa_kernel_interface_replace_policy_from_fd - replace a policy in the kernel with a policy from a file descriptor * @kernel_interface: valid aa_kernel_interface * @fd: a pre-opened, readable file descriptor at the correct offset * -- 2.1.4 -- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
