diff options
Diffstat (limited to 'libapol/include/apol/mls_level.h')
| -rw-r--r-- | libapol/include/apol/mls_level.h | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/libapol/include/apol/mls_level.h b/libapol/include/apol/mls_level.h new file mode 100644 index 0000000..12e86b4 --- /dev/null +++ b/libapol/include/apol/mls_level.h @@ -0,0 +1,261 @@ +/** + * @file + * Public interface for representing and manipulating an + * apol_mls_level 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_LEVEL_H +#define APOL_MLS_LEVEL_H + +#ifdef __cplusplus +extern "C" +{ +#endif + +#include "policy.h" +#include "vector.h" +#include <qpol/policy.h> + + typedef struct apol_mls_level apol_mls_level_t; + +/** + * Allocate and return a new MLS level structure. All fields are + * initialized to nothing. The caller must call + * apol_mls_level_destroy() upon the return value afterwards. + * + * @return An initialized MLS level structure, or NULL upon error. + */ + extern apol_mls_level_t *apol_mls_level_create(void); + +/** + * Allocate and return an MLS level structure, initialized by an + * existing apol_mls_level_t object. The caller must call + * apol_mls_level_destroy() upon the return value afterwards. + * + * @param level Level to copy. If NULL then the returned MLS level + * will be initialized to nothing. + * + * @return An initialized MLS level structure, or NULL upon error. + */ + extern apol_mls_level_t *apol_mls_level_create_from_mls_level(const apol_mls_level_t * level); + +/** + * Take a MLS level string (e.g., <b>S0:C0.C127</b>) and parse it. + * Fill in a newly allocated apol_mls_level_t and return it. This + * function needs a policy to resolve dots within categories. If the + * string represents an illegal level then return NULL. The caller + * must call apol_mls_level_destroy() upon the returned value + * afterwards. + * + * @param p Policy within which to validate mls_level_string. + * @param mls_level_string Pointer to a string representing a valid + * MLS level. + * + * @return A filled in MLS level structure, or NULL upon error. + */ + extern apol_mls_level_t *apol_mls_level_create_from_string(const apol_policy_t * p, const char *mls_level_string); + +/** + * Take a literal MLS level string (e.g., <b>S0:C0.C127</b>), fill in + * a newly allocated apol_mls_level_t and return it. The category + * portion of the level will <strong>not</strong> be expanded (i.e., + * dots will not be resolved). The caller must call + * apol_mls_level_destroy() upon the returned value afterwards. + * + * Because this function creates a level without the benefit of a + * policy, its category list is "incomplete" and thus most operations + * will fail. All functions other than apol_mls_level_render(), + * apol_mls_level_convert(), and apol_mls_level_is_literal() will + * result in error. Call apol_mls_level_convert() to make a literal + * MLS level complete, so that it can be used in all functions. + * + * @param mls_level_string Pointer to a string representing a + * (possibly invalid) MLS level. + * + * @return A filled in MLS level structure, or NULL upon error. + */ + extern apol_mls_level_t *apol_mls_level_create_from_literal(const char *mls_level_string); + +/** + * Create a new apol_mls_level_t and initialize it with a + * qpol_mls_level_t. The caller must call apol_mls_level_destroy() + * upon the returned value afterwards. + * + * @param p Policy from which the qpol_mls_level_t was obtained. + * @param qpol_level The libqpol level for which to create a new + * apol level. This level will not be altered by this call. + * + * @return A MLS level structure initialized to the value of + * qpol_level, or NULL upon error. + */ + extern apol_mls_level_t *apol_mls_level_create_from_qpol_mls_level(const apol_policy_t * p, + const qpol_mls_level_t * qpol_level); + +/** + * Create a new apol_mls_level_t and initialize it with a + * qpol_level_t. The caller must call apol_mls_level_destroy() + * upon the returned value afterwards. + * + * @param p Policy from which the qpol_level_t was obtained. + * @param qpol_level The libqpol level for which to create a new + * apol level. This level will not be altered by this call. + * + * @return A MLS level structure initialized to the value of + * qpol_level, or NULL upon error. + */ + apol_mls_level_t *apol_mls_level_create_from_qpol_level_datum(const apol_policy_t * p, const qpol_level_t * qpol_level); + +/** + * Deallocate all memory associated with a MLS level structure and + * then set it to NULL. This function does nothing if the level is + * already NULL. + * + * @param level Reference to a MLS level structure to destroy. + */ + extern void apol_mls_level_destroy(apol_mls_level_t ** level); + +/** + * Set the sensitivity component of an MLS level structure. This + * function duplicates the incoming string. + * + * @param p Error reporting handler, or NULL to use default handler. + * @param level MLS level to modify. + * @param sens New sensitivity component to set, or NULL to unset this + * field. + * + * @return 0 on success, negative on error. + */ + extern int apol_mls_level_set_sens(const apol_policy_t * p, apol_mls_level_t * level, const char *sens); + +/** + * Get the sensitivity component of an MLS level structure. + * + * @param level MLS level to query. + * + * @return The sensitivity, or NULL upon error if it has not yet been + * set. Do not modify the return value. + */ + extern const char *apol_mls_level_get_sens(const apol_mls_level_t * level); + +/** + * Add a category component of an MLS level structure. This function + * duplicates the incoming string. + * + * @param p Error reporting handler, or NULL to use default handler. + * @param level MLS level to modify. + * @param cats New category component to append. + * + * @return 0 on success or < 0 on failure. + */ + extern int apol_mls_level_append_cats(const apol_policy_t * p, apol_mls_level_t * level, const char *cats); + +/** + * Get the category component of an MLS level structure. This will be + * a vector of strings, sorted alphabetically. + * + * @param level MLS level to query. + * + * @return Vector of categories, or NULL upon error. Be aware that + * the vector could be empty if no categories have been set. Do not + * modify the return value. + */ + extern const apol_vector_t *apol_mls_level_get_cats(const apol_mls_level_t * level); + +/** + * Compare two levels and determine their relationship to each other. + * Both levels must have their respective sensitivity and categories + * set. Levels may contain aliases in place of primary names. If + * level2 is NULL then this always returns APOL_MLS_EQ. + * + * @param p Policy within which to look up MLS information. + * @param target Target MLS level to compare. + * @param search Source MLS level to compare. + * + * @return One of APOL_MLS_EQ, APOL_MLS_DOM, APOL_MLS_DOMBY, or + * APOL_MLS_INCOMP; < 0 on error. + * + * @see apol_mls_level_validate() + */ + extern int apol_mls_level_compare(const apol_policy_t * p, const apol_mls_level_t * level1, + const apol_mls_level_t * level2); + +/** + * Given a level, determine if it is legal according to the supplied + * policy. This function will convert from aliases to canonical forms + * as necessary. + * + * @param h Error reporting handler. + * @param p Policy within which to look up MLS information. + * @param level Level to check. + * + * @return 1 If level is legal, 0 if not; < 0 on error. + * + * @see apol_mls_level_compare() + */ + extern int apol_mls_level_validate(const apol_policy_t * p, const apol_mls_level_t * level); + +/** + * Creates a string containing the textual representation of + * a MLS level. + * @param p Policy from which the MLS level is a member. If NULL, + * then attempt to treat the level as an incomplete level (as per + * apol_mls_level_create_from_literal()). + * @param level MLS level 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_level_render(const apol_policy_t * p, const apol_mls_level_t * level); + +/** + * Given a policy and a MLS level created by + * apol_mls_level_create_from_literal(), convert the level to have a + * valid ("complete") list of categories. This will take the literal + * string stored within the level and resolve its category lists, such + * as by expanding dots. The level will keep its literal string, so + * that it may be converted again if given a different policy. + * + * @param p Policy containing category information. + * @param level MLS level to convert. + * + * @return 0 on success, < 0 on error. + */ + extern int apol_mls_level_convert(const apol_policy_t * p, apol_mls_level_t * level); + +/** + * Determine if a level is literal (i.e., created from + * apol_mls_level_create_from_literal()). Note that converting a + * literal level (apol_mls_level_convert()) completes the level, but + * it is still a literal level. + * + * @param level Level to query. + * + * @return > 0 value if the level is literal, 0 if not, < 0 if unknown + * or upon error. + */ + extern int apol_mls_level_is_literal(const apol_mls_level_t * level); + +#ifdef __cplusplus +} +#endif + +#endif /* APOL_MLS_LEVEL_H */ |