[glib: 4/7] gdebugcontroller: Add some more documentation

[Philip Withnall <pwithnall src gnome org>]

commit 6d5953ee4835464a37cb7488543b9535edb6122e
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu Feb 10 19:24:17 2022 +0000

    gdebugcontroller: Add some more documentation
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #1190

 gio/gdebugcontroller.c     |  4 ++
 gio/gdebugcontrollerdbus.c | 99 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)
---
diff --git a/gio/gdebugcontroller.c b/gio/gdebugcontroller.c
index 13808d500..c61561621 100644
--- a/gio/gdebugcontroller.c
+++ b/gio/gdebugcontroller.c
@@ -44,6 +44,10 @@
  * default. Application code may connect to the #GObject::notify signal for it
  * to control other parts of its debug infrastructure as necessary.
  *
+ * If your application or service is using the default GLib log writer function,
+ * creating one of the built-in implementations of #GDebugController should be
+ * all that’s needed to dynamically enable or disable debug output.
+ *
  * Since: 2.72
  */
 
diff --git a/gio/gdebugcontrollerdbus.c b/gio/gdebugcontrollerdbus.c
index d58b03c76..e64390654 100644
--- a/gio/gdebugcontrollerdbus.c
+++ b/gio/gdebugcontrollerdbus.c
@@ -42,6 +42,105 @@
  * #GDebugControllerDBus:connection once it’s initialized. The object will be
  * unregistered when the last reference to the #GDebugControllerDBus is dropped.
  *
+ * This D-Bus object can be used by remote processes to enable or disable debug
+ * output in this process. Remote processes calling
+ * `org.gtk.Debugging.SetDebugEnabled()` will affect the value of
+ * #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled().
+ * default.
+ *
+ * By default, all processes will be able to call `SetDebugEnabled()`. If this
+ * process is privileged, or might expose sensitive information in its debug
+ * output, you may want to restrict the ability to enable debug output to
+ * privileged users or processes.
+ *
+ * One option is to install a D-Bus security policy which restricts access to
+ * `SetDebugEnabled()`, installing something like the following in
+ * `$datadir/dbus-1/system.d/`:
+ * |[<!-- language="XML" -->
+ * <?xml version="1.0"?> <!--*-nxml-*-->
+ * <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ *      "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd";>
+ * <busconfig>
+ *   <policy user="root">
+ *     <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ *   </policy>
+ *   <policy context="default">
+ *     <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ *   </policy>
+ * </busconfig>
+ * ]|
+ *
+ * This will prevent the `SetDebugEnabled()` method from being called by all
+ * except root. It will not prevent the `DebugEnabled` property from being read,
+ * as it’s accessed through the `org.freedesktop.DBus.Properties` interface.
+ *
+ * Another option is to use polkit to allow or deny requests on a case-by-case
+ * basis, allowing for the possibility of dynamic authorisation. To do this,
+ * connect to the #GDebugControllerDBus::authorize signal and query polkit in
+ * it:
+ * |[<!-- language="C" -->
+ *   g_autoptr(GError) child_error = NULL;
+ *   g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
+ *   gulong debug_controller_authorize_id = 0;
+ *
+ *   // Set up the debug controller.
+ *   debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, 
&child_error));
+ *   if (debug_controller == NULL)
+ *     {
+ *       g_error ("Could not register debug controller on bus: %s"),
+ *                child_error->message);
+ *     }
+ *
+ *   debug_controller_authorize_id = g_signal_connect (debug_controller,
+ *                                                     "authorize",
+ *                                                     G_CALLBACK (debug_controller_authorize_cb),
+ *                                                     self);
+ *
+ *   static gboolean
+ *   debug_controller_authorize_cb (GDebugControllerDBus  *debug_controller,
+ *                                  GDBusMethodInvocation *invocation,
+ *                                  gpointer               user_data)
+ *   {
+ *     g_autoptr(PolkitAuthority) authority = NULL;
+ *     g_autoptr(PolkitSubject) subject = NULL;
+ *     g_autoptr(PolkitAuthorizationResult) auth_result = NULL;
+ *     g_autoptr(GError) local_error = NULL;
+ *     GDBusMessage *message;
+ *     GDBusMessageFlags message_flags;
+ *     PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE;
+ *
+ *     message = g_dbus_method_invocation_get_message (invocation);
+ *     message_flags = g_dbus_message_get_flags (message);
+ *
+ *     authority = polkit_authority_get_sync (NULL, &local_error);
+ *     if (authority == NULL)
+ *       {
+ *         g_warning ("Failed to get polkit authority: %s", local_error->message);
+ *         return FALSE;
+ *       }
+ *
+ *     if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION)
+ *       flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION;
+ *
+ *     subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));
+ *
+ *     auth_result = polkit_authority_check_authorization_sync (authority,
+ *                                                              subject,
+ *                                                              "com.example.MyService.set-debug-enabled",
+ *                                                              NULL,
+ *                                                              flags,
+ *                                                              NULL,
+ *                                                              &local_error);
+ *     if (auth_result == NULL)
+ *       {
+ *         g_warning ("Failed to get check polkit authorization: %s", local_error->message);
+ *         return FALSE;
+ *       }
+ *
+ *     return polkit_authorization_result_get_is_authorized (auth_result);
+ *   }
+ * ]|
+ *
  * Since: 2.72
  */