docs/plugin-loaders-overview.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4 ]>
   5 <refentry id="gsignond-plugin-loaders-overview">
   6   <refmeta>
   7     <refentrytitle>Overview of GSignond's authentication plugin subsystem</refentrytitle>
   8     <manvolnum>3</manvolnum>
   9     <refmiscinfo>GSignond</refmiscinfo>
  10   </refmeta>
  11
  12     <refsect1 id="intro">
  13         <title>Introduction</title>
  14         <para>
  15             For security and flexibility reasons, authentication sessions in GSSO are performed
  16             by authentication plugins that run in separate processes and communicate with
  17             the GSSO daemon using D-Bus IPC. This page describes that IPC, and the
  18             options that plugin writers have for implementing additional plugins.
  19         </para>
  20     </refsect1>
  21
  22     <refsect1>
  23         <title>GLib plugins</title>
  24         <para>
  25             The standard, most simple way to write plugins is by using GLib to
  26             implement <link linkend="GSignondPlugin">GSignondPlugin</link> interface,
  27             package the code as a shared library, and install the library into
  28             gsso's standard location for GLib plugins. This approach is described
  29            in detail in <link linkend="GSignondPlugin">GSignondPlugin chapter</link>.
  30         </para>
  31     </refsect1>
  32
  33     <refsect1>
  34         <title>Plugin loaders</title>
  35         <para>
  36             If using GLib to implement authentication plugins is undesirable or
  37             impossible, you can provide a binary that implements a GSSO plugin
  38             loader, which should be installed in
  39             <command>pkg-config gsignond --variable=pluginloadersdir</command>.
  40         </para>
  41         <para>
  42             The GLib plugin loader that manages GLib-based plugins is a reference
  43             implementation for such a loader. It is possible to fork and tweak its
  44             code (as long as the IPC protocol, described below, is preserved),
  45             or it's also possible to write such a loader from scratch. The source
  46             code for the GLib plugin loader can be found
  47             <ulink url="https://code.google.com/p/accounts-sso/source/browse/?repo=gsignond#git%2Fsrc%2Fgplugind">
  48             here</ulink>.
  49         </para>
  50     </refsect1>
  51
  52     <refsect1>
  53         <title>Plugin loaders' command line options</title>
  54         <para>
  55             The plugin loader binary should implement the following command line options:
  56             <itemizedlist>
  57                 <listitem>
  58                     <systemitem>--list-plugins</systemitem> command line option
  59                     must be supported. The plugin loader binary should then list
  60                     available plugin names, one name per line, for example:
  61                     <literallayout>
  62                     <userinput>> gsignond-plugind --list-plugins</userinput>
  63                     password
  64                     ssotest
  65                     digest
  66                     </literallayout>
  67                     NOTE: it is recommended that plugin names are either hardcoded
  68                     in the plugin loader, or determined from plugin filenames in
  69                     the filesystem. It's less secure to determine the names by
  70                     loading the plugins' code and calling into each plugin.
  71                 </listitem>
  72                 <listitem>
  73                     <systemitem>--load-plugin=name</systemitem> command line option
  74                     must also be supported. The plugin loader binary should then
  75                     load and prepare the plugin with the corresponding name (or
  76                     simply prepare the plugin that is provided within the plugin
  77                     loader itself), and export a d-bus object on standard input and
  78                     output streams that gsso daemon will communicate with. The next
  79                     session describes this in more detail.
  80                 </listitem>
  81             </itemizedlist>
  82         </para>
  83     </refsect1>
  84
  85     <refsect1>
  86         <title>Plugin loaders' D-Bus IPC</title>
  87         <para>
  88             When run with a <systemitem>--load-plugin</systemitem> command line
  89             option, the plugin loader process is expected to export a D-Bus object
  90             on path "/" that implements
  91             <ulink url="https://code.google.com/p/accounts-sso/source/browse/src/daemon/dbus/interfaces/com.google.code.AccountsSSO.gSingleSignOn.RemotePlugin.xml?repo=gsignond">
  92                 this interface</ulink>.
  93         </para>
  94         <para>
  95             The interface declarations map directly to the plugin API. See
  96             <link linkend="GSignondPlugin">GSignondPlugin</link> interface for
  97             the meaning of various methods, signals and properties.
  98         </para>
  99         <para>
 100             The object is exported on a connection that is formed from standard
 101             input and standard output streams. This is the most secure way
 102             to communicate with the gsso daemon, because these streams are visible
 103             only to the two ends of the connection - the plugin loader process
 104             and the parent process (the gsso daemon).
 105         </para>
 106         <para>
 107             NOTE: at the moment input and output should happen on two separate
 108             streams, the standard input and the standard output respectively.
 109             In the future, gsso will set both streams to the same
 110             bidirectional channel, for compatibility with
 111             <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#transports-exec">
 112                 D-Bus' unixexec transport</ulink>.
 113         </para>
 114     </refsect1>
 115 </refentry>