192 lines
5 KiB
Groff
192 lines
5 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Author: Eamon Walsh (ewalsh@tycho.nsa.gov) 2004
|
|
.TH "avc_add_callback" "3" "9 June 2004" "" "SELinux API documentation"
|
|
.SH "NAME"
|
|
avc_add_callback \- additional event notification for SELinux userspace object managers
|
|
.
|
|
.SH "SYNOPSIS"
|
|
.B #include <selinux/selinux.h>
|
|
.br
|
|
.B #include <selinux/avc.h>
|
|
.sp
|
|
.BI "int avc_add_callback(int (*" callback ")(uint32_t " event ,
|
|
.in +\w'int avc_add_callback(int (*callback)('u
|
|
.BI "security_id_t " ssid ,
|
|
.br
|
|
.BI "security_id_t " tsid ,
|
|
.br
|
|
.BI "security_class_t " tclass ,
|
|
.br
|
|
.BI "access_vector_t " perms ,
|
|
.br
|
|
.BI "access_vector_t *" out_retained "),"
|
|
.in
|
|
.in +\w'int avc_add_callback('u
|
|
.BI "uint32_t " events ", security_id_t " ssid ,
|
|
.br
|
|
.BI "security_id_t " tsid ", security_class_t " tclass ,
|
|
.br
|
|
.BI "access_vector_t " perms ");"
|
|
.in
|
|
.
|
|
.SH "DESCRIPTION"
|
|
.BR 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.
|
|
|
|
.I events
|
|
is the
|
|
.RI bitwise- or
|
|
of security events on which to register the callback; see
|
|
.B SECURITY EVENTS
|
|
below.
|
|
|
|
.IR ssid ,
|
|
.IR tsid ,
|
|
.IR tclass ,
|
|
and
|
|
.I perms
|
|
specify the source and target SID's, target class, and specific permissions that the callback wishes to monitor. The special symbol
|
|
.B SECSID_WILD
|
|
may be passed as the
|
|
.I source
|
|
or
|
|
.I target
|
|
and will cause any SID to match.
|
|
|
|
.I callback
|
|
is the callback function provided by the userspace object manager. The
|
|
.I 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
|
|
.I errno
|
|
set appropriately (but see
|
|
.B RETURN VALUE
|
|
below).
|
|
.
|
|
.SH "SECURITY EVENTS"
|
|
In all cases below,
|
|
.I ssid
|
|
and/or
|
|
.I tsid
|
|
may be set to
|
|
.BR SECSID_WILD ,
|
|
indicating that the change applies to all source and/or target SID's. Unless otherwise indicated, the
|
|
.I out_retained
|
|
parameter is unused.
|
|
.
|
|
.TP
|
|
.B AVC_CALLBACK_GRANT
|
|
Previously denied permissions are now granted for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.I perms
|
|
indicates the permissions to grant.
|
|
.TP
|
|
.B AVC_CALLBACK_TRY_REVOKE
|
|
Previously granted permissions are now conditionally revoked for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.I perms
|
|
indicates the permissions to revoke. The callback should set
|
|
.I out_retained
|
|
to the subset of
|
|
.I perms
|
|
which are retained as migrated permissions. Note that
|
|
.I out_retained
|
|
is ignored if the callback returns \-1.
|
|
.TP
|
|
.B AVC_CALLBACK_REVOKE
|
|
Previously granted permissions are now unconditionally revoked for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.I perms
|
|
indicates the permissions to revoke.
|
|
.TP
|
|
.B AVC_CALLBACK_RESET
|
|
Indicates that the cache was flushed. The SID, class, and permission arguments are unused and are set to NULL.
|
|
.TP
|
|
.B AVC_CALLBACK_AUDITALLOW_ENABLE
|
|
The permissions given by
|
|
.I perms
|
|
should now be audited when granted for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.TP
|
|
.B AVC_CALLBACK_AUDITALLOW_DISABLE
|
|
The permissions given by
|
|
.I perms
|
|
should no longer be audited when granted for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.TP
|
|
.B AVC_CALLBACK_AUDITDENY_ENABLE
|
|
The permissions given by
|
|
.I perms
|
|
should now be audited when denied for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.TP
|
|
.B AVC_CALLBACK_AUDITDENY_DISABLE
|
|
The permissions given by
|
|
.I perms
|
|
should no longer be audited when denied for
|
|
.IR ssid ,
|
|
.I tsid
|
|
with respect to
|
|
.IR tclass .
|
|
.
|
|
.SH "RETURN VALUE"
|
|
On success,
|
|
.BR avc_add_callback ()
|
|
returns zero. On error, \-1 is returned and
|
|
.I 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
|
|
.B EINVAL
|
|
on all further permission checks until
|
|
.BR avc_destroy (3)
|
|
is called. In non-threaded mode, the permission check on which the error occurred will return \-1 and the value of
|
|
.I errno
|
|
encountered to the caller. In both cases, a log message is produced and the kernel may be notified of the error.
|
|
.
|
|
.SH "ERRORS"
|
|
.TP
|
|
.B ENOMEM
|
|
An attempt to allocate memory failed.
|
|
.
|
|
.SH "NOTES"
|
|
If the userspace AVC is running in threaded mode, callbacks registered via
|
|
.BR 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
|
|
.BR 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
|
|
.BR AVC_CALLBACK_RESET .
|
|
.
|
|
.SH "AUTHOR"
|
|
Eamon Walsh <ewalsh@tycho.nsa.gov>
|
|
.
|
|
.SH "SEE ALSO"
|
|
.ad l
|
|
.nh
|
|
.BR avc_init (3),
|
|
.BR avc_has_perm (3),
|
|
.BR avc_context_to_sid (3),
|
|
.BR avc_cache_stats (3),
|
|
.BR security_compute_av (3)
|
|
.BR selinux (8)
|