avc_add_callback(3)

1avc_add_callback(3)       SE Linux API documentation       avc_add_callback(3)
2
3
4

NAME

6       avc_add_callback  - additional event notification for SELinux userspace
7       object managers.
8

SYNOPSIS

10       #include <selinux/selinux.h>
11
12       #include <selinux/avc.h>
13
14       int avc_add_callback(int (*callback)(uint32_t event,
15                                            security_id_t ssid,
16
17                                            security_id_t tsid,
18
19                                            security_class_t tclass,
20
21                                            access_vector_t perms,
22
23                                            access_vector_t *out_retained),
24                            uint32_t events, security_id_t ssid,
25
26                            security_id_t tsid, security_class_t tclass,
27
28                            access_vector_t perms);
29

DESCRIPTION

31       avc_add_callback is used to register  callback  functions  on  security
32       events.  The purpose of this functionality is to allow userspace object
33       managers to take additional action when a policy change, usually a pol‐
34       icy reload, causes permissions to be granted or revoked.
35
36       events  is  the  bitwise-or of security events on which to register the
37       callback; see SECURITY EVENTS below.
38
39       ssid, tsid, tclass, and perms specify the source and target SID's, tar‐
40       get  class,  and specific permissions that the callback wishes to moni‐
41       tor.  The special symbol SECSID_WILD may be passed  as  the  source  or
42       target and will cause any SID to match.
43
44       callback is the callback function provided by the userspace object man‐
45       ager.  The event argument indicates the security event  which  occured;
46       the  remaining  arguments  are  interpreted  according  to the event as
47       described below.  The return value of the callback should  be  zero  on
48       success, -1 on error with errno set appropriately (but see RETURN VALUE
49       below).
50
51

SECURITY EVENTS

53       In all cases below, ssid and/or tsid may be set to  SECSID_WILD,  indi‐
54       cating  that  the  change  applies  to  all source and/or target SID's.
55       Unless otherwise indicated, the out_retained parameter is unused.
56
57
58       AVC_CALLBACK_GRANT
59              Previously denied permissions are now  granted  for  ssid,  tsid
60              with  respect  to  tclass.   perms  indicates the permissions to
61              grant.
62
63       AVC_CALLBACK_TRY_REVOKE
64              Previously granted permissions are now conditionally revoked for
65              ssid,  tsid with respect to tclass.  perms indicates the permis‐
66              sions to revoke.  The callback should set  out_retained  to  the
67              subset  of  perms  which  are  retained as migrated permissions.
68              Note that out_retained is ignored if the callback returns -1.
69
70       AVC_CALLBACK_REVOKE
71              Previously granted permissions are now  unconditionally  revoked
72              for ssid, tsid with respect to tclass.  perms indicates the per‐
73              missions to revoke.
74
75       AVC_CALLBACK_RESET
76              Indicates that the cache was flushed.  The SID, class, and  per‐
77              mission arguments are unused and are set to NULL.
78
79       AVC_CALLBACK_AUDITALLOW_ENABLE
80              The  permissions  given  by  perms  should  now  be audited when
81              granted for ssid, tsid with respect to tclass.
82
83       AVC_CALLBACK_AUDITALLOW_DISABLE
84              The permissions given by perms should no longer be audited  when
85              granted for ssid, tsid with respect to tclass.
86
87       AVC_CALLBACK_AUDITDENY_ENABLE
88              The permissions given by perms should now be audited when denied
89              for ssid, tsid with respect to tclass.
90
91       AVC_CALLBACK_AUDITDENY_DISABLE
92              The permissions given by perms should no longer be audited  when
93              denied for ssid, tsid with respect to tclass.
94
95

RETURN VALUE

97       On  success,  avc_add_callback  returns zero.  On error, -1 is returned
98       and errno is set appropriately.
99
100       A return value of -1 from a callback is interpreted as a failed  policy
101       operation.   If such a return value is encountered, all remaining call‐
102       backs registered on the  event  are  called.   In  threaded  mode,  the
103       netlink  handler  thread may then terminate and cause the userspace AVC
104       to return EINVAL on all further permission checks until  avc_destroy(3)
105       is  called.   In  non-threaded  mode, the permission check on which the
106       error occurred will return -1 and the value of errno encountered to the
107       caller.  In both cases, a log message is produced and the kernel may be
108       notified of the error.
109
110

ERRORS

112       ENOMEM An attempt to allocate memory failed.
113
114

NOTES

116       If the userspace AVC is running in threaded mode, callbacks  registered
117       via avc_add_callback may be executed in the context of the netlink han‐
118       dler thread.  This will likely introduce synchronization issues requir‐
119       ing the use of locks.  See avc_init(3).
120
121       Support for dynamic revocation and retained permissions is mostly unim‐
122       plemented in the SELinux kernel module.  The only security  event  that
123       currently gets excercised is AVC_CALLBACK_RESET.
124
125

AUTHOR

127       Eamon Walsh <ewalsh@epoch.ncsc.mil>
128
129