00001 /** 00002 * @file 00003 * Public interface for computing semantic policy differences 00004 * between two policies. The user loads two policies, the "original" 00005 * and "modified" policies, and then calls poldiff_create() to obtain 00006 * a poldiff object. Next call poldiff_run() to actually execute the 00007 * differencing algorithm. Results are retrieved via 00008 * poldiff_get_type_vector(), poldiff_get_avrule_vector(), and so 00009 * forth. 00010 * 00011 * @author Jeremy A. Mowery jmowery@tresys.com 00012 * @author Jason Tang jtang@tresys.com 00013 * 00014 * Copyright (C) 2006-2007 Tresys Technology, LLC 00015 * 00016 * This library is free software; you can redistribute it and/or 00017 * modify it under the terms of the GNU Lesser General Public 00018 * License as published by the Free Software Foundation; either 00019 * version 2.1 of the License, or (at your option) any later version. 00020 * 00021 * This library is distributed in the hope that it will be useful, 00022 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00024 * Lesser General Public License for more details. 00025 * 00026 * You should have received a copy of the GNU Lesser General Public 00027 * License along with this library; if not, write to the Free Software 00028 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00029 */ 00030 00031 #ifndef POLDIFF_POLDIFF_H 00032 #define POLDIFF_POLDIFF_H 00033 00034 #ifdef __cplusplus 00035 extern "C" 00036 { 00037 #endif 00038 00039 #include <apol/policy.h> 00040 #include <apol/policy-query.h> 00041 #include <apol/vector.h> 00042 #include <stdarg.h> 00043 #include <stdint.h> 00044 00045 typedef struct poldiff poldiff_t; 00046 00047 /** 00048 * Form of a difference. This enumeration describes the kind of change 00049 * in a policy component or rule from policy1 to policy2. 00050 * Differences can be additions (item present only in policy2), 00051 * removals (item present only in policy1) or a modification 00052 * (item present in both policies with different semantic meaning). 00053 * For rules there are two more options - added or removed due to a 00054 * type being added or removed; these forms differentiate these cases 00055 * from those of added/removed rules where the types exist in both policies. 00056 */ 00057 typedef enum poldiff_form 00058 { 00059 /** only for error conditions */ 00060 POLDIFF_FORM_NONE, 00061 /** item was added - only in policy 2 */ 00062 POLDIFF_FORM_ADDED, 00063 /** item was removed - only in policy 1 */ 00064 POLDIFF_FORM_REMOVED, 00065 /** item was modified - in both policies but with different meaning */ 00066 POLDIFF_FORM_MODIFIED, 00067 /** item was added due to an added type - for rules only */ 00068 POLDIFF_FORM_ADD_TYPE, 00069 /** item was removed due to a removed type - for rules only */ 00070 POLDIFF_FORM_REMOVE_TYPE 00071 } poldiff_form_e; 00072 00073 typedef void (*poldiff_handle_fn_t) (void *arg, const poldiff_t * diff, int level, const char *fmt, va_list va_args); 00074 00075 #include <poldiff/attrib_diff.h> 00076 #include <poldiff/avrule_diff.h> 00077 #include <poldiff/cat_diff.h> 00078 #include <poldiff/bool_diff.h> 00079 #include <poldiff/class_diff.h> 00080 #include <poldiff/level_diff.h> 00081 #include <poldiff/range_diff.h> 00082 #include <poldiff/range_trans_diff.h> 00083 #include <poldiff/rbac_diff.h> 00084 #include <poldiff/role_diff.h> 00085 #include <poldiff/terule_diff.h> 00086 #include <poldiff/type_diff.h> 00087 #include <poldiff/user_diff.h> 00088 #include <poldiff/type_map.h> 00089 #include <poldiff/util.h> 00090 00091 /* NOTE: while defined OCONS are not currently supported */ 00092 #define POLDIFF_DIFF_CLASSES 0x00000001U 00093 #define POLDIFF_DIFF_COMMONS 0x00000002U 00094 #define POLDIFF_DIFF_TYPES 0x00000004U 00095 #define POLDIFF_DIFF_ATTRIBS 0x00000008U 00096 #define POLDIFF_DIFF_ROLES 0x00000010U 00097 #define POLDIFF_DIFF_USERS 0x00000020U 00098 #define POLDIFF_DIFF_BOOLS 0x00000040U 00099 #define POLDIFF_DIFF_LEVELS 0x00000080U 00100 #define POLDIFF_DIFF_CATS 0x00000100U 00101 #define POLDIFF_DIFF_ROLE_ALLOWS 0x00000800U 00102 #define POLDIFF_DIFF_ROLE_TRANS 0x00001000U 00103 #define POLDIFF_DIFF_RANGE_TRANS 0x00002000U 00104 #define POLDIFF_DIFF_AVALLOW 0x10000000U 00105 #define POLDIFF_DIFF_AVAUDITALLOW 0x20000000U 00106 #define POLDIFF_DIFF_AVDONTAUDIT 0x40000000U 00107 #define POLDIFF_DIFF_AVNEVERALLOW 0x80000000U 00108 #define POLDIFF_DIFF_TECHANGE 0x01000000U 00109 #define POLDIFF_DIFF_TEMEMBER 0x02000000U 00110 #define POLDIFF_DIFF_TETRANS 0x04000000U 00111 00112 #define POLDIFF_DIFF_TERULES_COMPAT 0x00000400U /**< deprecated */ 00113 #define POLDIFF_DIFF_AVRULES_COMPAT 0x00000200U /**< deprecated */ 00114 00115 #define POLDIFF_DIFF_AVRULES (POLDIFF_DIFF_AVALLOW | POLDIFF_DIFF_AVNEVERALLOW | POLDIFF_DIFF_AVAUDITALLOW | POLDIFF_DIFF_AVDONTAUDIT) 00116 #define POLDIFF_DIFF_TERULES (POLDIFF_DIFF_TEMEMBER | POLDIFF_DIFF_TECHANGE | POLDIFF_DIFF_TETRANS) 00117 /* 00118 * Add ocons here and modify POLDIFF_DIFF_OCONS below 00119 * #define POLDIFF_DIFF_ * 00120 */ 00121 #define POLDIFF_DIFF_SYMBOLS (POLDIFF_DIFF_CLASSES|POLDIFF_DIFF_COMMONS|POLDIFF_DIFF_TYPES|POLDIFF_DIFF_ATTRIBS|POLDIFF_DIFF_ROLES|POLDIFF_DIFF_USERS|POLDIFF_DIFF_BOOLS) 00122 #define POLDIFF_DIFF_RULES (POLDIFF_DIFF_AVRULES|POLDIFF_DIFF_TERULES|POLDIFF_DIFF_ROLE_ALLOWS|POLDIFF_DIFF_ROLE_TRANS) 00123 #define POLDIFF_DIFF_RBAC (POLDIFF_DIFF_ROLES|POLDIFF_DIFF_ROLE_ALLOWS|POLDIFF_DIFF_ROLE_TRANS) 00124 #define POLDIFF_DIFF_MLS (POLDIFF_DIFF_LEVELS|POLDIFF_DIFF_CATS|POLDIFF_DIFF_RANGE_TRANS) 00125 #define POLDIFF_DIFF_OCONS 0 00126 #define POLDIFF_DIFF_REMAPPED (POLDIFF_DIFF_TYPES|POLDIFF_DIFF_ATTRIBS|POLDIFF_DIFF_AVRULES|POLDIFF_DIFF_TERULES|POLDIFF_DIFF_ROLES|POLDIFF_DIFF_ROLE_TRANS|POLDIFF_DIFF_RANGE_TRANS|POLDIFF_DIFF_OCONS) 00127 #define POLDIFF_DIFF_ALL (POLDIFF_DIFF_SYMBOLS|POLDIFF_DIFF_RULES|POLDIFF_DIFF_MLS|POLDIFF_DIFF_OCONS) 00128 00129 /** 00130 * Allocate and initialize a new policy difference structure. This 00131 * function takes ownership of the supplied policies and will handle 00132 * their destruction upon poldiff_destroy(). The poldiff object will 00133 * be responsible for rebuilding the policy (such as if neverallows 00134 * are requested). It is still safe to access elements within the 00135 * policies, but avoid making changes to the policy while the poldiff 00136 * object still exists. 00137 * @param orig_policy The original policy. 00138 * @param mod_policy The new (modified) policy. 00139 * @param fn Function to be called by the error handler. If NULL 00140 * then write messages to standard error. 00141 * @param callback_arg Argument for the callback. 00142 * @return a newly allocated and initialized difference structure or 00143 * NULL on error; if the call fails, errno will be set. 00144 * The caller is responsible for calling poldiff_destroy() to free 00145 * memory used by this structure. 00146 */ 00147 extern poldiff_t *poldiff_create(apol_policy_t * orig_policy, 00148 apol_policy_t * mod_policy, poldiff_handle_fn_t fn, void *callback_arg); 00149 00150 /** 00151 * Free all memory used by a policy difference structure and set it to NULL. 00152 * @param diff Reference pointer to the difference structure to destroy. 00153 * This pointer will be set to NULL. (If already NULL, function is a no-op.) 00154 */ 00155 extern void poldiff_destroy(poldiff_t ** diff); 00156 00157 /** 00158 * Run the difference algorithm for the selected policy components/rules. 00159 * @param diff The policy difference structure for which to compute 00160 * the differences. 00161 * @param flags Bit-wise or'd set of POLDIFF_DIFF_* from above indicating 00162 * the components and rules for which to compute the difference. 00163 * If an item has already been computed the flag for that item is ignored. 00164 * @return 0 on success or < 0 on error; if the call fails, errno will 00165 * be set and the only defined operation on the difference structure is 00166 * poldiff_destroy(). 00167 */ 00168 extern int poldiff_run(poldiff_t * diff, uint32_t flags); 00169 00170 /** 00171 * Determine if a particular policy component/rule diff was actually 00172 * run yet or not. 00173 * @param diff The policy difference structure for which to compute 00174 * the differences. 00175 * @param flags Bit-wise or'd set of POLDIFF_DIFF_* from above indicating 00176 * which components/rules diffs were run. 00177 * @return 1 if all indicated diffs were run, 0 if any were not, < 0 00178 * on error. 00179 */ 00180 extern int poldiff_is_run(const poldiff_t * diff, uint32_t flags); 00181 00182 /** 00183 * Get a total of the differences of each form for a given item (or set 00184 * of items). 00185 * @param diff The policy difference structure from which to get the stats. 00186 * @param flags Bit-wise or'd set of POLDIFF_DIFF_* from above indicating 00187 * the items for which to get the total differences. If more that one bit 00188 * is set differences of the same form are totaled for all specified items. 00189 * @param stats Array into which to write the numbers (array must be 00190 * pre-allocated). The order of the values written to the array is as follows: 00191 * number of items of form POLDIFF_FORM_ADDED, number of POLDIFF_FORM_REMOVED, 00192 * number of POLDIFF_FORM_MODIFIED, number of form POLDIFF_FORM_ADD_TYPE, and 00193 * number of POLDIFF_FORM_REMOVE_TYPE. 00194 * @return 0 on success and < 0 on error; if the call fails, errno will be set. 00195 */ 00196 extern int poldiff_get_stats(const poldiff_t * diff, uint32_t flags, size_t stats[5]); 00197 00198 /** 00199 * Enable line numbers for all rule differences. If not called, line 00200 * numbers will not be available when displaying differences. This 00201 * function is safe to call multiple times and will have no effect 00202 * after the first time. It also has no effect if one policy (or 00203 * both of them) does not support line numbers. Be aware that line 00204 * numbers will need to be re-enabled each time poldiff_run() is 00205 * called. 00206 * 00207 * @param diff The policy difference structure. 00208 * 00209 * @return 0 on success and < 0 on failure; if the call fails, 00210 * errno will be set and the difference structure should be destroyed. 00211 */ 00212 extern int poldiff_enable_line_numbers(poldiff_t * diff); 00213 00214 #ifdef __cplusplus 00215 } 00216 #endif 00217 00218 #endif /* POLDIFF_POLDIFF_H */
