Provided by: libselinux1-dev_2.2.2-1ubuntu0.1_amd64 bug

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  occured;  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  excercised  is
       AVC_CALLBACK_RESET.

AUTHOR

       Eamon Walsh <ewalsh@tycho.nsa.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)