diff options
Diffstat (limited to 'libapol/include/apol/mls_range.h')
-rw-r--r-- | libapol/include/apol/mls_range.h | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/libapol/include/apol/mls_range.h b/libapol/include/apol/mls_range.h new file mode 100644 index 0000000..49dade7 --- /dev/null +++ b/libapol/include/apol/mls_range.h @@ -0,0 +1,270 @@ +/** + * @file + * Public interface for representing and manipulating the + * apol_mls_range object. + * + * @author Jeremy A. Mowery jmowery@tresys.com + * @author Jason Tang jtang@tresys.com + * + * Copyright (C) 2006-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_MLS_RANGE_H +#define APOL_MLS_RANGE_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include "mls_level.h" +#include "policy.h" +#include "vector.h" +#include <qpol/policy.h> + + typedef struct apol_mls_range apol_mls_range_t; + +/** + * Allocate and return a new MLS range structure. All fields are + * initialized to nothing. The caller must call + * apol_mls_range_destroy() upon the return value afterwards. + * + * @return An initialized MLS range structure, or NULL upon error. + */ + extern apol_mls_range_t *apol_mls_range_create(void); + +/** + * Allocate and return a new MLS range structure, initialized by an + * existing apol_mls_range_t. The caller must call + * apol_mls_range_destroy() upon the return value afterwards. + * + * @param range Range to copy. If NULL then the returned MLS range + * will be initialized to nothing. + * + * @return An initialized MLS range structure, or NULL upon error. + */ + extern apol_mls_range_t *apol_mls_range_create_from_mls_range(const apol_mls_range_t * range); + +/** + * Take a MLS range string (e.g., <b>S0:C0.C10-S1:C0.C127</b>) and + * parse it. Fill in a newly allocated apol_mls_range_t and return + * it. This function needs a policy to resolve dots within categories + * and to ensure that the high level dominates the low. If the string + * represents an illegal range then return NULL. The caller must call + * apol_mls_range_destroy() upon the returned value afterwards. + * + * @param p Policy within which to validate mls_range_string. + * @param mls_range_string Pointer to a string representing a valid + * MLS range. + * + * @return A filled in MLS range structure, or NULL upon error. + */ + extern apol_mls_range_t *apol_mls_range_create_from_string(const apol_policy_t * p, const char *mls_range_string); + +/** + * Take a literal MLS range string (e.g., + * <b>S0:C0.C10-S1:C0.C127</b>), fill in a newly allocated + * apol_mls_range_t and return it. The category portions of the + * levels will <strong>not</strong> be expanded (i.e., dots will not + * be resolved); likewise there is no check that the high level + * dominates the low. The caller must call apol_mls_range_destroy() + * upon the returned value afterwards. + * + * Because this function creates a range without the benefit of a + * policy, its levels are "incomplete" and thus most operations will + * fail. Call apol_mls_range_convert() to make a literal MLS range + * complete, so that it can be used in all functions. + * + * @param mls_range_string Pointer to a string representing a + * (possibly invalid) MLS range. + * + * @return A filled in MLS range structure, or NULL upon error. + */ + extern apol_mls_range_t *apol_mls_range_create_from_literal(const char *mls_range_string); + +/** + * Create a new apol_mls_range_t and initialize it with a + * qpol_mls_range_t. The caller must call apol_mls_range_destroy() + * upon the return value afterwards. + * + * @param p Policy from which the qpol_mls_range_t was obtained. + * @param qpol_range The libqpol range for which to create a new + * apol range. This range will not be altered by this call. + * + * @return A MLS range structure initialized to the value of + * qpol_range, or NULL upon error. + */ + extern apol_mls_range_t *apol_mls_range_create_from_qpol_mls_range(const apol_policy_t * p, + const qpol_mls_range_t * qpol_range); + +/** + * Deallocate all memory associated with a MLS range structure and + * then set it to NULL. This function does nothing if the range is + * already NULL. + * + * @param range Reference to a MLS range structure to destroy. + */ + extern void apol_mls_range_destroy(apol_mls_range_t ** range); + +/** + * Set the low level component of a MLS range structure. This + * function takes ownership of the level, such that the caller must + * not modify nor destroy it afterwards. It is legal to pass in the + * same pointer for the range's low and high level. + * + * @param p Error reporting handler, or NULL to use default handler. + * @param range MLS range to modify. + * @param level New low level for range, or NULL to unset this field. + * + * @return 0 on success or < 0 on failure. + */ + extern int apol_mls_range_set_low(const apol_policy_t * p, apol_mls_range_t * range, apol_mls_level_t * level); + +/** + * Set the high level component of a MLS range structure. This + * function takes ownership of the level, such that the caller must + * not modify nor destroy it afterwards. It is legal to pass in the + * same pointer for the range's low and high level. + * + * @param p Error reporting handler, or NULL to use default handler. + * @param range MLS range to modify. + * @param level New high level for range, or NULL to unset this field. + * + * @return 0 on success or < 0 on failure. + */ + extern int apol_mls_range_set_high(const apol_policy_t * p, apol_mls_range_t * range, apol_mls_level_t * level); + +/** + * Get the low level component of a MLS range structure. + * + * @param range MLS range to query. + * + * @return Low level, or NULL upon error or if not yet set. Do not + * modify the return value. + */ + extern const apol_mls_level_t *apol_mls_range_get_low(const apol_mls_range_t * range); + +/** + * Get the high level component of a MLS range structure. + * + * @param range MLS range to query. + * + * @return High level, or NULL upon error or if not yet set. Do not + * modify the return value. + */ + extern const apol_mls_level_t *apol_mls_range_get_high(const apol_mls_range_t * range); + +/** + * Compare two ranges, determining if one matches the other. The + * fifth parameter gives how to match the ranges. For APOL_QUERY_SUB, + * if search is a subset of target. For APOL_QUERY_SUPER, if search + * is a superset of target. Other valid compare types are + * APOL_QUERY_EXACT and APOL_QUERY_INTERSECT. If a range is not valid + * according to the policy then this function returns -1. If search + * is NULL then comparison always succeeds. + * + * @param p Policy within which to look up MLS information. + * @param target Target MLS range to compare. + * @param search Source MLS range to compare. + * @param range_compare_type Specifies how to compare the ranges. + * + * @return 1 If comparison succeeds, 0 if not; -1 on error. + */ + extern int apol_mls_range_compare(const apol_policy_t * p, + const apol_mls_range_t * target, const apol_mls_range_t * search, + unsigned int range_compare_type); + +/** + * Determine if a range completely contains a subrange given a certain + * policy. If a range is not valid according to the policy then this + * function returns -1. + * + * @param p Policy within which to look up MLS information. + * @param range Parent range to compare. + * @param subrange Child range to which compare. + * + * @return 1 If comparison succeeds, 0 if not; -1 on error. + */ + extern int apol_mls_range_contain_subrange(const apol_policy_t * p, const apol_mls_range_t * range, + const apol_mls_range_t * subrange); +/** + * Given a range, determine if it is legal according to the supplied + * policy. This function will convert from aliases to canonical forms + * as necessary. + * + * @param p Policy within which to look up MLS information. + * @param range Range to check. + * + * @return 1 If range is legal, 0 if not; -1 on error. + */ + extern int apol_mls_range_validate(const apol_policy_t * p, const apol_mls_range_t * range); + +/** + * Given a range, return a vector of levels (type apol_mls_level_t *) + * that constitutes that range. The vector will be sorted in policy order. + * + * @param p Policy from which the level and category definitions reside. + * @param range Range to expand. + * + * @return Vector of levels, or NULL upon error. The caller is + * responsible for calling apol_vector_destroy() upon the returned + * value, passing apol_mls_level_free() as the second parameter. + */ + extern apol_vector_t *apol_mls_range_get_levels(const apol_policy_t * p, const apol_mls_range_t * range); + +/** + * Creates a string containing the textual representation of + * a MLS range. + * + * @param p Policy from which the MLS range is a member. If NULL, + * then attempt to treat the range's levels as incomplete levels (as + * per apol_mls_level_create_from_literal()). + * @param range MLS range to render. + * + * @return A newly allocated string, or NULL upon error. The caller + * is responsible for calling free() upon the return value. + */ + extern char *apol_mls_range_render(const apol_policy_t * p, const apol_mls_range_t * range); + +/** + * Given a range, convert any literal MLS levels within it (as per + * apol_mls_level_convert()) to a complete level. If the range has no + * levels or has no literal levels then do nothing. + * + * @param p Policy containing category information. + * @param range Range to convert. + * + * @return 0 on success, < 0 on error. + */ + extern int apol_mls_range_convert(const apol_policy_t * p, apol_mls_range_t * range); + +/** + * Determine if the range contains any literal levels. (Levels that + * have been converted are still considered literal.) + * + * @param range Range to query. + * + * @return > 0 value if the range has a literal level, 0 if not, < 0 + * if unknown or upon error. + */ + extern int apol_mls_range_is_literal(const apol_mls_range_t * range); + +#ifdef __cplusplus +} +#endif + +#endif /* APOL_MLS_RANGE_H */ |