avc_has_perm(3)

1avc_has_perm(3)            SELinux API documentation           avc_has_perm(3)
2
3
4

NAME

6       avc_has_perm,  avc_has_perm_noaudit,  avc_audit,  avc_entry_ref_init  -
7       obtain and audit SELinux access decisions
8

SYNOPSIS

10       #include <selinux/selinux.h>
11       #include <selinux/avc.h>
12
13       void avc_entry_ref_init(struct avc_entry_ref *aeref);
14
15       int avc_has_perm(security_id_t ssid, security_id_t tsid,
16                        security_class_t tclass, access_vector_t requested,
17                        struct avc_entry_ref *aeref, void *auditdata);
18
19       int avc_has_perm_noaudit(security_id_t ssid, security_id_t tsid,
20                        security_class_t tclass, access_vector_t requested,
21                        struct avc_entry_ref *aeref, struct av_decision *avd);
22
23       void avc_audit(security_id_t ssid, security_id_t tsid,
24                      security_class_t tclass, access_vector_t requested,
25                      struct av_decision *avd, int result, void *auditdata);
26

DESCRIPTION

28       Direct use of these functions is generally discouraged in favor of  the
29       higher  level  interface selinux_check_access(3) since the latter auto‐
30       matically handles the dynamic mapping of class and permission names  to
31       their policy values and proper handling of allow_unknown.
32
33       When  using  any  of  the functions that take policy integer values for
34       classes or permissions as inputs, use  string_to_security_class(3)  and
35       string_to_av_perm(3)  to  map  the  class and permission names to their
36       policy values.  These values may change across a policy reload, so they
37       should  be  re-acquired  on  every use or using a SELINUX_CB_POLICYLOAD
38       callback set via selinux_set_callback(3).
39
40       An alternative approach is to use selinux_set_mapping(3)  to  create  a
41       mapping  from class and permission index values used by the application
42       to the policy values, thereby allowing the application to pass its  own
43       fixed  constants for the classes and permissions to these functions and
44       internally mapping them on demand.  However, this also requires setting
45       up a callback as above to address policy reloads.
46
47       avc_entry_ref_init()  initializes an avc_entry_ref structure; see ENTRY
48       REFERENCES below.  This function may be implemented as a macro.
49
50       avc_has_perm() checks whether the requested permissions are granted for
51       subject  SID  ssid  and  target  SID tsid, interpreting the permissions
52       based on tclass and updating aeref, if non-NULL, to refer  to  a  cache
53       entry  with  the resulting decision.  The granting or denial of permis‐
54       sions is audited in accordance with the policy.  The auditdata  parame‐
55       ter is for supplemental auditing; see avc_audit() below.
56
57       avc_has_perm_noaudit()  behaves  as avc_has_perm() without producing an
58       audit message.  The access decision is  returned  in  avd  and  can  be
59       passed to avc_audit() explicitly.
60
61       avc_audit()  produces an audit message for the access query represented
62       by ssid, tsid, tclass, and requested, with a  decision  represented  by
63       avd.  Pass the value returned by avc_has_perm_noaudit() as result.  The
64       auditdata parameter is passed to the user-supplied func_audit  callback
65       and  can  be used to add supplemental information to the audit message;
66       see avc_init(3).
67

ENTRY REFERENCES

69       Entry references can be used to speed cache  performance  for  repeated
70       queries  on  the same subject and target.  The userspace AVC will check
71       the aeref argument, if supplied, before searching the cache on  a  per‐
72       mission  query.   After  a query is performed, aeref will be updated to
73       reference the cache entry for that query.  A subsequent  query  on  the
74       same  subject  and  target  will then have the decision at hand without
75       having to walk the cache.
76
77       After declaring an avc_entry_ref structure, use avc_entry_ref_init() to
78       initialize    it    before    passing    it    to   avc_has_perm()   or
79       avc_has_perm_noaudit() for the  first  time.   Using  an  uninitialized
80       structure will produce undefined behavior.
81

RETURN VALUE

83       If  requested  permissions are granted, zero is returned.  If requested
84       permissions are denied or an error occurred, -1 is returned  and  errno
85       is set appropriately.
86
87       In  permissive  mode, zero will be returned and errno unchanged even if
88       permissions were denied.  avc_has_perm() will still  produce  an  audit
89       message in this case.
90

ERRORS

92       EACCES A requested permission was denied.
93
94       EINVAL The  tclass  and/or the security contexts referenced by ssid and
95              tsid are not recognized by the currently loaded policy.
96
97       ENOMEM An attempt to allocate memory failed.
98

NOTES

100       Internal errors encountered by the userspace AVC may cause certain val‐
101       ues  of errno to be returned unexpectedly.  For example, netlink socket
102       errors may produce EACCES or EINVAL.  Make sure that  userspace  object
103       managers are granted appropriate access to netlink by the policy.
104

AUTHOR

106       Originally Eamon Walsh.  Updated by Stephen Smalley <sds@tycho.nsa.gov>
107