00001 /** 00002 * @file 00003 * 00004 * Routines to query type enforcement rules of a policy. These are 00005 * type_transition, type_member, and type_change 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_TERULE_QUERY_H 00028 #define APOL_TERULE_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_terule_query apol_terule_query_t; 00040 00041 /** 00042 * Execute a query against all type enforcement rules within the policy. 00043 * 00044 * @param p Policy within which to look up terules. 00045 * @param t Structure containing parameters for query. If this is 00046 * NULL then return all terules. 00047 * @param v Reference to a vector of qpol_terule_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_terule_get_by_query(const apol_policy_t * p, const apol_terule_query_t * t, apol_vector_t ** v); 00055 00056 /** 00057 * Execute a query against all syntactic type enforcement rules within 00058 * the policy. If the policy has line numbers, then the returned list 00059 * will be sorted increasingly by line number. 00060 * 00061 * @param p Policy within which to look up terules. <b>Must be a 00062 * source policy.</b> 00063 * @param t Structure containing parameters for query. If this is 00064 * NULL then return all terules. 00065 * @param v Reference to a vector of qpol_syn_terule_t. The vector 00066 * will be allocated by this function. The caller must call 00067 * apol_vector_destroy() afterwards. This will be set to NULL upon no 00068 * results or upon error. 00069 * 00070 * @return 0 on success (including none found), negative on error. 00071 */ 00072 extern int apol_syn_terule_get_by_query(const apol_policy_t * p, const apol_terule_query_t * t, apol_vector_t ** v); 00073 00074 /** 00075 * Allocate and return a new terule query structure. All fields are 00076 * initialized, such that running this blank query results in 00077 * returning all terules within the policy. The caller must call 00078 * apol_terule_query_destroy() upon the return value afterwards. 00079 * 00080 * @return An initialized terule query structure, or NULL upon error. 00081 */ 00082 extern apol_terule_query_t *apol_terule_query_create(void); 00083 00084 /** 00085 * Deallocate all memory associated with the referenced terule query, 00086 * and then set it to NULL. This function does nothing if the query 00087 * is already NULL. 00088 * 00089 * @param t Reference to a terule query structure to destroy. 00090 */ 00091 extern void apol_terule_query_destroy(apol_terule_query_t ** t); 00092 00093 /** 00094 * Set a terule query to search only certain type enforcement rules 00095 * within the policy. This is a bitmap; use the constants in 00096 * libqpol/terule_query.h (QPOL_RULE_TYPE_TRANS, etc.) to give the 00097 * rule selections. 00098 * 00099 * @param p Policy handler, to report errors. 00100 * @param te TE rule query to set. 00101 * @param rules Bitmap to indicate which rules to search, or 0 to 00102 * search all rules. 00103 * 00104 * @return Always 0. 00105 */ 00106 extern int apol_terule_query_set_rules(const apol_policy_t * p, apol_terule_query_t * t, unsigned int rules); 00107 00108 /** 00109 * Set a terule query to return rules whose source symbol matches 00110 * symbol. Symbol may be a type or attribute; if it is an alias then 00111 * the query will convert it to its primary prior to searching. If 00112 * is_indirect is non-zero then the search will be done indirectly. 00113 * If the symbol is a type, then the query matches rules with one of 00114 * the type's attributes. If the symbol is an attribute, then it 00115 * matches rule with any of the attribute's types. 00116 * 00117 * @param p Policy handler, to report errors. 00118 * @param t TE rule query to set. 00119 * @param symbol Limit query to rules with this symbol as their 00120 * source, or NULL to unset this field. 00121 * @param is_indirect If non-zero, perform indirect matching. 00122 * 00123 * @return 0 on success, negative on error. 00124 */ 00125 extern int apol_terule_query_set_source(const apol_policy_t * p, apol_terule_query_t * t, const char *symbol, 00126 int is_indirect); 00127 00128 /** 00129 * Set an terule query to return rules whose source symbol is matched as a type 00130 * or an attribute. The symbol will match both types and attributes by default. 00131 * @see apol_avrule_query_set_source() to set the symbol to match. 00132 * 00133 * @param p Policy handler, to report errors. 00134 * @param t TE rule query to set. 00135 * @param component Bit-wise or'ed set of APOL_QUERY_SYMBOL_IS_TYPE 00136 * and APOL_QUERY_SYMBOL_IS_ATTRIBUTE indicating the type of component 00137 * to match. 00138 * 00139 * @return 0 on success, negative on error. 00140 */ 00141 extern int apol_terule_query_set_source_component(const apol_policy_t * p, apol_terule_query_t * t, unsigned int component); 00142 00143 /** 00144 * Set a terule query to return rules whose target symbol matches 00145 * symbol. Symbol may be a type or attribute; if it is an alias then 00146 * the query will convert it to its primary prior to searching. If 00147 * is_indirect is non-zero then the search will be done indirectly. 00148 * If the symbol is a type, then the query matches rules with one of 00149 * the type's attributes. If the symbol is an attribute, then it 00150 * matches rule with any of the attribute's types. 00151 * 00152 * @param p Policy handler, to report errors. 00153 * @param t TE rule query to set. 00154 * @param symbol Limit query to rules with this symbol as their 00155 * target, or NULL to unset this field. 00156 * @param is_indirect If non-zero, perform indirect matching. 00157 * 00158 * @return 0 on success, negative on error. 00159 */ 00160 extern int apol_terule_query_set_target(const apol_policy_t * p, apol_terule_query_t * t, const char *symbol, 00161 int is_indirect); 00162 00163 /** 00164 * Set an terule query to return rules whose target symbol is matched as a type 00165 * or an attribute. The symbol will match both types and attributes by default. 00166 * @see apol_avrule_query_set_source() to set the symbol to match. 00167 * 00168 * @param p Policy handler, to report errors. 00169 * @param t TE rule query to set. 00170 * @param component Bit-wise or'ed set of APOL_QUERY_SYMBOL_IS_TYPE 00171 * and APOL_QUERY_SYMBOL_IS_ATTRIBUTE indicating the type of component 00172 * to match. 00173 * 00174 * @return 0 on success, negative on error. 00175 */ 00176 extern int apol_terule_query_set_target_component(const apol_policy_t * p, apol_terule_query_t * t, unsigned int component); 00177 00178 /** 00179 * Set a terule query to return rules with this default type. The 00180 * symbol may be a type or any of its aliases; it may not be an 00181 * attribute. 00182 * 00183 * @param p Policy handler, to report errors. 00184 * @param t TE rule query to set. 00185 * @param type Name of default type to search. 00186 * 00187 * @return 0 on success, negative on error. 00188 */ 00189 extern int apol_terule_query_set_default(const apol_policy_t * p, apol_terule_query_t * t, const char *type); 00190 00191 /** 00192 * Set at terule query to return rules with this object (non-common) 00193 * class. If more than one class are appended to the query, the 00194 * rule's class must be one of those appended. (I.e., the rule's 00195 * class must be a member of the query's classes.) Pass a NULL to 00196 * clear all classes. Note that this performs straight string 00197 * comparison, ignoring the regex flag. 00198 00199 * 00200 * @param p Policy handler, to report errors. 00201 * @param t TE rule query to set. 00202 * @param obj_class Name of object class to add to search set. 00203 * 00204 * @return 0 on success, negative on error. 00205 */ 00206 extern int apol_terule_query_append_class(const apol_policy_t * p, apol_terule_query_t * t, const char *obj_class); 00207 00208 /** 00209 * Set a terule query to return rules that are in conditionals and 00210 * whose conditional uses a particular boolean variable. 00211 * Unconditional rules will not be returned. 00212 * 00213 * @param p Policy handler, to report errors. 00214 * @param t TE rule query to set. 00215 * @param bool_name Name of boolean that conditional must contain. If 00216 * NULL then search all rules. 00217 * 00218 * @return 0 on success, negative on error. 00219 */ 00220 extern int apol_terule_query_set_bool(const apol_policy_t * p, apol_terule_query_t * t, const char *bool_name); 00221 00222 /** 00223 * Set a terule query to search only enabled rules within the policy. 00224 * These include rules that are unconditional and those within enabled 00225 * conditionals. 00226 * 00227 * @param p Policy handler, to report errors. 00228 * @param t TE rule query to set. 00229 * @param is_enabled Non-zero to search only enabled rules, 0 to 00230 * search all rules. 00231 * 00232 * @return Always 0. 00233 */ 00234 extern int apol_terule_query_set_enabled(const apol_policy_t * p, apol_terule_query_t * t, int is_enabled); 00235 00236 /** 00237 * Set a terule query to treat the source symbol as any. That is, use 00238 * the same symbol for either source, target, or default of a rule. 00239 * This flag does nothing if the source symbol is not set. 00240 * 00241 * @param p Policy handler, to report errors. 00242 * @param t TE rule query to set. 00243 * @param is_any Non-zero to use source symbol for any field, 0 to 00244 * keep source as only source. 00245 * 00246 * @return Always 0. 00247 */ 00248 extern int apol_terule_query_set_source_any(const apol_policy_t * p, apol_terule_query_t * t, int is_any); 00249 00250 /** 00251 * Set a terule query to use regular expression searching for source 00252 * and target types/attributes and default type. Strings will be 00253 * treated as regexes instead of literals. Matching will occur against 00254 * the type name or any of its aliases. 00255 * 00256 * @param p Policy handler, to report errors. 00257 * @param t TE rule query to set. 00258 * @param is_regex Non-zero to enable regex searching, 0 to disable. 00259 * 00260 * @return Always 0. 00261 */ 00262 extern int apol_terule_query_set_regex(const apol_policy_t * p, apol_terule_query_t * t, int is_regex); 00263 00264 /** 00265 * Given a single terule, return a newly allocated vector of 00266 * qpol_syn_terule_t pointers (relative to the given policy) which 00267 * comprise that rule. The vector will be sorted by line numbers if 00268 * the policy has line numbers. 00269 * 00270 * @param p Policy from which to obtain syntactic rules. 00271 * @param rule TE rule to convert. 00272 * 00273 * @return A newly allocated vector of syn_terule_t pointers. The 00274 * caller is responsible for calling apol_vector_destroy() afterwards. 00275 */ 00276 extern apol_vector_t *apol_terule_to_syn_terules(const apol_policy_t * p, const qpol_terule_t * rule); 00277 00278 /** 00279 * Given a vector of terules (qpol_terule_t pointers), return a newly 00280 * allocated vector of qpol_syn_terule_t pointers (relative to the 00281 * given policy) which comprise all of those rules. The returned 00282 * vector will be sorted by line numbers if the policy has line 00283 * numbers. Also, it will not have any duplicate syntactic rules. 00284 * 00285 * @param p Policy from which to obtain syntactic rules. 00286 * @param rules Vector of TE rules to convert. 00287 * 00288 * @return A newly allocated vector of syn_terule_t pointers. The 00289 * caller is responsible for calling apol_vector_destroy() afterwards. 00290 */ 00291 extern apol_vector_t *apol_terule_list_to_syn_terules(const apol_policy_t * p, const apol_vector_t * rules); 00292 00293 /** 00294 * Render a terule to a string. 00295 * 00296 * @param policy Policy handler, to report errors. 00297 * @param rule The rule to render. 00298 * 00299 * @return a newly malloc()'d string representation of the rule, or NULL on 00300 * failure; if the call fails, errno will be set. The caller is responsible 00301 * for calling free() on the returned string. 00302 */ 00303 extern char *apol_terule_render(const apol_policy_t * policy, const qpol_terule_t * rule); 00304 00305 /** 00306 * Render a syntactic terule to a string. 00307 * 00308 * @param policy Policy handler to report errors. 00309 * @param rule The rule to render. 00310 * 00311 * @return a newly malloc()'d string representation of the rule, or NULL on 00312 * failure; if the call fails, errno will be set. The caller is responsible 00313 * for calling free() on the returned string. 00314 */ 00315 extern char *apol_syn_terule_render(const apol_policy_t * policy, const qpol_syn_terule_t * rule); 00316 00317 #ifdef __cplusplus 00318 } 00319 #endif 00320 00321 #endif
