Create setools-3.3.7 git repomaster

1 files changed, 387 insertions, 0 deletions

diff --git a/libapol/include/apol/infoflow-analysis.h b/libapol/include/apol/infoflow-analysis.h
new file mode 100644
index 0000000..61b00a9
--- /dev/null
+++ b/libapol/include/apol/infoflow-analysis.h
@@ -0,0 +1,387 @@
+/**
+ * @file
+ *
+ * Routines to perform an information flow analysis, both direct and
+ * transitive flows.
+ *
+ * @author Jeremy A. Mowery jmowery@tresys.com
+ * @author Jason Tang  jtang@tresys.com
+ *
+ * Copyright (C) 2003-2007 Tresys Technology, LLC
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+#ifndef APOL_INFOFLOW_ANALYSIS_H
+#define APOL_INFOFLOW_ANALYSIS_H
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+#include "policy.h"
+#include "vector.h"
+#include <qpol/policy.h>
+
+/*
+ * Information flows can be either direct (A -> B) or transitive (A ->
+ * {stuff} -> B).
+ */
+#define APOL_INFOFLOW_MODE_DIRECT  0x01
+#define APOL_INFOFLOW_MODE_TRANS   0x02
+
+/*
+ * All operations are mapped in either an information flow in or an
+ * information flow out (using the permission map).  These defines are
+ * for the two flow directions plus flows in both or either direction
+ * for queries and query results.
+ */
+#define APOL_INFOFLOW_IN      0x01
+#define APOL_INFOFLOW_OUT     0x02
+#define APOL_INFOFLOW_BOTH    (APOL_INFOFLOW_IN|APOL_INFOFLOW_OUT)
+#define APOL_INFOFLOW_EITHER  0x04
+
+	typedef struct apol_infoflow_graph apol_infoflow_graph_t;
+	typedef struct apol_infoflow_analysis apol_infoflow_analysis_t;
+	typedef struct apol_infoflow_result apol_infoflow_result_t;
+	typedef struct apol_infoflow_step apol_infoflow_step_t;
+
+/**
+ * Deallocate all space associated with a particular information flow
+ * graph, including the pointer itself.  Afterwards set the pointer to
+ * NULL.
+ *
+ * @param g Reference to an apol_infoflow_graph_t to destroy.
+ */
+	extern void apol_infoflow_graph_destroy(apol_infoflow_graph_t ** g);
+
+/********** functions to do information flow analysis **********/
+
+/**
+ * Execute an information flow analysis against a particular policy.
+ * The policy must have had a permission map loaded via
+ * apol_policy_open_permmap(), else this analysis will abort
+ * immediately.
+ *
+ * @param p Policy within which to look up allow rules.
+ * @param ia A non-NULL structure containing parameters for analysis.
+ * @param v Reference to a vector of apol_infoflow_result_t.  The
+ * vector will be allocated by this function.  The caller must call
+ * apol_vector_destroy() afterwards.  This will be set to NULL upon
+ * error.
+ * @param g Reference to the information flow graph constructed for
+ * the given infoflow analysis object.  The graph will be allocated by
+ * this function; the caller is responsible for calling
+ * apol_infoflow_graph_destroy() afterwards.  This will be set to NULL
+ * upon error.
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_do(const apol_policy_t * p,
+					     const apol_infoflow_analysis_t * ia, apol_vector_t ** v, apol_infoflow_graph_t ** g);
+
+/**
+ * Execute an information flow analysis against a particular policy
+ * and a pre-built information flow graph.  The analysis will keep the
+ * same criteria that were used to build the graph, sans differing
+ * starting type.
+ *
+ * @param p Policy within which to look up allow rules.
+ * @param g Existing information flow graph to analyze.
+ * @param type New string from which to begin analysis.
+ * @param v Reference to a vector of apol_infoflow_result_t.  The
+ * vector will be allocated by this function.  The caller must call
+ * apol_vector_destroy() afterwards.  This will be set to NULL upon no
+ * results or upon error.
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_do_more(const apol_policy_t * p, apol_infoflow_graph_t * g, const char *type,
+						  apol_vector_t ** v);
+
+/**
+ * Prepare an existing transitive infoflow graph to do further
+ * searches upon two specific start and end types.  The analysis is by
+ * way of a BFS with random restarts; thus each call to
+ * apol_infoflow_analysis_trans_further_next() may possibly return
+ * additional paths.  This function is needed to prepare the pool of
+ * initial states for the search.
+ *
+ * @param p Policy from which infoflow rules derived.
+ * @param g Existing transitive infoflow graph.  If it was already
+ * prepared then those values will be first destroyed.
+ * @param start_type String from which to begin further analysis.
+ * @param end_type String for target infoflow paths.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_infoflow_analysis_trans_further_prepare(const apol_policy_t * p,
+								apol_infoflow_graph_t * g, const char *start_type,
+								const char *end_type);
+
+/**
+ * Find further transitive infoflow paths by way of a random restart.
+ * The infoflow graph must be first prepared by first calling
+ * apol_infoflow_analysis_trans_further_prepare().  This function will
+ * append to vector v any new results it finds.
+ *
+ * @param p Policy from which infoflow rules derived.
+ * @param g Prepared transitive infoflow graph.
+ * @param v Pointer to a vector of existing apol_infoflow_result_t
+ * pointers.  If this functions finds additional unique results it
+ * will append them to this vector.  If the pointer is NULL then this
+ * will allocate and return a new vector.  It is the caller's
+ * responsibility to call apol_vector_destroy() afterwards.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_infoflow_analysis_trans_further_next(const apol_policy_t * p, apol_infoflow_graph_t * g,
+							     apol_vector_t ** v);
+
+/********** functions to create/modify an analysis object **********/
+
+/**
+ * Allocate and return a new information analysis structure.  All
+ * fields are cleared; one must fill in the details of the analysis
+ * before running it.  The caller must call
+ * apol_infoflow_analysis_destroy() upon the return value afterwards.
+ *
+ * @return An initialized information flow analysis structure, or NULL
+ * upon error.
+ */
+	extern apol_infoflow_analysis_t *apol_infoflow_analysis_create(void);
+
+/**
+ * Deallocate all memory associated with the referenced information
+ * flow analysis, and then set it to NULL.  This function does nothing
+ * if the analysis is already NULL.
+ *
+ * @param ia Reference to an infoflow analysis structure to destroy.
+ */
+	extern void apol_infoflow_analysis_destroy(apol_infoflow_analysis_t ** ia);
+
+/**
+ * Set an information flow analysis mode to be either direct or
+ * transitive.  This must be one of the values
+ * APOL_INFOFLOW_MODE_DIRECT, or APOL_INFOFLOW_MODE_TRANS.  This
+ * function must be called prior to running the analysis.
+ *
+ * @param p Policy handler, to report errors.
+ * @param ia Infoflow analysis to set.
+ * @param mode Analysis mode, either direct or transitive.
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_set_mode(const apol_policy_t * p, apol_infoflow_analysis_t * ia, unsigned int mode);
+
+/**
+ * Set an information flow analysis to search in a specific direction.
+ * For direct infoflow analysis this must be one of the values
+ * APOL_INFOFLOW_IN, APOL_INFOFLOW_OUT, APOL_INFOFLOW_BOTH, or
+ * APOL_INFOFLOW_EITHER; transitive infoflow only permits the first
+ * two.  This function must be called prior to running the analysis.
+ *
+ * @param p Policy handler, to report errors.
+ * @param ia Infoflow analysis to set.
+ * @param dir Direction to analyze, using one of the defines above.
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_set_dir(const apol_policy_t * p, apol_infoflow_analysis_t * ia, unsigned int dir);
+
+/**
+ * Set an information flow analysis to begin searching using a given
+ * type.  This function must be called prior to running the analysis.
+ *
+ * @param p Policy handler, to report errors.
+ * @param ia Infoflow anlysis to set.
+ * @param name Begin searching types with this non-NULL name.
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_set_type(const apol_policy_t * p, apol_infoflow_analysis_t * ia, const char *name);
+
+/**
+ * Set an information flow analysis to return paths that only go
+ * through this intermediate type.  If more than one type is appended
+ * to the analysis, every step of a return path will go through at
+ * least one of the types.  These intermediate types are ignored when
+ * running a direct information flow analysis.
+ *
+ * @param policy Policy handler, to report errors.
+ * @param ia Infoflow analysis to set.
+ * @param type Intermediate type which a result must flow through.  If
+ * NULL, then clear all existing intermediate types.  (All paths will
+ * be returned.)
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_append_intermediate(const apol_policy_t * p, apol_infoflow_analysis_t * ia,
+							      const char *type);
+
+/**
+ * Set an information flow analysis to return only rules with this
+ * object (non-common) class and permission.  If more than one
+ * class/perm pair is appended to the query, every rule's class and
+ * permissions must be one of those appended.  (I.e., the rule will be
+ * a member of the analysis's class/perm pairs.)
+ *
+ * @param policy Policy handler, to report errors.
+ * @param ia Infoflow analysis to set.
+ * @param class_name The class to which a result must have access.  If
+ * NULL, then accept all class/perm pairs.
+ * @param perm_name The permission which a result must have for the
+ * given class.  This may be NULL if class_name is also NULL.
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_append_class_perm(const apol_policy_t * p,
+							    apol_infoflow_analysis_t * ia, const char *class_name,
+							    const char *perm_name);
+
+/**
+ * Set an information flow analysis to return only rules with at least
+ * one permission whose weight is greater than or equal to the given
+ * minimum.  Permission weights are retrieved from the currently
+ * loaded permission map.  If the given minimum exceeds
+ * APOL_PERMMAP_MAX_WEIGHT it will be clamped to that value.
+ *
+ * @param policy Policy handler, to report errors.
+ * @param ia Infoflow analysis to set.
+ * @param min_weight Minimum weight for rules, or negative to accept
+ * all rules.
+ * @return Always 0.
+ */
+	extern int apol_infoflow_analysis_set_min_weight(const apol_policy_t * p, apol_infoflow_analysis_t * ia, int min_weight);
+
+/**
+ * Set an information flow analysis to return only types matching a
+ * regular expression.  Note that the regexp will also match types'
+ * aliases.
+ *
+ * @param p Policy handler, to report errors.
+ * @param ia Information flow anlysis to set.
+ * @param result Only return types matching this regular expression, or
+ * NULL to return all types
+ *
+ * @return 0 on success, negative on error.
+ */
+	extern int apol_infoflow_analysis_set_result_regex(const apol_policy_t * p, apol_infoflow_analysis_t * ia,
+							   const char *result);
+
+/*************** functions to access infoflow results ***************/
+
+/**
+ * Return the direction of an information flow result.  This will be
+ * one of APOL_INFOFLOW_IN, APOL_INFOFLOW_OUT, or APOL_INFOFLOW_BOTH.
+ *
+ * @param result Infoflow result from which to get direction.
+ * @return Direction of result or zero on error.
+ */
+	extern unsigned int apol_infoflow_result_get_dir(const apol_infoflow_result_t * result);
+
+/**
+ * Return the start type of an information flow result.  The caller
+ * should not free the returned pointer.
+ *
+ * @param result Infoflow result from which to get start type.
+ * @return Pointer to the start type of the infoflow or NULL on error.
+ */
+	extern const qpol_type_t *apol_infoflow_result_get_start_type(const apol_infoflow_result_t * result);
+
+/**
+ * Return the end type of an information flow result.  The caller
+ * should not free the returned pointer.
+ *
+ * @param result Infoflow result from which to get end type.
+ * @return Pointer to the end type of the infoflow or NULL on error.
+ */
+	extern const qpol_type_t *apol_infoflow_result_get_end_type(const apol_infoflow_result_t * result);
+
+/**
+ * Return the length of an information flow result.  This represents
+ * how easily information flows from the start to end type, where
+ * lower numbers are easier than higher numbers.  This is dependent
+ * upon the weights assigned in the currently loaded permission map.
+ *
+ * @param result Infoflow result from which to get length.
+ * @return Length of result or zero on error.
+ */
+	extern unsigned int apol_infoflow_result_get_length(const apol_infoflow_result_t * result);
+
+/**
+ * Return the vector of infoflow steps for a particular information
+ * flow result.  This is a vector of apol_infoflow_step_t pointers.
+ * The caller <b>should not</b> call apol_vector_destroy() upon the
+ * returned vector.  Note that for a direct infoflow analysis this
+ * vector will consist of exactly one step; for transitive analysis
+ * the vector will have multiple steps.
+ *
+ * @param result Infoflow result from which to get steps.
+ *
+ * @return Pointer to a vector of steps found between the result's
+ * start and end types or NULL on error.
+ */
+	extern const apol_vector_t *apol_infoflow_result_get_steps(const apol_infoflow_result_t * result);
+
+/**
+ * Return the starting type for an information flow step.  The caller
+ * should not free the returned pointer.
+ *
+ * @param step Infoflow step from which to get start type.
+ * @return Pointer to the start type for this infoflow step or NULL on error.
+ */
+	extern const qpol_type_t *apol_infoflow_step_get_start_type(const apol_infoflow_step_t * step);
+
+/**
+ * Return the ending type for an information flow step.  The caller
+ * should not free the returned pointer.
+ *
+ * @param step Infoflow step from which to get end type.
+ * @return Pointer to the start type for this infoflow step or NULL on error.
+ */
+	extern const qpol_type_t *apol_infoflow_step_get_end_type(const apol_infoflow_step_t * step);
+
+/**
+ * Return the weight of an information flow step.  For a direct
+ * infoflow analysis the weight is zero.  For a transitive
+ * analysis this is an integer value that quantatizes the amount of
+ * information that could flow between the start and end types; it is
+ * based upon the currently opened permission map.  It will be a value
+ * between APOL_PERMMAP_MIN_WEIGHT and APOL_PERMMAP_MAX_WEIGHT,
+ * inclusive.
+ *
+ * @param step Infoflow step from which to get weight.
+ * @return Weight of step or < 0 on error.
+ */
+	extern int apol_infoflow_step_get_weight(const apol_infoflow_step_t * step);
+
+/**
+ * Return the vector of access rules for a particular information
+ * step.  This is a vector of qpol_avrule_t pointers.  The caller
+ * <b>should not</b> call apol_vector_destroy() upon the returned
+ * vector.
+ *
+ * @param step Infoflow flow step from which to get rules.
+ *
+ * @return Pointer to a vector of rules relative to the policy originally
+ * used to generate the results or NULL on error.
+ */
+	extern const apol_vector_t *apol_infoflow_step_get_rules(const apol_infoflow_step_t * step);
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif