diff options
Diffstat (limited to 'libapol/include/apol/types-relation-analysis.h')
| -rw-r--r-- | libapol/include/apol/types-relation-analysis.h | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/libapol/include/apol/types-relation-analysis.h b/libapol/include/apol/types-relation-analysis.h new file mode 100644 index 0000000..1278072 --- /dev/null +++ b/libapol/include/apol/types-relation-analysis.h @@ -0,0 +1,380 @@ +/** + * @file + * + * Routines to perform a two-types relationship analysis. + * + * @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_TYPES_RELATION_ANALYSIS_H +#define APOL_TYPES_RELATION_ANALYSIS_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include "policy.h" +#include "vector.h" +#include <qpol/policy.h> + +/* Specify a which types relationship analysis/analyses to run using + * these bit values. + */ +#define APOL_TYPES_RELATION_COMMON_ATTRIBS 0x0001 +#define APOL_TYPES_RELATION_COMMON_ROLES 0x0002 +#define APOL_TYPES_RELATION_COMMON_USERS 0x0004 +#define APOL_TYPES_RELATION_SIMILAR_ACCESS 0x0010 +#define APOL_TYPES_RELATION_DISSIMILAR_ACCESS 0x0020 +#define APOL_TYPES_RELATION_ALLOW_RULES 0x0100 +#define APOL_TYPES_RELATION_TYPE_RULES 0x0200 +#define APOL_TYPES_RELATION_DOMAIN_TRANS_AB 0x0400 +#define APOL_TYPES_RELATION_DOMAIN_TRANS_BA 0x0800 +#define APOL_TYPES_RELATION_DIRECT_FLOW 0x1000 +#define APOL_TYPES_RELATION_TRANS_FLOW_AB 0x4000 +#define APOL_TYPES_RELATION_TRANS_FLOW_BA 0x8000 + + typedef struct apol_types_relation_analysis apol_types_relation_analysis_t; + typedef struct apol_types_relation_result apol_types_relation_result_t; + typedef struct apol_types_relation_access apol_types_relation_access_t; + +/********** functions to do types relation analysis **********/ + +/** + * Execute a two types relationship analysis against a particular + * policy. + * + * @param p Policy within which to look up relationships. + * @param tr A non-NULL structure containing parameters for analysis. + * @param r Reference to a apol_types_relation_result_t. The object + * will be allocated by this function. The caller must call + * apol_types_relation_result_destroy() afterwards. This will be set + * to NULL upon no results or upon error. + * + * @return 0 on success, negative on error. + */ + extern int apol_types_relation_analysis_do(apol_policy_t * p, + const apol_types_relation_analysis_t * tr, apol_types_relation_result_t ** r); + +/** + * Allocate and return a new two types relationship analysis + * structure. All fields are cleared; one must fill in the details of + * the analysis before running it. The caller must call + * apol_types_relation_analysis_destroy() upon the return value + * afterwards. + * + * @return An initialized two types relationship analysis structure, or + * NULL upon error. + */ + extern apol_types_relation_analysis_t *apol_types_relation_analysis_create(void); + +/** + * Deallocate all memory associated with the referenced types relation + * analysis, and then set it to NULL. This function does nothing if + * the analysis is already NULL. + * + * @param tr Reference to a types relation analysis structure to + * destroy. + */ + extern void apol_types_relation_analysis_destroy(apol_types_relation_analysis_t ** tr); + +/** + * Set a types relation analysis to begin analysis from this first + * type. This function must be called prior to running the analysis. + * + * @param p Policy handler, to report errors. + * @param tr Types relation analysis to set. + * @param name Perform analysis with this non-NULL name. + * + * @return 0 on success, negative on error. + */ + extern int apol_types_relation_analysis_set_first_type(const apol_policy_t * p, apol_types_relation_analysis_t * tr, + const char *name); + +/** + * Set a types relation analysis to begin analysis from this other + * type. This function must be called prior to running the analysis. + * + * @param p Policy handler, to report errors. + * @param tr Types relation analysis to set. + * @param name Perform analysis with this other non-NULL name. + * + * @return 0 on success, negative on error. + */ + extern int apol_types_relation_analysis_set_other_type(const apol_policy_t * p, apol_types_relation_analysis_t * tr, + const char *name); + +/** + * Set a types relation analysis to run the specified + * analysis/analyses. This is a bitmap; use the defines + * APOL_TYPES_RELATION_COMMON_ATTRIBUTES etc. to specify which one(s) + * to run. + * + * @param p Policy handler, to report errors. + * @param tr Types relation analysis to set. + * @param analyses Bitmap to indicate which analyses to run, or 0 to + * run them all. + * + * @return Always 0. + */ + extern int apol_types_relation_analysis_set_analyses(const apol_policy_t * p, apol_types_relation_analysis_t * tr, + unsigned int analyses); + +/*************** functions to access types relation results ***************/ + +/** + * Deallocate all memory associated with a types relation analysis + * result, including the pointer itself. This function does nothing + * if the result is already NULL. + * + * @param result Reference to a types relation result structure to + * destroy. + */ + extern void apol_types_relation_result_destroy(apol_types_relation_result_t ** result); + +/** + * Return the vector of attributes common to the two types. This is a + * vector of qpol_type_t pointers. The caller <b>should not</b> call + * apol_vector_destroy() upon the returned vector. If the user did + * not request this analysis then the return value will be NULL. + * + * @param result Types relation result from which to get common + * attributes. + * + * @return Vector of common attributes, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_attributes(const apol_types_relation_result_t * result); + +/** + * Return the vector of roles common to the two types. This is a + * vector of qpol_role_t pointers. The caller <b>should not</b> call + * apol_vector_destroy() upon the returned vector. If the user did + * not request this analysis then the return value will be NULL. + * + * @param result Types relation result from which to get common roles. + * + * @return Vector of common roles, or NULL if analysis was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_roles(const apol_types_relation_result_t * result); + +/** + * Return the vector of users common to the two types. This is a + * vector of qpol_user_t pointers. The caller <b>should not</b> call + * apol_vector_destroy() upon the returned vector. If the user did + * not request this analysis then the return value will be NULL. + * + * @param result Types relation result from which to get common users. + * + * @return Vector of common users, or NULL if analysis was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_users(const apol_types_relation_result_t * result); + +/** + * Return the vector of accesses similar to the two types. This is a + * vector of apol_types_relation_access_t pointers. The vector will + * contain only the rules that the first type had. Call + * apol_types_relation_result_get_similar_other() to get the + * complementary vector (i.e., both vectors will have the same types). + * The caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get similar accesses. + * + * @return Vector of similar accesses, or NULL if analysis was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_similar_first(const apol_types_relation_result_t * result); + +/** + * Return the vector of accesses similar to the two types. This is a + * vector of apol_types_relation_access_t pointers. The vector will + * contain only the rules that the other type had. Call + * apol_types_relation_result_get_similar_first() to get the + * complementary vector (i.e., both vectors will have the same types). + * The caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get similar accesses. + * + * @return Vector of similar accesses, or NULL if analysis was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_similar_other(const apol_types_relation_result_t * result); + +/** + * Return the vector of accesses dissimilar for the first type (i.e., + * types that the first type reaches that the other type does not). + * This is a vector of apol_types_relation_access_t pointers. The + * caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get dissimilar + * accesses. + * + * @return Vector of dissimilar accesses, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_dissimilar_first(const apol_types_relation_result_t * result); + +/** + * Return the vector of accesses dissimilar for the other type (i.e., + * types that the other type reaches that the first type does not). + * This is a vector of apol_types_relation_access_t pointers. The + * caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get dissimilar + * accesses. + * + * @return Vector of dissimilar accesses, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_dissimilar_other(const apol_types_relation_result_t * result); + +/** + * Return the vector of allow rules involving both types (allow one + * type to the other). This is a vector of qpol_avrule_t pointers. + * The caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get rules. + * + * @return Vector of allow rules, or NULL if analysis was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_allowrules(const apol_types_relation_result_t * result); + +/** + * Return the vector of type transition / type change rules involving + * both types. This is a vector of qpol_terule_t pointers. The + * caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get rules. + * + * @return Vector of type enforcement rules, or NULL if analysis was + * not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_typerules(const apol_types_relation_result_t * result); + +/** + * Return the vector of apol_infoflow_result_t pointers corresponding + * to a direct information flow analysis between both types. The + * caller <b>should not</b> call apol_vector_destroy() upon the + * returned vector. If the user did not request this analysis then + * the return value will be NULL. + * + * @param result Types relation result from which to get information + * flows. + * + * @return Vector of infoflow results, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_directflows(const apol_types_relation_result_t * result); + +/** + * Return the vector of apol_infoflow_result_t pointers corresponding + * to a transitive information flow analysis between the first type to + * the other. The caller <b>should not</b> call apol_vector_destroy() + * upon the returned vector. If the user did not request this + * analysis then the return value will be NULL. + * + * @param result Types relation result from which to get information + * flows. + * + * @return Vector of infoflow results, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_transflowsAB(const apol_types_relation_result_t * result); + +/** + * Return the vector of apol_infoflow_result_t pointers corresponding + * to a transitive information flow analysis between the other type to + * the first. The caller <b>should not</b> call apol_vector_destroy() + * upon the returned vector. If the user did not request this + * analysis then the return value will be NULL. + * + * @param result Types relation result from which to get information + * flows. + * + * @return Vector of infoflow results, or NULL if analysis was not + * run. + */ + extern const apol_vector_t *apol_types_relation_result_get_transflowsBA(const apol_types_relation_result_t * result); + +/** + * Return the vector of apol_domain_trans_result_t pointers + * corresponding to a domain transition analysis between the first + * type to the other. The caller <b>should not</b> call + * apol_vector_destroy() upon the returned vector. If the user did + * not request this analysis then the return value will be NULL. + * + * @param result Types relation result from which to get domain + * transitions. + * + * @return Vector of domain transition results, or NULL if analysis + * was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_domainsAB(const apol_types_relation_result_t * result); + +/** + * Return the vector of apol_domain_trans_result_t pointers + * corresponding to a domain transition analysis between the other + * type to the first. The caller <b>should not</b> call + * apol_vector_destroy() upon the returned vector. If the user did + * not request this analysis then the return value will be NULL. + * + * @param result Types relation result from which to get domain + * transitions. + * + * @return Vector of domain transition results, or NULL if analysis + * was not run. + */ + extern const apol_vector_t *apol_types_relation_result_get_domainsBA(const apol_types_relation_result_t * result); + +/** + * Given a types relation access node, return the type stored within. + * + * @param a Types relation access node. + * + * @return Pointer to the type stored within. + */ + extern const qpol_type_t *apol_types_relation_access_get_type(const apol_types_relation_access_t * a); + +/** + * Given a types relation access node, return the vector of + * qpol_avrule_t pointers stored within. + * + * @param a Types relation access node. + * + * @return Pointer to the vector of rules. The caller <b>must not</b> + * destroy this vector. + */ + extern const apol_vector_t *apol_types_relation_access_get_rules(const apol_types_relation_access_t * a); + +#ifdef __cplusplus +} +#endif + +#endif |