--- name: "avc_add_callback" section: "3" platform: "linux" package: "libselinux1-dev" version: "3.8.1-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/avc_add_callback" --- # avc\_add\_callback(3) additional event notification for SELinux userspace object managers ## NAME avc\_add\_callback - additional event notification for SELinux userspace object managers ## SYNOPSIS **#include \**\ **#include \** **int avc\_add\_callback(int (\****callback***)(uint32\_t** *event***,** **security\_id\_t** *ssid***,**\ **security\_id\_t** *tsid***,**\ **security\_class\_t** *tclass***,**\ **access\_vector\_t** *perms***,**\ **access\_vector\_t \****out\_retained***),** **uint32\_t** *events***, security\_id\_t** *ssid***,**\ **security\_id\_t** *tsid***, security\_class\_t** *tclass***,**\ **access\_vector\_t** *perms***);** ## DESCRIPTION **avc\_add\_callback**() is used to register callback functions on security events. The purpose of this functionality is to allow userspace object managers to take additional action when a policy change, usually a policy reload, causes permissions to be granted or revoked. *events* is the bitwise-*or* of security events on which to register the callback; see **SECURITY EVENTS** below. *ssid*, *tsid*, *tclass*, and *perms* specify the source and target SID's, target class, and specific permissions that the callback wishes to monitor. The special symbol **SECSID\_WILD** may be passed as the *source* or *target* and will cause any SID to match. *callback* is the callback function provided by the userspace object manager. The *event* argument indicates the security event which occurred; the remaining arguments are interpreted according to the event as described below. The return value of the callback should be zero on success, -1 on error with *errno* set appropriately (but see **RETURN VALUE** below). ## SECURITY EVENTS In all cases below, *ssid* and/or *tsid* may be set to **SECSID\_WILD**, indicating that the change applies to all source and/or target SID's. Unless otherwise indicated, the *out\_retained* parameter is unused. - **AVC\_CALLBACK\_GRANT** Previously denied permissions are now granted for *ssid*, *tsid* with respect to *tclass*. *perms* indicates the permissions to grant. - **AVC\_CALLBACK\_TRY\_REVOKE** Previously granted permissions are now conditionally revoked for *ssid*, *tsid* with respect to *tclass*. *perms* indicates the permissions to revoke. The callback should set *out\_retained* to the subset of *perms* which are retained as migrated permissions. Note that *out\_retained* is ignored if the callback returns -1. - **AVC\_CALLBACK\_REVOKE** Previously granted permissions are now unconditionally revoked for *ssid*, *tsid* with respect to *tclass*. *perms* indicates the permissions to revoke. - **AVC\_CALLBACK\_RESET** Indicates that the cache was flushed. The SID, class, and permission arguments are unused and are set to NULL. - **AVC\_CALLBACK\_AUDITALLOW\_ENABLE** The permissions given by *perms* should now be audited when granted for *ssid*, *tsid* with respect to *tclass*. - **AVC\_CALLBACK\_AUDITALLOW\_DISABLE** The permissions given by *perms* should no longer be audited when granted for *ssid*, *tsid* with respect to *tclass*. - **AVC\_CALLBACK\_AUDITDENY\_ENABLE** The permissions given by *perms* should now be audited when denied for *ssid*, *tsid* with respect to *tclass*. - **AVC\_CALLBACK\_AUDITDENY\_DISABLE** The permissions given by *perms* should no longer be audited when denied for *ssid*, *tsid* with respect to *tclass*. ## RETURN VALUE On success, **avc\_add\_callback**() returns zero. On error, -1 is returned and *errno* is set appropriately. A return value of -1 from a callback is interpreted as a failed policy operation. If such a return value is encountered, all remaining callbacks registered on the event are called. In threaded mode, the netlink handler thread may then terminate and cause the userspace AVC to return **EINVAL** on all further permission checks until [**avc\_destroy**(3)](/avc_destroy/3.md) is called. In non-threaded mode, the permission check on which the error occurred will return -1 and the value of *errno* encountered to the caller. In both cases, a log message is produced and the kernel may be notified of the error. ## ERRORS - **ENOMEM** An attempt to allocate memory failed. ## NOTES If the userspace AVC is running in threaded mode, callbacks registered via **avc\_add\_callback**() may be executed in the context of the netlink handler thread. This will likely introduce synchronization issues requiring the use of locks. See [**avc\_init**(3)](/avc_init/3.md). Support for dynamic revocation and retained permissions is mostly unimplemented in the SELinux kernel module. The only security event that currently gets exercised is **AVC\_CALLBACK\_RESET**. ## AUTHOR Eamon Walsh \ ## SEE ALSO [**avc\_init**(3)](/avc_init/3.md), [**avc\_has\_perm**(3)](/avc_has_perm/3.md), [**avc\_context\_to\_sid**(3)](/avc_context_to_sid/3.md), [**avc\_cache\_stats**(3)](/avc_cache_stats/3.md), [**security\_compute\_av**(3)](/security_compute_av/3.md) [**selinux**(8)](/selinux/8.md)