All of lore.kernel.org
 help / color / mirror / Atom feed
* [RFC][PATCH] extending the libsepol API
@ 2006-03-21 22:46 Kevin Carr
  2006-03-22 12:51 ` Stephen Smalley
                   ` (2 more replies)
  0 siblings, 3 replies; 12+ messages in thread
From: Kevin Carr @ 2006-03-21 22:46 UTC (permalink / raw)
  To: Stephen Smalley, selinux; +Cc: Selinux-Dev

[-- Attachment #1: Type: text/plain, Size: 2162 bytes --]

Hello All,

Some of us at Tresys have been working on changing setools to use libsepol
as our underlying policy representation.  Our basic goals are the following:

1. Provide setools (and other analysis tools) with some of the added
features of libsepol such as modular policy, the new language features, etc 
2. Reduce the redundancy and maintenance required to maintain our own policy
representation 

To make our changes we have been working on some API additions for libsepol.
The attached diff adds some header files that represent how we plan to
export a new shared API for accessing types/attribs.  The patch is the first
of many aimed at fleshing out the shared API.  The diff contains just the
headers as we would like to get some feedback from the community at this
point.

The patch adds two files: "include/iterator.h" and "include/type_query.h".  

We are concerned about consistency in the API and so we intend that the
remaining component accessors will look very similar to the types API.
Ultimately we will need to add access to all other components in the policy
as well as rules and interfaces.  We feel that the iterator concept will
scale well to those functions.

As for the limited number of accessor functions that currently exist,
(users, booleans, etc.) we feel that the current design metaphors don't fit
well with our requirements and we are not sure what to do about them long
term as we are presenting something very different, and as I said we are
concerned about consistency.  There are several long-term options: 1.
Deprecate them in source and keep them for ABI stability, 2. Don't do number
1 ;)

We are looking for constructive feedback, so any comments will be helpful.
We have documented our headers with the doxygen format as we think this is
helpful, we are more than happy to continue or discontinue that format as
work continues, as well as make changes to fit our needs with the rest of
the community.

Again, our goal here is to build something that is more complete in scope
than the current functions, and ultimately found beneficial to the whole
SELinux community.

Kevin Carr
Tresys Technology
410.290.1411 x137


[-- Attachment #2: types-api.patch --]
[-- Type: application/octet-stream, Size: 12055 bytes --]

diff -purN --exclude=.svn trunk/libsepol/include/sepol/iterator.h branch/setools_export-types/libsepol/include/sepol/iterator.h
--- trunk/libsepol/include/sepol/iterator.h	1969-12-31 19:00:00.000000000 -0500
+++ branch/setools_export-types/libsepol/include/sepol/iterator.h	2006-03-12 04:31:26.000000000 -0500
@@ -0,0 +1,86 @@
+/**
+ * @file iterator.h
+ * Defines the public API for sepol_iterator; this structure
+ * is used when requesting lists of components from the policy
+ * database.
+ * 
+ * @author Kevin Carr kcarr@tresys.com
+ * @author Jeremy A. Mowery jmowery@tresys.com
+ * @author Jason Tang jtang@tresys.com
+ *
+ * Copyright (C) 2006 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 SEPOL_ITERATOR_H
+#define SEPOL_ITERATOR_H
+
+#include <stddef.h>
+
+struct sepol_iterator;
+typedef struct sepol_iterator sepol_iterator_t;
+
+/**
+ *  Free memory used by the iterator.
+ *  @param iter Pointer to the iterator to be freed; frees all
+ *  memory used by the iterator and the iterator itself. On returning
+ *  *iter will be NULL.
+ */
+extern void sepol_iterator_destroy(sepol_iterator_t **iter);
+
+/**
+ *  Get the item at the current position of the iterator.
+ *  @param iter The iterator from which to get the item.
+ *  @param item Pointer in which to store the current item; the caller is 
+ *  responsible for safely casting this pointer. Unless specifically
+ *  noted by the function creating the iterator, the item set 
+ *  by this function should not be freed. If the iterator is at 
+ *  the end (i.e. all items have been traversed) *item will be NULL.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *item will be NULL.
+ */
+extern int sepol_iterator_get_item(sepol_iterator_t *iter, void **item);
+
+/**
+ *  Advance the iterator to the next item.
+ *  @param iter The iterator to advance; internal state data will change.
+ *  @return Returns 0 on success and < 0 on failure; advancing an
+ *  iterator that is at the end fails (and returns < 0). If the call fails,
+ *  errno will be set.
+ */
+extern int sepol_iterator_next(sepol_iterator_t *iter);
+
+/**
+ *  Determine if an iterator is at the end.
+ *  @param iter The iterator to check.
+ *  @return Returns non-zero if the current position of the iterator
+ *  is at the end of the list (i.e. past the last valid item) and
+ *  zero in any other case. If there is an error determining if
+ *  the iterator is at the end then non-zero will be returned.
+ */
+extern int sepol_iterator_is_end(sepol_iterator_t *iter);
+
+/**
+ *  Get the total number of items in the list stored in the iterator.
+ *  @param iter The iterator from which to get the number of items.
+ *  @param size Pointer in which to store the number of items. 
+ *  Must be non-NULL.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *size will be 0.
+ */
+extern int sepol_iterator_get_size(sepol_iterator_t *iter, size_t *size);
+
+#endif /* SEPOL_ITERATOR */
diff -purN --exclude=.svn trunk/libsepol/include/sepol/type_query.h branch/setools_export-types/libsepol/include/sepol/type_query.h
--- trunk/libsepol/include/sepol/type_query.h	1969-12-31 19:00:00.000000000 -0500
+++ branch/setools_export-types/libsepol/include/sepol/type_query.h	2006-03-12 04:31:39.000000000 -0500
@@ -0,0 +1,159 @@
+ /**
+ *  @file type_query.h
+ *  Defines the public interface for searching and iterating over types. 
+ *
+ *  @author Kevin Carr kcarr@tresys.com
+ *  @author Jeremy A. Mowery jmowery@tresys.com
+ *  @author Jason Tang jtang@tresys.com
+ *
+ *  Copyright (C) 2006 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 SEPOL_TYPE_QUERY_H
+#define SEPOL_TYPE_QUERY_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <sepol/handle.h>
+#include <sepol/policydb.h>
+#include <sepol/iterator.h>
+
+typedef struct sepol_type_datum sepol_type_datum_t;
+
+/**
+ *  Get the datum for a type by name.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy from which to get the type.
+ *  @param name The name of the type; searching is case sensitive.
+ *  @param datum Pointer in which to store the type datum; the caller
+ *  should not free this pointer.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *datum will be NULL.
+ */
+extern int sepol_policydb_get_type_by_name(sepol_handle_t *handle, sepol_policydb_t *policy, const char *name, sepol_type_datum_t **datum);
+
+/**
+ *  Get an iterator for types declared in the policy.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy from which to create the iterator.
+ *  @param iter Iterator of type sepol_type_datum_t* returned; 
+ *  the caller is responsible for calling sepol_iterator_destroy() to 
+ *  free memory used; it is important to note that the iterator is 
+ *  valid only as long as the policy is unchanged.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *iter will be NULL.
+ */
+extern int sepol_policydb_get_type_iter(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_iterator_t **iter);
+
+/**
+ *  Get the integer value associated with a type. Values range from 1 
+ *  to the number of types declared in the policy.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type from which to get the value.
+ *  @param value Pointer to the integer in which to store value.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and value will be 0.
+ */
+extern int sepol_type_datum_get_value(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, uint32_t *value);
+
+/**
+ *  Determine whether a given type is an alias for another type.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type to check.
+ *  @param isalias Pointer to be set to 1 (true) if the type is an alias
+ *  and 0 (false) otherwise.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *isalias will be 0 (false).
+ */
+extern int sepol_type_datum_get_isalias(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, unsigned char *isalias);
+
+/**
+ *  Determine whether a given type is an attribute.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type to check.
+ *  @param isattr Pointer to be set to 1 (true) if the type is an
+ *  attribute and 0 (false) otherwise.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *isattr will be 0 (false).
+ */
+extern int sepol_type_datum_get_isattr(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, unsigned char *isattr);
+
+/**
+ *  Get an iterator for the list of types in an attribute.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the attribute.
+ *  @param datum The attribute from which to get the types.
+ *  @param types Iterator of type sepol_type_datum_t* returned; 
+ *  the caller is responsible for calling sepol_iterator_destroy() to 
+ *  free memory used; it is important to note that the iterator is 
+ *  valid only as long as the policy is unchanged.
+ *  @return Returns 0 on success, > 0 if the type is not an attribute
+ *  and < 0 on failure; if the call fails, errno will be set and
+ *  *types will be NULL. If the type is not an attribute *types will
+ *  be NUll.
+ */
+extern int sepol_type_datum_get_type_iter(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, sepol_iterator_t **types);
+
+
+/**
+ *  Get an iterator for the list of attributes given to a type.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type for which to get the attributes.
+ *  @param attrs Iterator of type sepol_type_datum_t* returned; 
+ *  the caller is responsible for calling sepol_iterator_destroy() to 
+ *  free memory used; it is important to note that the iterator is 
+ *  valid only as long as the policy is unchanged.
+ *  @return Returns 0 on success, > 0 if the type is an attribute
+ *  and < 0 on failure; if the call fails, errno will be set and
+ *  *types will be NULL. If the type is an attribute *types will
+ *  be NUll.
+ */
+extern int sepol_type_datum_get_attr_iter(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, sepol_iterator_t **attrs);
+
+/**
+ *  Get the name by which a type is identified from its datum.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type for which to get the name.
+ *  @param name Pointer in which to store the name; the caller 
+ *  should not free the string. If the type is an alias then the
+ *  primary name will be returned.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *name will be NULL.
+ */
+extern int sepol_type_datum_get_name(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, char **name);
+
+/**
+ *  Get an iterator for the list of aliases for a type.
+ *  @param handle Error handler for the policy database.
+ *  @param policy The policy associated with the type.
+ *  @param datum The type for which to get aliases.
+ *  @param aliases Iterator of type char* returned; the caller is 
+ *  responsible for calling sepol_iterator_destroy() to free
+ *  memory used; it is important to note that the iterator is valid
+ *  only as long as the policy is unchanged. If a type has no aliases,
+ *  the iterator will be at end and have size 0.
+ *  @return Returns 0 on success and < 0 on failure; if the call fails,
+ *  errno will be set and *aliases will be NULL.
+ */
+extern int sepol_type_datum_get_alias_iter(sepol_handle_t *handle, sepol_policydb_t *policy, sepol_type_datum_t *datum, sepol_iterator_t **aliases);
+
+#endif /* SEPOL_TYPE_QUERY_H */

^ permalink raw reply	[flat|nested] 12+ messages in thread
end of thread, other threads:[~2006-03-28  0:53 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <1143123154.28120.300.camel@moss-spartans.epoch.ncsc.mil>
2006-03-23 19:23 ` [RFC][PATCH] extending the libsepol API Kevin Carr
2006-03-23 19:58   ` Stephen Smalley
2006-03-24 13:37     ` Stephen Smalley
2006-03-24 17:24     ` Kevin Carr
2006-03-28  0:27       ` Ivan Gyurdiev
2006-03-28  0:42   ` Ivan Gyurdiev
2006-03-21 22:46 Kevin Carr
2006-03-22 12:51 ` Stephen Smalley
2006-03-22 15:55   ` Kevin Carr
2006-03-28  0:53     ` Ivan Gyurdiev
2006-03-23 20:41 ` Stephen Smalley
2006-03-27 23:59 ` Ivan Gyurdiev

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.