00001 /** 00002 * @file 00003 * 00004 * Routines to query access vector rules of a policy. These are 00005 * allow, neverallow, auditallow, and dontaudit rules. 00006 * 00007 * @author Jeremy A. Mowery jmowery@tresys.com 00008 * @author Jason Tang jtang@tresys.com 00009 * 00010 * Copyright (C) 2006-2007 Tresys Technology, LLC 00011 * 00012 * This library is free software; you can redistribute it and/or 00013 * modify it under the terms of the GNU Lesser General Public 00014 * License as published by the Free Software Foundation; either 00015 * version 2.1 of the License, or (at your option) any later version. 00016 * 00017 * This library is distributed in the hope that it will be useful, 00018 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00019 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00020 * Lesser General Public License for more details. 00021 * 00022 * You should have received a copy of the GNU Lesser General Public 00023 * License along with this library; if not, write to the Free Software 00024 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00025 */ 00026 00027 #ifndef APOL_AVRULE_QUERY_H 00028 #define APOL_AVRULE_QUERY_H 00029 00030 #ifdef __cplusplus 00031 extern "C" 00032 { 00033 #endif 00034 00035 #include "policy.h" 00036 #include "vector.h" 00037 #include <qpol/policy.h> 00038 00039 typedef struct apol_avrule_query apol_avrule_query_t; 00040 00041 /** 00042 * Execute a query against all access vector rules within the policy. 00043 * 00044 * @param p Policy within which to look up avrules. 00045 * @param a Structure containing parameters for query. If this is 00046 * NULL then return all avrules. 00047 * @param v Reference to a vector of qpol_avrule_t. The vector will 00048 * be allocated by this function. The caller must call 00049 * apol_vector_destroy() afterwards. This will be set to NULL upon no 00050 * results or upon error. 00051 * 00052 * @return 0 on success (including none found), negative on error. 00053 */ 00054 extern int apol_avrule_get_by_query(const apol_policy_t * p, const apol_avrule_query_t * a, apol_vector_t ** v); 00055 00056 /** 00057 * Execute a query against all syntactic access vector rules within 00058 * the policy. If the policy has line numbers, then the returned list 00059 * 00060 * @param p Policy within which to look up avrules. The policy must 00061 * be capable of having syntactic rules. 00062 * @param a Structure containing parameters for query. If this is 00063 * NULL then return all avrules. 00064 * @param v Reference to a vector of qpol_syn_avrule_t. The vector 00065 * will be allocated by this function. The caller must call 00066 * apol_vector_destroy() afterwards. This will be set to NULL upon no 00067 * results or upon error. 00068 * 00069 * @return 0 on success (including none found), negative on error. 00070 */ 00071 extern int apol_syn_avrule_get_by_query(const apol_policy_t * p, const apol_avrule_query_t * a, apol_vector_t ** v); 00072 00073 /** 00074 * Allocate and return a new avrule query structure. All fields are 00075 * initialized, such that running this blank query results in 00076 * returning all avrules within the policy. The caller must call 00077 * apol_avrule_query_destroy() upon the return value afterwards. 00078 * 00079 * @return An initialized avrule query structure, or NULL upon error. 00080 */ 00081 extern apol_avrule_query_t *apol_avrule_query_create(void); 00082 00083 /** 00084 * Deallocate all memory associated with the referenced avrule query, 00085 * and then set it to NULL. This function does nothing if the query 00086 * is already NULL. 00087 * 00088 * @param a Reference to a avrule query structure to destroy. 00089 */ 00090 extern void apol_avrule_query_destroy(apol_avrule_query_t ** a); 00091 00092 /** 00093 * Set an avrule query to search only certain access vector rules 00094 * within the policy. This is a bitmap; use the constants in 00095 * libqpol/avrule_query.h (QPOL_RULE_ALLOW, etc.) to give the rule 00096 * selections. 00097 * 00098 * @param p Policy handler, to report errors. 00099 * @param a AV rule query to set. 00100 * @param rules Bitmap to indicate which rules to search, or 0 to 00101 * search all rules. 00102 * 00103 * @return Always 0. 00104 */ 00105 extern int apol_avrule_query_set_rules(const apol_policy_t * p, apol_avrule_query_t * a, unsigned int rules); 00106 00107 /** 00108 * Set an avrule query to return rules whose source symbol matches 00109 * symbol. Symbol may be a type or attribute; if it is an alias then 00110 * the query will convert it to its primary prior to searching. If 00111 * is_indirect is non-zero then the search will be done indirectly. 00112 * If the symbol is a type, then the query matches rules with one of 00113 * the type's attributes. If the symbol is an attribute, then it 00114 * matches rule with any of the attribute's types. 00115 * 00116 * @param p Policy handler, to report errors. 00117 * @param a AV rule query to set. 00118 * @param symbol Limit query to rules with this symbol as their 00119 * source, or NULL to unset this field. 00120 * @param is_indirect If non-zero, perform indirect matching. 00121 * 00122 * @return 0 on success, negative on error. 00123 */ 00124 extern int apol_avrule_query_set_source(const apol_policy_t * p, apol_avrule_query_t * a, const char *symbol, 00125 int is_indirect); 00126 00127 /** 00128 * Set an avrule query to return rules whose source symbol is matched as a type 00129 * or an attribute. The symbol will match both types and attributes by default. 00130 * @see apol_avrule_query_set_source() to set the symbol to match. 00131 * 00132 * @param p Policy handler, to report errors. 00133 * @param a AV rule query to set. 00134 * @param component Bit-wise or'ed set of APOL_QUERY_SYMBOL_IS_TYPE 00135 * and APOL_QUERY_SYMBOL_IS_ATTRIBUTE indicating the type of component 00136 * to match. 00137 * 00138 * @return 0 on success, negative on error. 00139 */ 00140 extern int apol_avrule_query_set_source_component(const apol_policy_t * p, apol_avrule_query_t * a, unsigned int component); 00141 00142 /** 00143 * Set an avrule query to return rules whose target symbol matches 00144 * symbol. Symbol may be a type or attribute; if it is an alias then 00145 * the query will convert it to its primary prior to searching. If 00146 * is_indirect is non-zero then the search will be done indirectly. 00147 * If the symbol is a type, then the query matches rules with one of 00148 * the type's attributes. If the symbol is an attribute, then it 00149 * matches rule with any of the attribute's types. 00150 * 00151 * @param p Policy handler, to report errors. 00152 * @param a AV rule query to set. 00153 * @param symbol Limit query to rules with this symbol as their 00154 * target, or NULL to unset this field. 00155 * @param is_indirect If non-zero, perform indirect matching. 00156 * 00157 * @return 0 on success, negative on error. 00158 */ 00159 extern int apol_avrule_query_set_target(const apol_policy_t * p, apol_avrule_query_t * a, const char *symbol, 00160 int is_indirect); 00161 00162 /** 00163 * Set an avrule query to return rules whose target symbol is matched as a type 00164 * or an attribute. The symbol will match both types and attributes by default. 00165 * @see apol_avrule_query_set_target() to set the symbol to match. 00166 * 00167 * @param p Policy handler, to report errors. 00168 * @param a AV rule query to set. 00169 * @param component Bit-wise or'ed set of APOL_QUERY_SYMBOL_IS_TYPE 00170 * and APOL_QUERY_SYMBOL_IS_ATTRIBUTE indicating the type of component 00171 * to match. 00172 * 00173 * @return 0 on success, negative on error. 00174 */ 00175 extern int apol_avrule_query_set_target_component(const apol_policy_t * p, apol_avrule_query_t * a, unsigned int component); 00176 00177 /** 00178 * Set an avrule query to return rules with this object (non-common) 00179 * class. If more than one class are appended to the query, the 00180 * rule's class must be one of those appended. (I.e., the rule's 00181 * class must be a member of the query's classes.) Pass a NULL to 00182 * clear all classes. Note that this performs straight string 00183 * comparison, ignoring the regex flag. 00184 * 00185 * @param p Policy handler, to report errors. 00186 * @param a AV rule query to set. 00187 * @param obj_class Name of object class to add to search set, or NULL 00188 * to clear all classes. 00189 * 00190 * @return 0 on success, negative on error. 00191 */ 00192 extern int apol_avrule_query_append_class(const apol_policy_t * p, apol_avrule_query_t * a, const char *obj_class); 00193 00194 /** 00195 * Set an avrule query to return rules with this permission. By 00196 * default, if more than one permission are appended to the query, at 00197 * least one of the rule's permissions must be one of those appended; 00198 * that is, the intersection of query's and rule's permissions must be 00199 * non-empty. (This behavior can be changed.) Pass a NULL to clear 00200 * all permissions. Note that this performs a straight string 00201 * comparison, ignoring the regex flag. 00202 * 00203 * @param p Policy handler, to report errors. 00204 * @param a AV rule query to set. 00205 * @param perm Name of permission to add to search set, or NULL to 00206 * clear all permissions. 00207 * 00208 * @return 0 on success, negative on error. 00209 * 00210 * @see apol_avrule_query_set_all_perms() 00211 */ 00212 extern int apol_avrule_query_append_perm(const apol_policy_t * p, apol_avrule_query_t * a, const char *perm); 00213 00214 /** 00215 * Set an avrule query to return rules that are in conditionals and 00216 * whose conditional uses a particular boolean variable. 00217 * Unconditional rules will not be returned. 00218 * 00219 * @param p Policy handler, to report errors. 00220 * @param a AV rule query to set. 00221 * @param bool_name Name of boolean that conditional must contain. If 00222 * NULL then search all rules. 00223 * 00224 * @return 0 on success, negative on error. 00225 */ 00226 extern int apol_avrule_query_set_bool(const apol_policy_t * p, apol_avrule_query_t * a, const char *bool_name); 00227 00228 /** 00229 * Set an avrule query to search only enabled rules within the policy. 00230 * These include rules that are unconditional and those within enabled 00231 * conditionals. 00232 * 00233 * @param p Policy handler, to report errors. 00234 * @param a AV rule query to set. 00235 * @param is_enabled Non-zero to search only enabled rules, 0 to 00236 * search all rules. 00237 * 00238 * @return Always 0. 00239 */ 00240 extern int apol_avrule_query_set_enabled(const apol_policy_t * p, apol_avrule_query_t * a, int is_enabled); 00241 00242 /** 00243 * Normally, if more than one permission are added to the query then 00244 * all returned rules will have <em>at least one</em> of those 00245 * permissions. If the all_perms flag is set, then returned rules 00246 * will have <em>all</em> of the given permissions. This flag does 00247 * nothing if no permissions are given. 00248 * 00249 * <em>Note:</em> If calling apol_syn_avrule_get_by_query(), the 00250 * returned results may not be what is expected. For a given 00251 * source-target-class triplet, all of the associated permissions are 00252 * unioned together prior to executing the avrule query. Although a 00253 * given syntactic AV rule might not have all of the matched 00254 * permissions, the union of the rules' permissions will them. For 00255 * example, consider these two allow rules: 00256 * 00257 *<pre>allow A B : C p1; 00258 *allow A B : C p2;</pre> 00259 * 00260 * If the avrule query has both permissions p1 and p2 and the 00261 * all_perms flag is set, then both of these syntactic rules will be 00262 * returned by apol_syn_avrule_get_by_query(). 00263 * 00264 * @param p Policy handler, to report errors. 00265 * @param a AV rule query to set. 00266 * @param all_perms Non-zero to match all permissions, zero to match 00267 * any permission. 00268 * 00269 * @return Always 0. 00270 * 00271 * @see apol_avrule_query_append_perm() 00272 */ 00273 extern int apol_avrule_query_set_all_perms(const apol_policy_t * p, apol_avrule_query_t * a, int all_perms); 00274 00275 /** 00276 * Set an avrule query to treat the source symbol as any. That is, 00277 * use the same symbol for either source or target of a rule. This 00278 * flag does nothing if the source symbol is not set. 00279 * 00280 * @param p Policy handler, to report errors. 00281 * @param a AV rule query to set. 00282 * @param is_any Non-zero to use source symbol for any field, 0 to 00283 * keep source as only source. 00284 * 00285 * @return Always 0. 00286 */ 00287 extern int apol_avrule_query_set_source_any(const apol_policy_t * p, apol_avrule_query_t * a, int is_any); 00288 00289 /** 00290 * Set an avrule query to use regular expression searching for source 00291 * and target types/attributes. Strings will be treated as regexes 00292 * instead of literals. Matching will occur against the type name or 00293 * any of its aliases. 00294 * 00295 * @param p Policy handler, to report errors. 00296 * @param a AV rule query to set. 00297 * @param is_regex Non-zero to enable regex searching, 0 to disable. 00298 * 00299 * @return Always 0. 00300 */ 00301 extern int apol_avrule_query_set_regex(const apol_policy_t * p, apol_avrule_query_t * a, int is_regex); 00302 00303 /** 00304 * Given a single avrule, return a newly allocated vector of 00305 * qpol_syn_avrule_t pointers (relative to the given policy) which 00306 * comprise that rule. The vector will be sorted by line numbers if 00307 * the policy has line numbers. If the given perms vector is non-NULL 00308 * and non-empty, then only return syntactic rules with at least one 00309 * permission listed within the perms vector. 00310 * 00311 * @param p Policy from which to obtain syntactic rules. 00312 * @param rule AV rule to convert. 00313 * @param perms If non-NULL and non-empty, a list of permission 00314 * strings. Returned syn avrules will have at least one permission in 00315 * common with this list. 00316 * 00317 * @return A newly allocated vector of syn_avrule_t pointers. The 00318 * caller is responsible for calling apol_vector_destroy() afterwards. 00319 */ 00320 extern apol_vector_t *apol_avrule_to_syn_avrules(const apol_policy_t * p, const qpol_avrule_t * rule, 00321 const apol_vector_t * perms); 00322 00323 /** 00324 * Given a vector of avrules (qpol_avrule_t pointers), return a newly 00325 * allocated vector of qpol_syn_avrule_t pointers (relative to the 00326 * given policy) which comprise all of those rules. The returned 00327 * vector will be sorted by line numbers if the policy has line 00328 * numbers. Also, it will not have any duplicate syntactic rules. If 00329 * the given perms vector is non-NULL and non-empty, then only return 00330 * syntactic rules with at least one permission listed within the 00331 * perms vector. 00332 * 00333 * @param p Policy from which to obtain syntactic rules. 00334 * @param rules Vector of AV rules to convert. 00335 * @param perms If non-NULL and non-empty, a list of permission 00336 * strings. Returned syn avrules will have at least one permission in 00337 * common with this list. 00338 * 00339 * @return A newly allocated vector of syn_avrule_t pointers. The 00340 * caller is responsible for calling apol_vector_destroy() afterwards. 00341 */ 00342 extern apol_vector_t *apol_avrule_list_to_syn_avrules(const apol_policy_t * p, const apol_vector_t * rules, 00343 const apol_vector_t * perms); 00344 00345 /** 00346 * Render an avrule to a string. 00347 * 00348 * @param policy Policy handler, to report errors. 00349 * @param rule The rule to render. 00350 * 00351 * @return a newly malloc()'d string representation of the rule, or NULL on 00352 * failure; if the call fails, errno will be set. The caller is responsible 00353 * for calling free() on the returned string. 00354 */ 00355 extern char *apol_avrule_render(const apol_policy_t * policy, const qpol_avrule_t * rule); 00356 00357 /** 00358 * Render a syntactic avrule to a string. 00359 * 00360 * @param policy Policy handler to report errors. 00361 * @param rule The rule to render. 00362 * 00363 * @return a newly malloc()'d string representation of the rule, or NULL on 00364 * failure; if the call fails, errno will be set. The caller is responsible 00365 * for calling free() on the returned string. 00366 */ 00367 extern char *apol_syn_avrule_render(const apol_policy_t * policy, const qpol_syn_avrule_t * rule); 00368 00369 #ifdef __cplusplus 00370 } 00371 #endif 00372 00373 #endif
