.\" Hey Emacs! This file is -*- nroff -*- source.

.\"

.\" Author: Eamon Walsh (ewalsh@epoch.ncsc.mil) 2004

.TH "avc_add_callback" "3" "9 June 2004" "" "SE Linux API documentation"

.SH "NAME"

avc_add_callback \- additional event notification for userspace object managers.

.SH "SYNOPSIS"

.B #include <selinux/selinux.h>

.br

.B #include <selinux/avc.h>

.sp

.BI "int avc_add_callback(int (*" callback ")(u_int32_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 "u_int32_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"

.B 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 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

.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,

.B 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

.B 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 excercised is

.BR AVC_CALLBACK_RESET .

.SH "AUTHOR"

Eamon Walsh <ewalsh@epoch.ncsc.mil>

.SH "SEE ALSO"

.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)