avc_add_callback(3)                 SELinux API documentation                 avc_add_callback(3)



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 SECU‐
       RITY EVENTS below.

       ssid, tsid, tclass, and perms specify the source and target SID's, target class, and  spe‐
       cific 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 occured; the remaining arguments are inter‐
       preted 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_call‐
       back()  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 excercised is
       AVC_CALLBACK_RESET.

AUTHOR
       Eamon Walsh <ewalsh AT tycho.gov>

SEE ALSO
       avc_init(3), avc_has_perm(3), avc_context_to_sid(3), avc_cache_stats(3),
       security_compute_av(3) selinux(8)



                                           9 June 2004                        avc_add_callback(3)