xenial (3) avc_add_callback.3.gz

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)