PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Tue Jul 24 14:42:05 PDT 2007
doc/TODO | 6 +++-
polkit-dbus/polkit-dbus.c | 25 +++++++++++++++-
polkit/polkit-config.c | 61 +++++++++++++++++++++++++++++++++++++++++
polkit/polkit-context.c | 23 +++++++++++++--
polkit/polkit-grant-database.c | 7 ++++
polkit/polkit-result.c | 9 ++++--
6 files changed, 123 insertions(+), 8 deletions(-)
New commits:
diff-tree a9860cf824a6503e09ea43070178676b39ca92f2 (from e13a83721307711f257e9222a4d6adebda78f662)
Author: David Zeuthen <davidz at redhat.com>
Date: Tue Jul 24 17:42:08 2007 -0400
fix up some of the docs
diff --git a/doc/TODO b/doc/TODO
index 1505e38..e4495aa 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -74,7 +74,11 @@
The is a bit like Objects mentioned in the spec (and what we used
to have as PolKitResource) but a bit more blurry. It may just work.
- - Be more forgiving about bad policy files and bad config files. Hard problem.
+ - Be more forgiving about bad policy files and bad config files. Hard
+ problem; it's potentially security sensitive. At least we probably
+ need to spam the syslog
+
+ - policy descriptions and localization
- Go to 1.0 soon
diff --git a/polkit-dbus/polkit-dbus.c b/polkit-dbus/polkit-dbus.c
index 07cc53d..ecfe977 100644
--- a/polkit-dbus/polkit-dbus.c
+++ b/polkit-dbus/polkit-dbus.c
@@ -26,10 +26,16 @@
/**
* SECTION:polkit-dbus
- * @short_description: Helper library for obtaining seat, session and caller information via D-Bus and ConsoleKit.
+ * @short_description: Helper library for obtaining seat, session and
+ * caller information via D-Bus and ConsoleKit.
*
* Helper library for obtaining seat, session and caller information
- * via D-Bus and ConsoleKit.
+ * via D-Bus and ConsoleKit. This library is only useful when writing
+ * a mechanism. If the mechanism itself is a daemon exposing a remote
+ * services (via e.g. D-Bus) it's often a better idea, to reduce
+ * roundtrips, to track and cache caller information and construct
+ * #PolKitCaller objects yourself based on this information (for an
+ * example of this, see the hald sources on how this can be done).
**/
#ifdef HAVE_CONFIG_H
@@ -547,6 +553,21 @@ out:
return caller;
}
+/**
+ * polkit_caller_new_from_pid:
+ * @con: D-Bus system bus connection
+ * @dbus_name: process id
+ * @error: D-Bus error
+ *
+ * This function will construct a #PolKitCaller object by querying
+ * both information in /proc (on Linux) and the ConsoleKit daemon for
+ * information about a given process. Note that this will do a lot of
+ * blocking IO so it is best avoided if your process already
+ * tracks/caches all the information.
+ *
+ * Returns: the new object or #NULL if an error occured (in which case
+ * @error will be set)
+ **/
PolKitCaller *
polkit_caller_new_from_pid (DBusConnection *con, pid_t pid, DBusError *error)
{
diff --git a/polkit/polkit-config.c b/polkit/polkit-config.c
index e969661..d0de655 100644
--- a/polkit/polkit-config.c
+++ b/polkit/polkit-config.c
@@ -45,6 +45,13 @@
#include "polkit-debug.h"
#include "polkit-error.h"
+/**
+ * SECTION:polkit-config
+ * @short_description: Configuration file.
+ *
+ * This class is used to represent the /etc/PolicyKit/PolicyKit.conf configuration file.
+ **/
+
enum {
STATE_NONE,
STATE_IN_CONFIG,
@@ -55,6 +62,11 @@ enum {
struct ConfigNode;
typedef struct ConfigNode ConfigNode;
+/**
+ * PolKitConfig:
+ *
+ * This class represents the system-wide configuration file for PolicyKit.
+ **/
struct PolKitConfig
{
int refcount;
@@ -112,6 +124,7 @@ struct ConfigNode
GSList *children;
};
+
static ConfigNode *
config_node_new (void)
{
@@ -322,6 +335,14 @@ error:
XML_StopParser (pd->parser, FALSE);
}
+/**
+ * polkit_config_new:
+ * @error: return location for error
+ *
+ * Create a new object representing the /etc/PolicyKit/PolicyKit.conf configuration file.
+ *
+ * Returns: the configuration file object
+ **/
PolKitConfig *
polkit_config_new (PolKitError **error)
{
@@ -397,6 +418,14 @@ error:
return NULL;
}
+/**
+ * polkit_config_ref:
+ * @pk_config: the object
+ *
+ * Increase reference count.
+ *
+ * Returns: the object
+ **/
PolKitConfig *
polkit_config_ref (PolKitConfig *pk_config)
{
@@ -405,6 +434,14 @@ polkit_config_ref (PolKitConfig *pk_conf
return pk_config;
}
+/**
+ * polkit_config_unref:
+ * @pk_config: the object
+ *
+ * Decreases the reference count of the object. If it becomes zero,
+ * the object is freed. Before freeing, reference counts on embedded
+ * objects are decresed by one.
+ **/
void
polkit_config_unref (PolKitConfig *pk_config)
{
@@ -509,6 +546,18 @@ out:
return result;
}
+/**
+ * polkit_config_can_session_do_action:
+ * @pk_config: the PolicyKit context
+ * @action: the type of access to check for
+ * @session: the session in question
+ *
+ * Determine if the /etc/PolicyKit/PolicyKit.conf configuration file
+ * says that a given session can do a given action.
+ *
+ * Returns: A #PolKitResult - returns #POLKIT_RESULT_UNKNOWN if there
+ * was no match in the configuration file.
+ */
PolKitResult
polkit_config_can_session_do_action (PolKitConfig *pk_config,
PolKitAction *action,
@@ -522,6 +571,18 @@ polkit_config_can_session_do_action (Pol
return result;
}
+/**
+ * polkit_config_can_caller_do_action:
+ * @pk_config: the PolicyKit context
+ * @action: the type of access to check for
+ * @caller: the caller in question
+ *
+ * Determine if the /etc/PolicyKit/PolicyKit.conf configuration file
+ * says that a given caller can do a given action.
+ *
+ * Returns: A #PolKitResult - returns #POLKIT_RESULT_UNKNOWN if there
+ * was no match in the configuration file.
+ */
PolKitResult
polkit_config_can_caller_do_action (PolKitConfig *pk_config,
PolKitAction *action,
diff --git a/polkit/polkit-context.c b/polkit/polkit-context.c
index 987b6e9..c54e1af 100644
--- a/polkit/polkit-context.c
+++ b/polkit/polkit-context.c
@@ -48,14 +48,30 @@
* SECTION:polkit
* @short_description: Centralized policy management.
*
- * polkit is a C library for centralized policy management.
+ * libpolkit is a C library for centralized policy management.
**/
/**
* SECTION:polkit-context
* @short_description: Context.
*
- * This class is used to represent the interface to PolicyKit.
+ * This class is used to represent the interface to PolicyKit - it is
+ * used by Mechanisms that use PolicyKit for making
+ * decisions. Typically, it's used as a singleton:
+ *
+ * <itemizedlist>
+ * <listitem>The mechanism starts up and uses polkit_context_new() to create a new context</listitem>
+ * <listitem>If the mechanism is a long running daemon, it should use polkit_context_set_config_changed() to register a callback when configuration changes. This is useful if, for example, the mechanism needs to revise decisions based on earlier answers from libpolkit. For example, a daemon that manages permissions on <literal>/dev</literal> may want to add/remove ACL's when configuration changes; for example, the system administrator could have changed the PolicyKit configuration file <literal>/etc/PolicyKit/PolicyKit.conf</literal> such that some user is now privileged to access a specific device.</listitem>
+ * <listitem>If polkit_context_set_config_changed() is used, the mechanism must also use polkit_context_set_io_watch_functions() to integrate libpolkit into the mainloop.</listitem>
+ * <listitem>The mechanism needs to call polkit_context_init() such that libpolkit can load configuration files and properly initialize.</listitem>
+ * <listitem>Whenever the mechanism needs to make a decision whether a caller is allowed to make a perform some action, the mechanism prepares a #PolKitAction and #PolKitCaller object (or #PolKitSession if applicable) and calls polkit_context_can_caller_do_action() (or polkit_context_can_session_do_action() if applicable). The mechanism may use the libpolkit-dbus library (specifically the polkit_caller_new_from_dbus_name() or polkit_caller_new_from_pid() functions) but may opt, for performance reasons, to construct #PolKitCaller (or #PolKitSession if applicable) from it's own cache of information.</listitem>
+ * <listitem>The mechanism will get a #PolKitResult object back that describes whether it should carry out the action. This result stems from a number of sources, see the PolicyKit specification document for details.</listitem>
+ * <listitem>If the result is #POLKIT_RESULT_YES, the mechanism should carry out the action. If the result is not #POLKIT_RESULT_YES nor #POLKIT_RESULT_UNKNOWN (this would never be returned but is mentioned here for completeness), the mechanism should throw an expcetion to the caller detailing the #PolKitResult as a textual string using polkit_result_to_string_representation(). For example, if the mechanism is using D-Bus it could throw an com.some-mechanism.DeniedByPolicy exception with the #PolKitResult textual representation in the detail field. Then the caller can interpret this exception and then act on it (for example it can attempt to gain that privilege).</listitem>
+ * </itemizedlist>
+ *
+ * For more information about using PolicyKit in mechanisms and
+ * callers, refer to the PolicyKit-gnome project which includes a
+ * sample application on how to use this in the GNOME desktop.
**/
/**
@@ -317,7 +333,8 @@ polkit_context_set_io_watch_functions (P
* @pk_context: the context
*
* Set whether policy descriptions should be loaded. By default these
- * are not loaded to keep memory use down.
+ * are not loaded to keep memory use down. TODO: specify whether they
+ * are localized and how.
*
* This method must be called before polkit_context_init().
**/
diff --git a/polkit/polkit-grant-database.c b/polkit/polkit-grant-database.c
index 88685f2..737e7ac 100644
--- a/polkit/polkit-grant-database.c
+++ b/polkit/polkit-grant-database.c
@@ -40,6 +40,13 @@
#include <polkit/polkit-grant-database.h>
+/**
+ * SECTION:polkit-grant-database
+ * @short_description: Local grant database
+ *
+ * This private class is used to represent the grant database and provides read/write functions to access it.
+ **/
+
/* TODO FIXME: this is Linux specific */
static unsigned long long
get_start_time_for_pid (pid_t pid)
diff --git a/polkit/polkit-result.c b/polkit/polkit-result.c
index 3c70750..6d5d4b3 100644
--- a/polkit/polkit-result.c
+++ b/polkit/polkit-result.c
@@ -69,7 +69,11 @@ static const struct {
* polkit_result_to_string_representation:
* @result: the given result to get a textual representation of
*
- * Gives a textual representation of a #PolKitResult object.
+ * Gives a textual representation of a #PolKitResult object. This
+ * string is not suitable for displaying to an end user (it's not
+ * localized for starters) but is useful for serialization as it can
+ * be converted back to a #PolKitResult object using
+ * polkit_result_from_string_representation().
*
* Returns: string representing the result (do not free) or #NULL if the given result is invalid
**/
@@ -89,7 +93,8 @@ polkit_result_to_string_representation (
* @string: textual representation of a #PolKitResult object
* @out_result: return location for #PolKitResult
*
- * Given a textual representation of a #PolKitResult object, find the #PolKitResult value.
+ * Given a textual representation of a #PolKitResult object, find the
+ * #PolKitResult value.
*
* Returns: TRUE if the textual representation was valid, otherwise FALSE
**/
More information about the hal-commit
mailing list