avc_add_callback(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | SECURITY EVENTS | RETURN VALUE | ERRORS | NOTES | AUTHOR | SEE ALSO | COLOPHON

avc_add_callback(3)     SELinux API documentation    avc_add_callback(3)

NAME         top

       avc_add_callback - additional event notification for SELinux
       userspace object managers

SYNOPSIS         top

       #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         top

       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         top

       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         top

       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         top

       ENOMEM An attempt to allocate memory failed.

NOTES         top

       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.

AUTHOR         top

       Eamon Walsh <ewalsh@tycho.nsa.gov>

SEE ALSO         top

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

COLOPHON         top

       This page is part of the selinux (Security-Enhanced Linux user-
       space libraries and tools) project.  Information about the
       project can be found at 
       ⟨https://github.com/SELinuxProject/selinux/wiki⟩.  If you have a
       bug report for this manual page, see
       ⟨https://github.com/SELinuxProject/selinux/wiki/Contributing⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/SELinuxProject/selinux⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-05-11.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

                               9 June 2004           avc_add_callback(3)

Pages that refer to this page: avc_cache_stats(3)avc_context_to_sid(3)avc_has_perm(3)avc_open(3)