GDBusAuthObserver: Document how to restrict authentication to EXTERNAL

This is simpler and more robust than DBUS_COOKIE_SHA1, which relies
on assumptions about random numbers and a secure home directory.

Signed-off-by: Simon McVittie <smcv@collabora.com>

1 files changed, 24 insertions, 0 deletions

diff --git a/gio/gdbusauthobserver.c b/gio/gdbusauthobserver.c
index 2cf995f0c..4590ffcae 100644
--- a/gio/gdbusauthobserver.c
+++ b/gio/gdbusauthobserver.c
@@ -39,6 +39,30 @@
  * signals you are interested in. Note that new signals may be added
  * in the future
  *
+ * ## Controlling Authentication Mechanisms
+ *
+ * By default, a #GDBusServer or server-side #GDBusConnection will allow
+ * any authentication mechanism to be used. If you only
+ * want to allow D-Bus connections with the `EXTERNAL` mechanism,
+ * which makes use of credentials passing and is the recommended
+ * mechanism for modern Unix platforms such as Linux and the BSD family,
+ * you would use a signal handler like this:
+ *
+ * |[<!-- language="C" -->
+ * static gboolean
+ * on_allow_mechanism (GDBusAuthObserver *observer,
+ *                     const gchar       *mechanism,
+ *                     gpointer           user_data)
+ * {
+ *   if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
+ *     {
+ *       return TRUE;
+ *     }
+ *
+ *   return FALSE;
+ * }
+ * ]|
+ *
  * ## Controlling Authorization # {#auth-observer}
  *
  * By default, a #GDBusServer or server-side #GDBusConnection will accept