# avc_add_callback

## NAME



           avc_add_callback - additional event notification for SELinux
           userspace object managers
    


## SYNOPSIS



           **#include <selinux/selinux.h>**
           **#include <selinux/avc.h>**
    
           **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) 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).
    
           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**.
    


* * *