1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
# This publication is intellectual property of Canonical Ltd. Its contents
# can be duplicated, either in part or in whole, provided that a copyright
# label is visibly located on each copy.
#
# All information found in this book has been compiled with utmost
# attention to detail. However, this does not guarantee complete accuracy.
# Neither Canonical Ltd, the authors, nor the translators shall be held
# liable for possible errors or the consequences thereof.
#
# Many of the software and hardware descriptions cited in this book
# are registered trademarks. All trade names are subject to copyright
# restrictions and may be registered trade marks. Canonical Ltd.
# essentially adhere to the manufacturer's spelling.
#
# Names of products and trademarks appearing in this book (with or without
# specific notation) are likewise subject to trademark and trade protection
# laws and may thus fall under copyright restrictions.
#
=pod
=head1 NAME
aa_query_label - query access permission associated with a label
aa_query_file_path, aa_query_file_path_len - query access permissions of a file path
aa_query_link_path, aa_query_link_path_len - query access permissions of a link path
=head1 SYNOPSIS
B<#include E<lt>sys/apparmor.hE<gt>>
B<int aa_query_label(uint32_t mask, char *query, size_t size, int *allowed, int *audited);>
B<int aa_query_file_path(uint32_t mask, const char *label, size_t label_len, const char *path, int *allowed, int *audited);>
B<int aa_query_file_path_len(uint32_t mask, const char *label, size_t label_len, const char *path, size_t path_len, int *allowed, int *audited);>
B<int aa_query_link_path(const char *label, const char *target, const char *link, int *allowed, int *audited);>
B<int aa_query_link_path_len(const char *label, size_t label_len, const char *target, size_t target_len, const char *link, size_t link_len, int *allowed, int *audited);>
Link with B<-lapparmor> when compiling.
=head1 DESCRIPTION
The B<aa_query_label> function fetches the current permissions granted by the
specified I<label> in the I<query> string.
The query is a raw binary formatted query, containing the label and
permission query to make. The returned I<allowed> and I<audited> values are
interpreted boolean values, simply stating whether the query is allowed and
if it is audited.
The mask of the query string is a bit mask of permissions to query and is
class type dependent (see B<AA_CLASS_xxx> entries in I<sys/apparmor.h>).
The format of the query string is also dependent on the B<AA_CLASS> and as
such the B<aa_query_xxx> helper functions should usually be used instead
of directly using B<aa_query_label>. If directly using the interface the
I<query> string is required to have a header of B<AA_QUERY_CMD_LABEL_SIZE>
that will be used by B<aa_query_label>.
The B<aa_query_file_path> and B<aa_query_file_path_len> functions are helper
function that assemble a properly formatted file path query for the
B<aa_query_label> function. The I<label> is a valid apparmor label as
returned by I<aa_splitcon> with I<label_len> being the length of the I<label>.
The I<path> is any valid filesystem path to query permissions for. For the
B<aa_query_file_path_len> variant the I<path_len> parameter specifies the
number of bytes in the I<path> to use as part of the query.
The B<aa_query_link_path> and B<aa_query_link_path_len> functions are helper
functions that assemble a properly formatted link path query for the
B<aa_query_label> function. The I<link_len> and I<target_len> parameters
specify the number of bytes in the I<link> and I<target> to use as part of
the query.
=head1 RETURN VALUE
On success 0 is returned, and the I<allowed> and I<audited> parameters
contain a boolean value of 0 not allowed/audited or 1 allowed/audited. On
error, -1 is returned, and errno(3) is set appropriately.
=head1 ERRORS
=over 4
=item B<EINVAL>
The requested I<mask> is empty.
The I<size> of the query is less than the query B<AA_QUERY_CMD_LABEL_SIZE>
The apparmor kernel module is not loaded or the kernel interface access
interface is not available
=item B<ENOMEM>
Insufficient memory was available.
=item B<EACCES>
Access to the specified I<label> or query interface was denied.
=item B<ENOENT>
The specified I<label> does not exist or is not visible.
=item B<ERANGE>
The confinement data is too large to fit in the supplied buffer.
=back
=head1 NOTES
The label permissions returned are only valid for the time of the
query and can change at any point in the future.
=head1 BUGS
None known. If you find any, please report them at
L<https://gitlab.com/apparmor/apparmor/-/issues>.
=head1 SEE ALSO
apparmor(7), apparmor.d(5), apparmor_parser(8), aa_getcon(2), aa_splitcon(3)
and L<https://wiki.apparmor.net>.
=cut
|
