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