docs/html/gsignond-plugin-loaders-overview.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>gsignond API Reference Manual: Overview of GSignond's authentication plugin subsystem</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="index.html" title="gsignond API Reference Manual">
   8 <link rel="up" href="ch03.html" title="Authentication plugins, plugin loaders and D-Bus IPC">
   9 <link rel="prev" href="ch03.html" title="Authentication plugins, plugin loaders and D-Bus IPC">
  10 <link rel="next" href="ch04.html" title="GSignond API for writing GLib-based authentication plugins">
  11 <meta name="generator" content="GTK-Doc V1.20 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="ch03.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="ch04.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry">
  23 <a name="gsignond-plugin-loaders-overview"></a><div class="titlepage"></div>
  24 <div class="refsect1">
  25 <a name="intro"></a><h2>Introduction</h2>
  26 <p>
  27             For security and flexibility reasons, authentication sessions in GSSO are performed
  28             by authentication plugins that run in separate processes and communicate with
  29             the GSSO daemon using D-Bus IPC. This page describes that IPC, and the
  30             options that plugin writers have for implementing additional plugins.
  31         </p>
  32 </div>
  33 <div class="refsect1">
  34 <a name="id-1.4.2.3"></a><h2>GLib plugins</h2>
  35 <p>
  36             The standard, most simple way to write plugins is by using GLib to
  37             implement <a class="link" href="GSignondPlugin.html" title="GSignondPlugin">GSignondPlugin</a> interface,
  38             package the code as a shared library, and install the library into
  39             gsso's standard location for GLib plugins. This approach is described
  40            in detail in <a class="link" href="GSignondPlugin.html" title="GSignondPlugin">GSignondPlugin chapter</a>.
  41         </p>
  42 </div>
  43 <div class="refsect1">
  44 <a name="id-1.4.2.4"></a><h2>Plugin loaders</h2>
  45 <p>
  46             If using GLib to implement authentication plugins is undesirable or
  47             impossible, you can provide a binary that implements a GSSO plugin
  48             loader, which should be installed in
  49             <span class="command"><strong>pkg-config gsignond --variable=pluginloadersdir</strong></span>.
  50         </p>
  51 <p>
  52             The GLib plugin loader that manages GLib-based plugins is a reference
  53             implementation for such a loader. It is possible to fork and tweak its
  54             code (as long as the IPC protocol, described below, is preserved),
  55             or it's also possible to write such a loader from scratch. The source
  56             code for the GLib plugin loader can be found
  57             <a class="ulink" href="https://code.google.com/p/accounts-sso/source/browse/?repo=gsignond#git%2Fsrc%2Fgplugind" target="_top">
  58             here</a>.
  59         </p>
  60 </div>
  61 <div class="refsect1">
  62 <a name="id-1.4.2.5"></a><h2>Plugin loaders' command line options</h2>
  63 <p>
  64             The plugin loader binary should implement the following command line options:
  65             </p>
  66 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  67 <li class="listitem">
  68 <code class="systemitem">--list-plugins</code> command line option
  69                     must be supported. The plugin loader binary should then list
  70                     available plugin names, one name per line, for example:
  71                     <div class="literallayout"><p><br>
  72                     <strong class="userinput"><code>&gt; gsignond-plugind --list-plugins</code></strong><br>
  73                     password<br>
  74                     ssotest<br>
  75                     digest<br>
  76                     </p></div>
  77                     NOTE: it is recommended that plugin names are either hardcoded
  78                     in the plugin loader, or determined from plugin filenames in
  79                     the filesystem. It's less secure to determine the names by
  80                     loading the plugins' code and calling into each plugin.
  81                 </li>
  82 <li class="listitem">
  83 <code class="systemitem">--load-plugin=name</code> command line option
  84                     must also be supported. The plugin loader binary should then
  85                     load and prepare the plugin with the corresponding name (or
  86                     simply prepare the plugin that is provided within the plugin
  87                     loader itself), and export a d-bus object on standard input and
  88                     output streams that gsso daemon will communicate with. The next
  89                     session describes this in more detail.
  90                 </li>
  91 </ul></div>
  92 <p>
  93         </p>
  94 </div>
  95 <div class="refsect1">
  96 <a name="id-1.4.2.6"></a><h2>Plugin loaders' D-Bus IPC</h2>
  97 <p>
  98             When run with a <code class="systemitem">--load-plugin</code> command line
  99             option, the plugin loader process is expected to export a D-Bus object
 100             on path "/" that implements
 101             <a class="ulink" href="https://code.google.com/p/accounts-sso/source/browse/src/daemon/dbus/interfaces/com.google.code.AccountsSSO.gSingleSignOn.RemotePlugin.xml?repo=gsignond" target="_top">
 102                 this interface</a>.
 103         </p>
 104 <p>
 105             The interface declarations map directly to the plugin API. See
 106             <a class="link" href="GSignondPlugin.html" title="GSignondPlugin">GSignondPlugin</a> interface for
 107             the meaning of various methods, signals and properties.
 108         </p>
 109 <p>
 110             The object is exported on a connection that is formed from standard
 111             input and standard output streams. This is the most secure way
 112             to communicate with the gsso daemon, because these streams are visible
 113             only to the two ends of the connection - the plugin loader process
 114             and the parent process (the gsso daemon).
 115         </p>
 116 <p>
 117             NOTE: at the moment input and output should happen on two separate
 118             streams, the standard input and the standard output respectively.
 119             In the future, gsso will set both streams to the same
 120             bidirectional channel, for compatibility with
 121             <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#transports-exec" target="_top">
 122                 D-Bus' unixexec transport</a>.
 123         </p>
 124 </div>
 125 </div>
 126 <div class="footer">
 127 <hr>
 128           Generated by GTK-Doc V1.20</div>
 129 </body>
 130 </html>