Create setools-3.3.7 git repomaster

1 files changed, 261 insertions, 0 deletions

diff --git a/libapol/include/apol/context-query.h b/libapol/include/apol/context-query.h
new file mode 100644
index 0000000..2ee269c
--- /dev/null
+++ b/libapol/include/apol/context-query.h
@@ -0,0 +1,261 @@
+/**
+ *  @file
+ *  Public interface for querying and manipulating a context.
+ *
+ *  @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_CONTEXT_QUERY_H
+#define APOL_CONTEXT_QUERY_H
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+#include "policy.h"
+#include "mls-query.h"
+#include <qpol/policy.h>
+
+	typedef struct apol_context apol_context_t;
+
+/**
+ * Allocate and return a new context structure.	 All fields are
+ * initialized to nothing.  The caller must call
+ * apol_context_destroy() upon the return value afterwards.
+ *
+ * @return An initialized context structure, or NULL upon error.
+ */
+	extern apol_context_t *apol_context_create(void);
+
+/**
+ * Allocate and return a new context structure, initialized from an
+ * existing qpol_context_t.  The caller must call
+ * apol_context_destroy() upon the return value afterwards.
+ *
+ * @param p Policy from which the qpol_context_t was obtained.
+ * @param context The libqpol context for which to create a new apol
+ * context.  This context will not be altered by this call.
+ *
+ * @return An initialized context structure, or NULL upon error.
+ */
+	extern apol_context_t *apol_context_create_from_qpol_context(const apol_policy_t * p, const qpol_context_t * context);
+
+/**
+ * Take a literal context string that may be missing components (e.g.,
+ * <b>user_u::type_t:s0:c0.c127</b>), fill in a newly allocated
+ * apol_context_t, and return it.  If there is a MLS range component
+ * to the context, it will <b>not</b> expanded.  The caller must call
+ * apol_context_destroy() upon the return value afterwards.
+ *
+ * Because this function creates a context without the benefit of a
+ * policy, its range is incomplete.  Call apol_context_convert() to
+ * complete it.
+ *
+ * @param context_string Pointer to a string representing a (possibly
+ * incomplete) context, or NULL upon error.
+ *
+ * @return An initialized context structure, or NULL upon error.
+ */
+	extern apol_context_t *apol_context_create_from_literal(const char *context_string);
+
+/**
+ * Deallocate all memory associated with a context structure and then
+ * set it to NULL.  This function does nothing if the context is
+ * already NULL.
+ *
+ * @param context Reference to a context structure to destroy.
+ */
+	extern void apol_context_destroy(apol_context_t ** context);
+
+/**
+ * Set the user field of a context structure.  This function
+ * duplicates the incoming string.
+ *
+ * @param p Error reporting handler, or NULL to use default handler.
+ * @param context Context to modify.
+ * @param user New user field to set, or NULL to unset this field.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_context_set_user(const apol_policy_t * p, apol_context_t * context, const char *user);
+
+/**
+ * Set the role field of a context structure.  This function
+ * duplicates the incoming string.
+ *
+ * @param p Error reporting handler, or NULL to use default handler.
+ * @param context Context to modify.
+ * @param role New role field to set, or NULL to unset this field.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_context_set_role(const apol_policy_t * p, apol_context_t * context, const char *role);
+
+/**
+ * Set the type field of a context structure.  This function
+ * duplicates the incoming string.
+ *
+ * @param p Error reporting handler, or NULL to use default handler.
+ * @param context Context to modify.
+ * @param type New type field to set, or NULL to unset this field.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_context_set_type(const apol_policy_t * p, apol_context_t * context, const char *type);
+
+/**
+ * Set the range field of a context structure.	This function takes
+ * ownership of the range, such that the caller must not modify nor
+ * destroy it afterwards.
+ *
+ * @param p Error reporting handler, or NULL to use default handler.
+ * @param context Context to modify.
+ * @param range New range field to set, or NULL to unset this field.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_context_set_range(const apol_policy_t * p, apol_context_t * context, apol_mls_range_t * range);
+
+/**
+ * Get the user field of a context structure.
+ *
+ * @param context Context to query.
+ *
+ * @return Context's user, or NULL if not set or upon error.  Do not
+ * modify this string.
+ */
+	extern const char *apol_context_get_user(const apol_context_t * context);
+
+/**
+ * Get the role field of a context structure.
+ *
+ * @param context Context to query.
+ *
+ * @return Context's role, or NULL if not set or upon error.  Do not
+ * modify this string.
+ */
+	extern const char *apol_context_get_role(const apol_context_t * context);
+
+/**
+ * Get the type field of a context structure.
+ *
+ * @param context Context to query.
+ *
+ * @return Context's type, or NULL if not set or upon error.  Do not
+ * modify this string.
+ */
+	extern const char *apol_context_get_type(const apol_context_t * context);
+
+/**
+ * Get the range field of a context structure.
+ *
+ * @param context Context to query.
+ *
+ * @return Context's range, or NULL if not set or upon error.  Do not
+ * modify this structure.
+ */
+	extern const apol_mls_range_t *apol_context_get_range(const apol_context_t * context);
+
+/**
+ * Compare two contexts, determining if one matches the other.	The
+ * search context may have empty elements that indicate not to compare
+ * that field.	Types will be matched if the two or any of their
+ * aliases are the same.  The last parameter gives how to match ranges
+ * (assuming that search has a range); it must be one of
+ * APOL_QUERY_SUB, APOL_QUERY_SUPER, APOL_QUERY_EXACT or
+ * APOL_QUERY_INTERSECT as per apol_mls_range_compare().  If a context
+ * 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 policy and MLS information.
+ * @param target Target context to compare.
+ * @param search Source context 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_context_compare(const apol_policy_t * p,
+					const apol_context_t * target, const apol_context_t * search,
+					unsigned int range_compare_type);
+
+/**
+ * Given a complete context (user, role, type, and range if policy is
+ * MLS), determine if it is legal according to the supplied policy.
+ * (Check that the user has that role, the role has that type, etc.)
+ * This function will convert from aliases to canonical forms as
+ * necessary.
+ *
+ * @param p Policy within which to look up context information.
+ * @param context Context to check.
+ *
+ * @return 1 If context is legal, 0 if not; -1 on error.
+ */
+	extern int apol_context_validate(const apol_policy_t * p, const apol_context_t * context);
+
+/**
+ * Given a partial context, determine if it is legal according to the
+ * supplied policy.  For fields that are not specified, assume that
+ * they would be legal.	 For example, if a user is given but not a
+ * role, then return truth if the user is in the policy.  If the
+ * context is NULL then this function returns 1.  This function will
+ * convert from aliases to canonical forms as necessary.
+ *
+ * @param p Policy within which to look up context information.
+ * @param context Context to check.
+ *
+ * @return 1 If context is legal, 0 if not; -1 on error.
+ */
+	extern int apol_context_validate_partial(const apol_policy_t * p, const apol_context_t * context);
+
+/**
+ * Given a context, allocate and return a string that represents the
+ * context.  This function does not check if the context is valid or
+ * not.  An asterisk ("*") represents fields that have not been set.
+ * For example, if a context has the role object_r but has no user nor
+ * type set, it will be rendered as "<sample>*:object_r:*</sample>"
+ * (assuming the given policy is not MLS).
+ *
+ * @param p Policy within which to look up MLS range information.  If
+ * NULL, then attempt to treat the range as incomplete.
+ * @param context Context to render.
+ *
+ * @return A newly allocated string on success, which the caller must
+ * free afterwards.  Upon error return NULL.
+ */
+	extern char *apol_context_render(const apol_policy_t * p, const apol_context_t * context);
+
+/**
+ * Given a context, convert the range within it (as per
+ * apol_mls_range_convert()) to a complete range.  If the context has
+ * no range or has no literal range then do nothing.
+ *
+ * @param p Policy containing category information.
+ * @param context Context to convert.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_context_convert(const apol_policy_t * p, apol_context_t * context);
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif				       /* APOL_CONTEXT_QUERY_H */