/** * @file * Defines the public interface for file context queries. * * @author Jeremy A. Mowery jmowery@tresys.com * @author Jason Tang jtang@tresys.com * * Copyright (C) 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 SEFS_QUERY_H #define SEFS_QUERY_H #ifdef __cplusplus extern "C" { #endif #include #include #ifndef __cplusplus #include #endif #include #include #include #include #ifdef __cplusplus } #include /** * This class represents a query into a (subclass of) fclist. Create * a query, fill in all accessors are needed, and then run the query. * All fields must match for an entry to be returned. Where a fclist * does not support a particular criterion (e.g., inode numbers for * fcfile) that portion of the query is considered to be matching. */ class sefs_query { friend class sefs_db; friend class sefs_fcfile; friend class sefs_filesystem; public: /** * Allocate and return a new sefs query structure. All fields * are initialized, such that running this blank query results * in returning all entries within a fclist. */ sefs_query(); ~sefs_query(); /** * Set a sefs query to match only entries with contexts with * the user \a name. * @param name Limit query to only contexts with this user, or * NULL to clear this field. The string will be duplicated. * @exception std::bad_alloc Out of memory. */ void user(const char *name) throw(std::bad_alloc); /** * Set a sefs query to match only entries with contexts with * the role \a name. * @param name Limit query to only contexts with this role, or * NULL to clear this field. The string will be duplicated. * @exception std::bad_alloc Out of memory. */ void role(const char *name) throw(std::bad_alloc); /** * Set a sefs query to match only entries with contexts with * the type \a name. * @param name Limit query to only contexts with this type, or * NULL to clear this field. The string will be duplicated. * @param indirect If true and if the fclist queried has * access to a policy, also match contexts with types in * attribute \a name or types which are an alias for \a name. * If a policy is not available, this field is ignored, and * exact string matching is used instead. This paramater is * ignored if \a name is NULL. * @exception std::bad_alloc Out of memory. * @see sefs_fclist::associatePolicy() to associate a policy * with a fclist. */ void type(const char *name, bool indirect) throw(std::bad_alloc); /** * Set a sefs query to match only entries with contexts with a * range of \a range. If the fclist is not MLS then \a name * and \a match will be ignored. * @param name Limit query to only contexts matching this * string representing the MLS range, or NULL to clear this * field. The string will be duplicated. * @param match If non-zero and the fclist queried has access * to a policy, match the range using the specified semantics; * this should be one of APOL_QUERY_SUB, APOL_QUERY_SUPER, or * APOL_QUERY_EXACT. (The range string will be converted * automatically into an apol_mls_range_t object.) If a * policy is not available or \a match is zero, exact string * matching is used instead. Note, if a policy is available * the regex flag is ignored if \a match is non-zero. This * parameter is ignored if \a range is NULL. * @exception std::bad_alloc Out of memory. * @see sefs_fclist::associatePolicy() to associate a policy * with a fclist. */ void range(const char *name, int match) throw(std::bad_alloc); /** * Set a sefs query to match only entries with object class \a * objclass. * * Note: If the query is run against a fcfile, then * entries without explicit object classes (i.e., no explicit * --, -d, etc.) will always match * irrespective of the query's object class field. * * @param Numeric identifier for an objclass, one of * QPOL_CLASS_FILE, QPOL_CLASS_DIR, etc., as defined in * . Use QPOL_CLASS_ALL to match all * object classes. */ void objectClass(uint32_t objclass); /** * Set a sefs query to match only entries with object class \a * name. The \a name parameter is not affected by regex(). * * @param name Limit query to only entries with this object * class, or NULL to clear this field. The incoming string * must be legal according to apol_str_to_objclass(). * * @see objectClass(uint32_t) for note about fcfiles. */ void objectClass(const char *name); /** * Set a sefs query to match only entries with path \a path. * * Note: If the query is run against a fcfile, the * behavior of matching paths is slightly different. For each * of fcfile's entries, that entry's regular expression is * matched against \a path. This is the reverse for other * types of fclist, where \a path matches an entry's path if * \a path is a substring. (If sefs_query::regex() is set to * true, \a path is instead treated as a regular expression.) * * @param str Limit query to only entries containing this * path, or NULL to clear this field. The string will be * duplicated. * @exception std::bad_alloc Out of memory. */ void path(const char *str) throw(std::bad_alloc); /** * Set a sefs query to match only entries with a given inode * number. * @param ino Limit query to only entries with this inode * number, or 0 to clear this field. */ void inode(ino64_t ino); /** * Set a sefs query to match only entries with a given device * name. * @param str Limit query to only entries with this device * name, or NULL to clear this string. The string will be * duplicated. * @exception std::bad_alloc Out of memory. * @see sefs_filesystem::getDevName() to convert between dev_t * and a name. */ void dev(const char *str) throw(std::bad_alloc); /** * Set a sefs query to use regular expression matching for * string fields. * @param r If true then use regular expression matching; * otherwise use only exact string matching. */ void regex(bool r); private: /** * Compile the regular expressions stored within this query * object. It is safe to call this function multiple times. * * @exception std::bad_alloc Out of memory. * @exception std::invalid_argument One or more invalid regular * expressions is invalid. */ void compile() throw(std::bad_alloc, std::invalid_argument); char *_user, *_role, *_type, *_range, *_path, *_dev; uint32_t _objclass; bool _indirect, _regex, _recursive; int _rangeMatch; ino64_t _inode; bool _recompiled; regex_t *_reuser, *_rerole, *_retype, *_rerange, *_repath, *_redev; }; extern "C" { #endif //we do not want to wrap two copies of everything so have SWIG ignore //the compatibility section. #ifndef SWIG typedef struct sefs_query sefs_query_t; /** * Allocate and return a new sefs query structure. * @see sefs_query::sefs_query() */ extern sefs_query_t *sefs_query_create(); /** * Deallocate all memory associated with the referenced sefs query, * and then set it to NULL. This function does nothing if the query * is already NULL. * @param query Reference to a sefs query structure to destroy. */ extern void sefs_query_destroy(sefs_query_t ** query); /** * Set a sefs query to match only entries with contexts with the user * \a name. * @see sefs_query::user() */ extern int sefs_query_set_user(sefs_query_t * query, const char *name); /** * Set a sefs query to match only entries with contexts with the role * \a name. * @see sefs_query::role() */ extern int sefs_query_set_role(sefs_query_t * query, const char *name); /** * Set a sefs query to match only entries with contexts with the type * \a name. * @see sefs_query::type() * @see sefs_fclist_associate_policy() to associate a policy with a * fclist. */ extern int sefs_query_set_type(sefs_query_t * query, const char *name, bool indirect); /** * Set a sefs query to match only entries with contexts with a range * of \a range. * @see sefs_query::range() * @see sefs_fclist_associate_policy() to associate a policy with a * fclist. */ extern int sefs_query_set_range(sefs_query_t * query, const char *range, int match); /** * Set a sefs query to match only entries with object class \a * objclass. * @return Always 0. * @see sefs_query::objectClass(uint32_t) */ extern int sefs_query_set_object_class(sefs_query_t * query, uint32_t objclass); /** * Set a sefs query to match only entries with object class \a name. * @return Always 0. * @see sefs_query::objectClass(const char *) */ extern int sefs_query_set_object_class_str(sefs_query_t * query, const char *name); /** * Set a sefs query to match only entries with path \a path. * @see sefs_query::path() */ extern int sefs_query_set_path(sefs_query_t * query, const char *path); /** * Set a sefs query to match only entries with a given inode number. * @return Always 0. * @see sefs_query::inode() */ extern int sefs_query_set_inode(sefs_query_t * query, ino64_t inode); /** * Set a sefs query to match only entries with a given device number. * @see sefs_query::dev() */ extern int sefs_query_set_dev(sefs_query_t * query, const char *dev); /** * Set a sefs query to use regular expression matching for string * fields. * @return Always 0. * @see sefs_query::regex() */ extern int sefs_query_set_regex(sefs_query_t * query, bool regex); #endif /* SWIG */ #ifdef __cplusplus } #endif #endif /* SEFS_QUERY_H */