From a9860cf824a6503e09ea43070178676b39ca92f2 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Tue, 24 Jul 2007 17:42:08 -0400 Subject: [PATCH] fix up some of the docs --- 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(-) 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_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) { @@ -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 (PolKitConfig *pk_config, 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: + * + * + * The mechanism starts up and uses polkit_context_new() to create a new context + * 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 /dev may want to add/remove ACL's when configuration changes; for example, the system administrator could have changed the PolicyKit configuration file /etc/PolicyKit/PolicyKit.conf such that some user is now privileged to access a specific device. + * 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. + * The mechanism needs to call polkit_context_init() such that libpolkit can load configuration files and properly initialize. + * 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. + * 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. + * 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). + * + * + * 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 (PolKitContext *pk_ * @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 +/** + * 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 (PolKitResult result) * @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 **/ -- 2.7.4