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
/**
* 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
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)
{
#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,
struct ConfigNode;
typedef struct ConfigNode ConfigNode;
+/**
+ * PolKitConfig:
+ *
+ * This class represents the system-wide configuration file for PolicyKit.
+ **/
struct PolKitConfig
{
int refcount;
GSList *children;
};
+
static ConfigNode *
config_node_new (void)
{
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)
{
return NULL;
}
+/**
+ * polkit_config_ref:
+ * @pk_config: the object
+ *
+ * Increase reference count.
+ *
+ * Returns: the object
+ **/
PolKitConfig *
polkit_config_ref (PolKitConfig *pk_config)
{
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)
{
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,
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,
* 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.
**/
/**
* @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().
**/
#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)
* 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
**/
* @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
**/