diff options
Diffstat (limited to 'libapol/include/apol/domain-trans-analysis.h')
| -rw-r--r-- | libapol/include/apol/domain-trans-analysis.h | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/libapol/include/apol/domain-trans-analysis.h b/libapol/include/apol/domain-trans-analysis.h new file mode 100644 index 0000000..2e05748 --- /dev/null +++ b/libapol/include/apol/domain-trans-analysis.h @@ -0,0 +1,427 @@ +/** + * @file + * + * Routines to perform a domain transition analysis. + * + * @author Jeremy A. Mowery jmowery@tresys.com + * @author Jason Tang jtang@tresys.com + * + * Copyright (C) 2005-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_DOMAIN_TRANS_ANALYSIS_H +#define APOL_DOMAIN_TRANS_ANALYSIS_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include "policy.h" +#include "vector.h" +#include <qpol/policy.h> + + typedef struct apol_domain_trans_analysis apol_domain_trans_analysis_t; + typedef struct apol_domain_trans_result apol_domain_trans_result_t; + +#define APOL_DOMAIN_TRANS_DIRECTION_FORWARD 0x01 +#define APOL_DOMAIN_TRANS_DIRECTION_REVERSE 0x02 + +#define APOL_DOMAIN_TRANS_SEARCH_VALID 0x01 +#define APOL_DOMAIN_TRANS_SEARCH_INVALID 0x02 +#define APOL_DOMAIN_TRANS_SEARCH_BOTH (APOL_DOMAIN_TRANS_SEARCH_VALID|APOL_DOMAIN_TRANS_SEARCH_INVALID) + +/******************* table operation functions ****************************/ + +/** + * Build the table of domain transitions for a policy if not already built. + * @param policy The policy for which to build the table; if the table + * already exists for this policy, nothing is done. + * @return 0 on success and < 0 on failure; if the call fails, + * errno will be set and the table will be destroyed. + */ + extern int apol_policy_build_domain_trans_table(apol_policy_t * policy); + +/** + * @deprecated Use apol_policy_build_domain_trans_table(). + */ + extern int apol_policy_domain_trans_table_build(apol_policy_t * policy) __attribute__ ((deprecated)); + +/** + * Reset the state of the domain transition table in a policy. This + * is needed because by default subsequent calls to + * apol_domain_trans_analysis_do() will not produce results generated + * in a previous call. If calls are to be considered independent or + * calls in a different direction are desired, call this function + * prior to apol_domain_trans_analysis_do(). If the table was not + * built yet then this function does nothing. + * + * @param policy Policy containing the table for which the state + * should be reset. + */ + extern void apol_policy_reset_domain_trans_table(apol_policy_t * policy); + +/** + * @deprecated Use apol_policy_reset_domain_trans_table(). + */ + extern void apol_domain_trans_table_reset(apol_policy_t * policy) __attribute__ ((deprecated)); + +/*************** functions to do domain transition anslysis ***************/ + +/** + * Allocate and return a new domain transition analysis structure. All + * fields are cleared; one must fill in the details of the analysis + * before running it. The caller must call apol_domain_trans_analysis_destroy() + * upon the return value afterwards. + * @return An initialized domain transition analysis structure, or NULL + * upon error; if an error occurs errno will be set. + */ + extern apol_domain_trans_analysis_t *apol_domain_trans_analysis_create(void); + +/** + * Deallocate all memory associated with the referenced domain transition + * analysis structure, and then set it to NULL. This function does nothing if + * the analysis is already NULL. + * @param dta Reference to a domain transition analysis structure to destroy. + */ + extern void apol_domain_trans_analysis_destroy(apol_domain_trans_analysis_t ** dta); + +/** + * Set the direction of the transitions with respect to the start type. + * Must be either APOL_DOMAIN_TRANS_DIRECTION_FORWARD + * or APOL_DOMAIN_TRANS_DIRECTION_REVERSE. + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param direction The direction to analyze using one of the two values above. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_set_direction(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + unsigned char direction); + +/** + * Set the analysis to search for transitions based upon whether they + * would be permitted. The value must be one of APOL_DOMAIN_TRANS_SEARCH_* + * defined above. The default for a newly created analysis is to search + * for only valid transitions (i.e. APOL_DOMAIN_TRANS_SEARCH_VALID). + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param valid One of APOL_DOMAIN_TRANS_SEARCH_*. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_set_valid(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + unsigned char valid); + +/** + * Set the analysis to begin searching using a given type. This function + * must be called prior to running the analysis. If a previous type + * was set, it will be free()'d first. + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param type_name Name of the type from which to begin searching. + * Must be non-NULL. This string will be duplicated. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_set_start_type(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *type_name); + +/** + * Set the analysis to return only types matching a regular expression. + * Note that the regular expression will also match types' aliases. + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param result Only return results matching this regular expression, or + * NULL to return all types. + * @return 0 on success, and < 0 on failure; if the call fails, + * errno will be set. + */ + extern int apol_domain_trans_analysis_set_result_regex(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *regex); + +/** + * Set the analysis to return only types having access (via allow + * rules) to this type. <b>This is only valid for forward + * analysis.</b> If more than one type is appended to the query, the + * resulting type must have access to at least one of the appended + * types. Pass a NULL to clear all previously appended types. <b>If + * access types are appended, the caller must also call + * apol_domain_trans_analysis_append_class() at least once with + * a valid class and apol_domain_trans_analysis_append_perm() at + * least once with a valid permission.</b> + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param type_name Type to which a result must have access. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_append_access_type(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *type_name); + +/** + * Set the analysis to return only types having access (via allow + * rules) to this class with the given permission. <b>This is only + * valid for forward analysis.</b> If more than one class is appended + * to the query, the resulting type must have access to at least one + * of the appended classes. If more than one permission is appended + * for the same class, the resulting type must have at least one of + * the appended permissions for that class. Pass a NULL to both + * strings to clear all previously appended classes and + * permissions. <b>If access classes and permissions are appended, + * the caller must also call + * apol_domain_trans_analysis_append_access_type() at least once with + * a valid type.</b> + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param class_name The class to which a result must have access. + * @param perm_name The permission which a result must have + * for the given class. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + * @deprecated This function has been split into + * apol_domain_trans_analysis_append_class() and + * apol_domain_trans_analysis_append_perm() + */ + extern int apol_domain_trans_analysis_append_class_perm(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *class_name, const char *perm_name) + __attribute__ ((deprecated)); + +/** + * Set the analysis to return only types having access (via allow + * rules) to this class. <b>This is only valid for forward + * analysis.</b> If more than one class is appended to the query, the + * resulting type must have access to at least one of the appended + * classes. Pass a NULL to clear all previously appended classes. + * <b>If access classes are appended, the caller must also call + * apol_domain_trans_analysis_append_access_type() at least once with + * a valid type and apol_domain_trans_analysis_append_perm() with a + * valid permission.</b> + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param class_name The class to which a result must have access. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_append_class(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *class_name); + +/** + * Set the analysis to return only types having access (via allow + * rules) to this permission. <b>This is only valid for forward + * analysis.</b> If more than one permission is appended the + * resulting type must have at least one of the appended permissions. + * Pass a NULL to clear all previously appended permissions. <b>If + * access permissions are appended, the caller must also call + * apol_domain_trans_analysis_append_access_type() at least once with + * a valid type and apol_domain_trans_analysis_append_class() at + * least once with a valid class.</b> + * @param policy Policy handler, to report errors. + * @param dta Domain transition analysis to set. + * @param perm_name The permission which a result must have. + * @return 0 on success, and < 0 on error; if the call fails, + * errno will be set and dta will be unchanged. + */ + extern int apol_domain_trans_analysis_append_perm(const apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + const char *perm_name); + +/** + * Execute a domain transition analysis against a particular policy. + * @param policy Policy containing the table to use. + * @param dta A non-NULL structure containng parameters for analysis. + * @param results A reference pointer to a vector of + * apol_domain_trans_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. + * @return 0 on success and < 0 on failure; if the call fails, + * errno will be set and *results will be NULL. + * + * @see apol_policy_reset_domain_trans_table() + */ + extern int apol_domain_trans_analysis_do(apol_policy_t * policy, apol_domain_trans_analysis_t * dta, + apol_vector_t ** results); + +/***************** functions for accessing results ************************/ + +/** + * Return the start type of the transition in an + * apol_domain_trans_result node. The caller should not free the + * returned pointer. If the transition in the node is not valid + * there may be no start type in which case NULL is returned. + * @param dtr Domain transition result node. + * @return Pointer to the start type of the transition. + */ + extern const qpol_type_t *apol_domain_trans_result_get_start_type(const apol_domain_trans_result_t * dtr); + +/** + * Return the entrypoint type of the transition in an + * apol_domain_trans_result node. The caller should not free the + * returned pointer. If the transition in the node is not valid + * there may be no entrypoint in which case NULL is returned. + * @param dtr Domain transition result node. + * @return Pointer to the entrypoint type of the transition. + */ + extern const qpol_type_t *apol_domain_trans_result_get_entrypoint_type(const apol_domain_trans_result_t * dtr); + +/** + * Return the end type of the transition in an apol_domain_trans_result + * node. The caller should not free the returned pointer. If the transition + * in the node is not valid there may be no end type in which case NULL + * is returned. + * @param dtr Domain transition result node. + * @return Pointer to the start type of the transition. + */ + extern const qpol_type_t *apol_domain_trans_result_get_end_type(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of process transition rules (qpol_avrule_t + * pointers) in an apol_domain_trans_result node. The caller should + * not free the returned pointer. If the transition is invalid then + * the returned vector will be empty. + * @param dtr Domain transition result node. + * @return Vector of qpol_avrule_t relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_proc_trans_rules(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of file entrypoint rules (qpol_avrule_t + * pointers) in an apol_domain_trans_result node. The caller should + * not free the returned pointer. If the transition is invalid then + * the returned vector will be empty. + * @return Vector of qpol_avrule_t relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_entrypoint_rules(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of file execute rules (qpol_avrule_t pointers) + * in an apol_domain_trans_result node. The caller should not free + * the returned pointer. If the transition is invalid then the + * returned vector will be empty. + * @return Vector of qpol_avrule_t relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_exec_rules(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of process setexec rules (qpol_avrule_t + * pointers) in an apol_domain_trans_result node. The caller should + * not free the returned pointer. For all policies of version 15 or + * later a transition requires either a setexec rule or a + * type_transition rule to be valid. Valid transitions may have + * both; if there is no rule, this function returns an empty vector. + * @param dtr Domain transition result node. + * @return Vector of qpol_avrule_t relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_setexec_rules(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of type_transition rules (qpol_terule_t + * pointers) in an apol_domain_trans_result node. The caller should + * not free the returned pointer. For all policies of version 15 or + * later a transition requires either a setexec rule or a + * type_transition rule to be valid. Valid transitions may have + * both; if there is no rule, this function returns an empty vector. + * @param dtr Domain transition result node. + * @return Vector of qpol_terule_t relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_type_trans_rules(const apol_domain_trans_result_t * dtr); + +/** + * Determine if the transition in an apol_domain_trans_result node is valid. + * @param dtr Domain transition result node. + * @return 0 if invalid and non-zero if valid. If dtr is NULL, returns 0. + */ + extern int apol_domain_trans_result_is_trans_valid(const apol_domain_trans_result_t * dtr); + +/** + * Return the vector of access rules which satisfied the access + * types, classes, and permissions specified in the query. This is a + * vector of qpol_avrule_t pointers. The caller <b>should not</b> + * call apol_vector_destroy() upon the returned vector. This vector + * is only populated if access criteria were specified in the + * analysis. + * + * @param dtr Domain transition result node. + * @return Pointer to a vector of rules relative to the policy originally + * used to generate the results. + */ + extern const apol_vector_t *apol_domain_trans_result_get_access_rules(const apol_domain_trans_result_t * dtr); + +/** + * Do a deep copy (i.e., a clone) of an apol_domain_trans_result_t + * object. The caller is responsible for calling + * apol_domain_trans_result_destroy() upon the returned value. + * + * @param result Pointer to a domain trans result structure to + * destroy. + * + * @return A clone of the passed in result node, or NULL upon error. + */ + extern apol_domain_trans_result_t *apol_domain_trans_result_create_from_domain_trans_result(const apol_domain_trans_result_t + * in); + +/** + * Free all memory used by an apol_domain_trans_result_t object and + * set it to NULL. This does nothing if the pointer is already NULL. + * <b>This should only be called for results created by + * apol_domain_trans_result_create_from_domain_trans_result() and not + * those returned from within vectors.</b> + * + * @param res Reference pointer to a result to destroy. + */ + extern void apol_domain_trans_result_destroy(apol_domain_trans_result_t ** res); + +/************************ utility functions *******************************/ +/* define the following for rule type */ +#define APOL_DOMAIN_TRANS_RULE_PROC_TRANS 0x01 +#define APOL_DOMAIN_TRANS_RULE_EXEC 0x02 +#define APOL_DOMAIN_TRANS_RULE_EXEC_NO_TRANS 0x04 +#define APOL_DOMAIN_TRANS_RULE_ENTRYPOINT 0x08 +#define APOL_DOMAIN_TRANS_RULE_TYPE_TRANS 0x10 +#define APOL_DOMAIN_TRANS_RULE_SETEXEC 0x20 + +/** + * Verify that a transition using the given three types is valid in the given + * policy. If not valid, return a value indicating the missing rules. If any + * type is NULL, rules that would contain that type are considered missing. A + * valid transition requires a process transition, an entrypoint, and an + * execute rule. If the policy is version 15 or later it also requires either + * a setexec rule or a type_transition rule. The value + * APOL_DOMAIN_TRANS_RULE_EXEC_NO_TRANS is not returned by this function. + * + * @param policy The policy containing the domain transition table to + * consult. Must be non-NULL. + * @param start_dom The starting domain of the transition. May be NULL. + * @param ep_type The entrypoint of the transition. May be NULL. + * @param end_dom The ending domain of the transition. May be NULL. + * + * @return 0 if the transition is valid, < 0 on error, or a bit-wise + * or'ed set of APOL_DOMAIN_TRANS_RULE_* from above (always > 0) + * representing the rules missing from the transition. + */ + extern int apol_domain_trans_table_verify_trans(apol_policy_t * policy, const qpol_type_t * start_dom, + const qpol_type_t * ep_type, const qpol_type_t * end_dom); + +#ifdef __cplusplus +} +#endif + +#endif /* APOL_DOMAIN_TRANS_ANALYSIS_H */ |