/** * @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 /* 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 should not 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 must not * 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