/usr/include/apol/context-query.h is in libapol-dev 3.3.8-3ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 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 */
|