xref: /aosp_15_r20/external/ltp/include/tst_capability.h (revision 49cdfc7efb34551c7342be41a7384b9c40d7cab7)
1 /* SPDX-License-Identifier: GPL-2.0-or-later */
2 /*
3  * Copyright (c) 2019 Richard Palethorpe <[email protected]>
4  */
5 
6 /**
7  * DOC: Capabilities introduction
8  *
9  * Limited capability operations without libcap.
10  */
11 
12 #ifndef TST_CAPABILITY_H
13 #define TST_CAPABILITY_H
14 
15 #include <stdint.h>
16 
17 #include "lapi/capability.h"
18 
19 /**
20  * enum tst_cap_act - A capability action masks.
21  *
22  * @TST_CAP_DROP: Drop capabilities.
23  * @TST_CAP_REQ: Add capabilities.
24  */
25 enum tst_cap_act {
26 	TST_CAP_DROP = 1,
27 	TST_CAP_REQ = (1 << 1)
28 };
29 
30 /**
31  * struct tst_cap_user_header - Kernel capget(), capset() syscall header.
32  *
33  * @version: A capability API version.
34  * @pid: A process to operate on.
35  */
36 struct tst_cap_user_header {
37 	uint32_t version;
38 	int pid;
39 };
40 
41 /**
42  * struct tst_cap_user_data - Kernel capset(), capget() syscall payload.
43  *
44  * @effective: A capability effective set.
45  * @permitted: A capability permitted set.
46  * @inheritable: A capability inheritable set.
47  */
48 struct tst_cap_user_data {
49 	uint32_t effective;
50 	uint32_t permitted;
51 	uint32_t inheritable;
52 };
53 
54 /**
55  * struct tst_cap - A capability to alter.
56  *
57  * @action: What should we do, i.e. drop or add a capability.
58  * @id: A capability id.
59  * @name: A capability name.
60  *
61  * This structure is usually constructed with the TST_CAP() macro so that the
62  * name is created automatically.
63  */
64 struct tst_cap {
65 	uint32_t action;
66 	uint32_t id;
67 	char *name;
68 };
69 
70 /**
71  * TST_CAP() - Create a struct tst_cap entry.
72  *
73  * @action: What should we do, i.e. drop or add capability.
74  * @capability: A capability id, e.g. CAP_BPF.
75  */
76 #define TST_CAP(action, capability) {action, capability, #capability}
77 
78 /**
79  * tst_capget() - Get the capabilities as decided by hdr.
80  *
81  * @hdr: A capability user header stores a pid to operate on and which
82  *       capability API version is used.
83  * @data: A memory to store the capabilities to. The memory pointed to by data
84  *        should be large enough to store two structs.
85  *
86  * return: Returns 0 on success, -1 on a failure and sets errno.
87  */
88 int tst_capget(struct tst_cap_user_header *hdr,
89 	       struct tst_cap_user_data *data);
90 
91 /**
92  * tst_capset() - Set the capabilities as decided by hdr and data
93  *
94  * @hdr: A capability user header stores a pid to operate on and which
95  *       capability API version is used.
96  * @data: A memory to store the capabilities to. The memory pointed to by data
97  *        should be large enough to store two structs.
98  *
99  * return: Returns 0 on success, -1 on a failure and sets errno.
100  */
101 int tst_capset(struct tst_cap_user_header *hdr,
102 	       const struct tst_cap_user_data *data);
103 
104 /**
105  * tst_cap_action() - Add, check or remove a capability.
106  *
107  * @cap: An {} terminated array of capabilities to alter.
108  *
109  * It will attempt to drop or add capability to the effective set. It will
110  * try to detect if this is needed and whether it can or can't be done. If it
111  * clearly can not add a privilege to the effective set then it will return
112  * TCONF. However it may fail for some other reason and return TBROK.
113  *
114  * This only tries to change the effective set. Some tests may need to change
115  * the inheritable and ambient sets, so that child processes retain some
116  * capability.
117  */
118 void tst_cap_action(struct tst_cap *cap);
119 
120 
121 /**
122  * tst_cap_setup() - Add, check or remove a capabilities.
123  *
124  * @cap: An {} terminated array of capabilities to alter.
125  * @action_mask: Decides which actions are done, i.e. only drop caps, add them
126  *               or both.
127  *
128  * Takes a NULL terminated array of structs which describe whether some
129  * capabilities are needed or not and mask that determines subset of the
130  * actions to be performed. Loops over the array and if mask matches the
131  * element action it's passed to tst_cap_action().
132  */
133 void tst_cap_setup(struct tst_cap *cap, enum tst_cap_act action_mask);
134 
135 #endif /* TST_CAPABILITY_H */
136