00001 /** 00002 * @file 00003 * Public Interface for querying portcons, netifcons, and nodecons of 00004 * a policy. 00005 * 00006 * @author Jeremy A. Mowery jmowery@tresys.com 00007 * @author Jason Tang jtang@tresys.com 00008 * 00009 * Copyright (C) 2006-2007 Tresys Technology, LLC 00010 * 00011 * This library is free software; you can redistribute it and/or 00012 * modify it under the terms of the GNU Lesser General Public 00013 * License as published by the Free Software Foundation; either 00014 * version 2.1 of the License, or (at your option) any later version. 00015 * 00016 * This library is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00019 * Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License along with this library; if not, write to the Free Software 00023 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00024 */ 00025 00026 #ifndef APOL_NETCON_QUERY_H 00027 #define APOL_NETCON_QUERY_H 00028 00029 #ifdef __cplusplus 00030 extern "C" 00031 { 00032 #endif 00033 00034 #include "policy.h" 00035 #include "vector.h" 00036 #include "context-query.h" 00037 #include <qpol/policy.h> 00038 00039 typedef struct apol_portcon_query apol_portcon_query_t; 00040 typedef struct apol_netifcon_query apol_netifcon_query_t; 00041 typedef struct apol_nodecon_query apol_nodecon_query_t; 00042 00043 /******************** portcon queries ********************/ 00044 00045 /** 00046 * Execute a query against all portcons within the policy. The 00047 * returned portcons will be unordered. 00048 * 00049 * @param p Policy within which to look up portcons. 00050 * @param po Structure containing parameters for query. If this is 00051 * NULL then return all portcons. 00052 * @param v Reference to a vector of qpol_portcon_t. The vector will 00053 * be allocated by this function. The caller must call 00054 * apol_vector_destroy() afterwards. This will be set to NULL upon no 00055 * results or upon error. 00056 * 00057 * @return 0 on success (including none found), negative on error. 00058 */ 00059 extern int apol_portcon_get_by_query(const apol_policy_t * p, const apol_portcon_query_t * po, apol_vector_t ** v); 00060 00061 /** 00062 * Allocate and return a new portcon query structure. All fields are 00063 * initialized, such that running this blank query results in 00064 * returning all portcons within the policy. The caller must call 00065 * apol_portcon_query_destroy() upon the return value afterwards. 00066 * 00067 * @return An initialized portcon query structure, or NULL upon error. 00068 */ 00069 extern apol_portcon_query_t *apol_portcon_query_create(void); 00070 00071 /** 00072 * Deallocate all memory associated with the referenced portcon 00073 * query, and then set it to NULL. This function does nothing if the 00074 * query is already NULL. 00075 * 00076 * @param po Reference to a portcon query structure to destroy. 00077 */ 00078 extern void apol_portcon_query_destroy(apol_portcon_query_t ** po); 00079 00080 /** 00081 * Set a portcon query to return only portcons that use this protocol. 00082 * 00083 * @param p Policy handler, to report errors. 00084 * @param po Portcon query to set. 00085 * @param proto Limit query to only portcons with this protocol, or 00086 * negative to unset this field. 00087 * 00088 * @return Always 0. 00089 */ 00090 extern int apol_portcon_query_set_protocol(const apol_policy_t * p, apol_portcon_query_t * po, int proto); 00091 00092 /** 00093 * Set a portcon query to return only portcons with this as their low 00094 * port. 00095 * 00096 * @param p Policy handler, to report errors. 00097 * @param po Portcon query to set. 00098 * @param low Limit query to only portcons with this low port, or 00099 * negative to unset this field. 00100 * 00101 * @return Always 0. 00102 */ 00103 extern int apol_portcon_query_set_low(const apol_policy_t * p, apol_portcon_query_t * po, int low); 00104 00105 /** 00106 * Set a portcon query to return only portcons with this as their high 00107 * port. 00108 * 00109 * @param p Policy handler, to report errors. 00110 * @param po Portcon query to set. 00111 * @param high Limit query to only portcons with this high port, or 00112 * negative to unset this field. 00113 * 00114 * @return Always 0. 00115 */ 00116 extern int apol_portcon_query_set_high(const apol_policy_t * p, apol_portcon_query_t * po, int high); 00117 00118 /** 00119 * Set a portcon query to return only portcons matching a context. 00120 * This function takes ownership of the context, such that the caller 00121 * must not modify nor destroy it afterwards. 00122 * 00123 * @param p Policy handler, to report errors. 00124 * @param po Portcon query to set. 00125 * @param context Limit query to only portcons matching this context, 00126 * or NULL to unset this field. 00127 * @param range_match Specifies how to match the MLS range within the 00128 * context. This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or 00129 * APOL_QUERY_EXACT. This parameter is ignored if context is NULL. 00130 * 00131 * @return Always returns 0. 00132 */ 00133 extern int apol_portcon_query_set_context(const apol_policy_t * p, 00134 apol_portcon_query_t * po, apol_context_t * context, unsigned int range_match); 00135 00136 /** 00137 * Creates a string containing the textual representation of 00138 * a portcon type. 00139 * @param p Reference to a policy. 00140 * @param portcon Reference to the portcon statement to be rendered. 00141 * 00142 * @return A newly allocated string on success, caller must free; 00143 * NULL on error. 00144 */ 00145 extern char *apol_portcon_render(const apol_policy_t * p, const qpol_portcon_t * portcon); 00146 00147 /******************** netifcon queries ********************/ 00148 00149 /** 00150 * Execute a query against all netifcons within the policy. The 00151 * returned netifcons will be unordered. 00152 * 00153 * @param p Policy within which to look up netifcons. 00154 * @param n Structure containing parameters for query. If this is 00155 * NULL then return all netifcons. 00156 * @param v Reference to a vector of qpol_netifcon_t. The vector will 00157 * be allocated by this function. The caller must call 00158 * apol_vector_destroy() afterwards,. This will be set to NULL upon 00159 * no results or upon error. 00160 * 00161 * @return 0 on success (including none found), negative on error. 00162 */ 00163 extern int apol_netifcon_get_by_query(const apol_policy_t * p, const apol_netifcon_query_t * n, apol_vector_t ** v); 00164 00165 /** 00166 * Allocate and return a new netifcon query structure. All fields are 00167 * initialized, such that running this blank query results in 00168 * returning all netifcons within the policy. The caller must call 00169 * apol_netifcon_query_destroy() upon the return value afterwards. 00170 * 00171 * @return An initialized netifcon query structure, or NULL upon 00172 * error. 00173 */ 00174 extern apol_netifcon_query_t *apol_netifcon_query_create(void); 00175 00176 /** 00177 * Deallocate all memory associated with the referenced netifcon 00178 * query, and then set it to NULL. This function does nothing if the 00179 * query is already NULL. 00180 * 00181 * @param n Reference to a netifcon query structure to destroy. 00182 */ 00183 extern void apol_netifcon_query_destroy(apol_netifcon_query_t ** n); 00184 00185 /** 00186 * Set a netifcon query to return only netifcons that use this device. 00187 * 00188 * @param p Policy handler, to report errors. 00189 * @param n Netifcon query to set. 00190 * @param dev Limit query to only netifcons that use this device, or 00191 * NULL to unset this field. 00192 * 00193 * @return 0 on success, negative on error. 00194 */ 00195 extern int apol_netifcon_query_set_device(const apol_policy_t * p, apol_netifcon_query_t * n, const char *dev); 00196 00197 /** 00198 * Set a netifcon query to return only netifcons matching this context 00199 * for its interface. This function takes ownership of the context, 00200 * such that the caller must not modify nor destroy it afterwards. 00201 * 00202 * @param p Policy handler, to report errors. 00203 * @param n Netifcon query to set. 00204 * @param context Limit query to only netifcon matching this context 00205 * for its interface, or NULL to unset this field. 00206 * @param range_match Specifies how to match the MLS range within the 00207 * context. This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or 00208 * APOL_QUERY_EXACT. This parameter is ignored if context is NULL. 00209 * 00210 * @return Always returns 0. 00211 */ 00212 extern int apol_netifcon_query_set_if_context(const apol_policy_t * p, 00213 apol_netifcon_query_t * n, apol_context_t * context, 00214 unsigned int range_match); 00215 00216 /** 00217 * Set a netifcon query to return only netifcons matching this context 00218 * for its messages. This function takes ownership of the context, 00219 * such that the caller must not modify nor destroy it afterwards. 00220 * 00221 * @param p Policy handler, to report errors. 00222 * @param n Netifcon query to set. 00223 * @param context Limit query to only netifcon matching this context 00224 * for its messages, or NULL to unset this field. 00225 * @param range_match Specifies how to match the MLS range within the 00226 * context. This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or 00227 * APOL_QUERY_EXACT. This parameter is ignored if context is NULL. 00228 * 00229 * @return Always returns 0. 00230 */ 00231 extern int apol_netifcon_query_set_msg_context(const apol_policy_t * p, 00232 apol_netifcon_query_t * n, apol_context_t * context, 00233 unsigned int range_match); 00234 00235 /** 00236 * Creates a string containing the textual representation of 00237 * a netifcon type. 00238 * @param p Reference to a policy. 00239 * @param netifcon Reference to the netifcon statement to be rendered. 00240 * 00241 * @return A newly allocated string on success, caller must free; 00242 * NULL on error. 00243 */ 00244 extern char *apol_netifcon_render(const apol_policy_t * p, const qpol_netifcon_t * netifcon); 00245 00246 /******************** nodecon queries ********************/ 00247 00248 /** 00249 * Execute a query against all nodecons within the policy. The 00250 * returned nodecons will be unordered. 00251 * 00252 * @param p Policy within which to look up nodecons. 00253 * @param n Structure containing parameters for query. If this is 00254 * NULL then return all nodecons. 00255 * @param v Reference to a vector of qpol_nodecon_t. The vector will 00256 * be allocated by this function. The caller must call 00257 * apol_vector_destroy() afterwards. This will be set to NULL upon no 00258 * results or upon error. 00259 * 00260 * @return 0 on success (including none found), negative on error. 00261 */ 00262 extern int apol_nodecon_get_by_query(const apol_policy_t * p, const apol_nodecon_query_t * n, apol_vector_t ** v); 00263 00264 /** 00265 * Allocate and return a new nodecon query structure. All fields are 00266 * initialized, such that running this blank query results in 00267 * returning all nodecons within the policy. The caller must call 00268 * apol_nodecon_query_destroy() upon the return value afterwards. 00269 * 00270 * @return An initialized nodecon query structure, or NULL upon 00271 * error. 00272 */ 00273 extern apol_nodecon_query_t *apol_nodecon_query_create(void); 00274 00275 /** 00276 * Deallocate all memory associated with the referenced nodecon 00277 * query, and then set it to NULL. This function does nothing if the 00278 * query is already NULL. 00279 * 00280 * @param n Reference to a nodecon query structure to destroy. 00281 */ 00282 extern void apol_nodecon_query_destroy(apol_nodecon_query_t ** n); 00283 00284 /** 00285 * Set a nodecon query to return only nodecons with this protocol, 00286 * either IPv4 or IPv6. 00287 * 00288 * @param p Policy handler, to report errors. 00289 * @param n Nodecon query to set. 00290 * @param proto Limit query to only this protocol, either QPOL_IPV4 or 00291 * QPOL_IPV6, or a negative value to unset this field. 00292 * 00293 * @return 0 if protocol was valid, -1 on error. 00294 */ 00295 extern int apol_nodecon_query_set_protocol(const apol_policy_t * p, apol_nodecon_query_t * n, int proto); 00296 00297 /** 00298 * Set a nodecon query to return only nodecons with this address. If 00299 * the protocol is QPOL_IPV4 then only the first element of the 00300 * address array is used, for QPOL_IPV6 all four are used. 00301 * 00302 * @param p Policy handler, to report errors. 00303 * @param n Nodecon query to set. 00304 * @param addr Array of no more than four elements representing the 00305 * address, or NULL to unset this field. This function will make a 00306 * copy of the array. 00307 * @param proto Format of address, either QPOL_IPV4 or QPOL_IPV6. 00308 * This parameter is ignored if addr is NULL. 00309 * 00310 * @return 0 if protocol was valid, -1 on error. 00311 */ 00312 extern int apol_nodecon_query_set_addr(const apol_policy_t * p, apol_nodecon_query_t * n, uint32_t * addr, int proto); 00313 00314 /** 00315 * Set a nodecon query to return only nodecons with this netmask. If 00316 * the protocol is QPOL_IPV4 then only the first element of the mask 00317 * array is used, for QPOL_IPV6 all four are used. 00318 * 00319 * @param p Policy handler, to report errors. 00320 * @param n Nodecon query to set. 00321 * @param mask Array of no more than four elements representing the 00322 * netmask, or NULL to unset this field. This function will make a 00323 * copy of the array. 00324 * @param proto Format of mask, either QPOL_IPV4 or QPOL_IPV6. This 00325 * parameter is ignored if mask is NULL. 00326 * 00327 * @return 0 if protocol was valid, -1 on error. 00328 */ 00329 extern int apol_nodecon_query_set_mask(const apol_policy_t * p, apol_nodecon_query_t * n, uint32_t * mask, int proto); 00330 00331 /** 00332 * Set a nodecon query to return only nodecons matching this context. 00333 * This function takes ownership of the context, such that the caller 00334 * must not modify nor destroy it afterwards. 00335 * 00336 * @param p Policy handler, to report errors. 00337 * @param n Nodecon query to set. 00338 * @param context Limit query to only nodecons matching this context, 00339 * or NULL to unset this field. 00340 * @param range_match Specifies how to match the MLS range within the 00341 * context. This must be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or 00342 * APOL_QUERY_EXACT. This parameter is ignored if context is NULL. 00343 * 00344 * @return Always returns 0. 00345 */ 00346 extern int apol_nodecon_query_set_context(const apol_policy_t * p, 00347 apol_nodecon_query_t * n, apol_context_t * context, unsigned int range_match); 00348 00349 /** 00350 * Creates a string containing the textual representation of 00351 * a nodecon type. 00352 * @param p Reference to a policy. 00353 * @param nodecon Reference to the nodecon statement to be rendered. 00354 * 00355 * @return A newly allocated string on success, caller must free; 00356 * NULL on error. 00357 */ 00358 extern char *apol_nodecon_render(const apol_policy_t * p, const qpol_nodecon_t * nodecon); 00359 00360 #ifdef __cplusplus 00361 } 00362 #endif 00363 00364 #endif /* APOL_NETCON_QUERY_H */
