aa_kernel_interface(3)

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

SYNOPSIS
#include <sys/apparmor.h>

typedef struct aa_kernel_interface aa_kernel_interface;

int aa_kernel_interface_new(aa_kernel_interface **kernel_interface, aa_features *kernel_features, const char *apparmorfs);

aa_kernel_interface *aa_kernel_interface_ref(aa_kernel_interface *kernel_interface);

void aa_kernel_interface_unref(aa_kernel_interface *kernel_interface);

int aa_kernel_interface_load_policy(aa_kernel_interface *kernel_interface, const char *buffer, size_t size);

int aa_kernel_interface_load_policy_from_file(aa_kernel_interface *kernel_interface, int dirfd, const char *path);

int aa_kernel_interface_load_policy_from_fd(aa_kernel_interface *kernel_interface, int fd);

int aa_kernel_interface_replace_policy(aa_kernel_interface *kernel_interface, const char *buffer, size_t size);

int aa_kernel_interface_replace_policy_from_file(aa_kernel_interface *kernel_interface, int dirfd, const char *path);

int aa_kernel_interface_replace_policy_from_fd(aa_kernel_interface *kernel_interface, int fd);

int aa_kernel_interface_remove_policy(aa_kernel_interface *kernel_interface, const char *fqname);

int aa_kernel_interface_write_policy(int fd, const char *buffer, size_t size);

Link with -lapparmor when compiling.

DESCRIPTION
The 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 aa_kernel_interface object based on an optional aa_features object and an optional path to the apparmor directory of securityfs, which is typically found at "/sys/kernel/security/apparmor/". If kernel_features is NULL, then the features of the current kernel are used. When specifying a valid kernel_features object, it must be compatible with the features of the currently running kernel. If apparmorfs is NULL, then the default location is used. The allocated kernel_interface object must be freed using aa_kernel_interface_unref().

aa_kernel_interface_ref() increments the reference count on the kernel_interface object.

aa_kernel_interface_unref() decrements the reference count on the 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 buffer will contain binary data. The size argument must specify the size of the buffer argument.

When loading or replacing from a file, the dirfd and path combination are used to specify the location of the file. See the openat(2) man page for examples of dirfd and path.

It is also possible to load or replace from a file descriptor specified by the 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 fqname argument. The operation will fail if a policy matching fqname is not found.

The aa_kernel_interface_write_policy() function allows for a policy, which is stored in buffer and consists of size bytes, to be written to a file descriptor. The fd must be open for writing and the file offset must be set appropriately.

RETURN VALUE
The aa_kernel_interface_new() function returns 0 on success and *kernel_interface will point to an aa_kernel_interface object that must be freed by aa_kernel_interface_unref(). -1 is returned on error, with errno set appropriately, and *kernel_interface will be set to NULL.

aa_kernel_interface_ref() returns the value of 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.

ERRORS
The errno value will be set according to the underlying error in the aa_kernel_interface family of functions that return -1 on error.

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.

BUGS
None known. If you find any, please report them at <https://gitlab.com/apparmor/apparmor/-/issues>.

SEE ALSO
aa_features(3), openat(2) and <https://wiki.apparmor.net>.