~ubuntu-branches/debian/sid/glib2.0/sid

    at the right level in the library stack, as well as other generally

    useful APIs for desktop applications (such as networking and

    D-Bus support). The goal is to overcome the shortcomings of GnomeVFS

    and provide an API that is so good that developers prefer it over raw

    POSIX calls. Among other things that means using GObject. It also means

    not cloning the POSIX API, but providing higher-level, document-centric

    interfaces.

    <title>Writing GIO applications</title>

 

    <para>

      The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib

      applications is generally applicable when writing GIO applications.

    </para>

 

    <simplesect><title>Threads</title>

 

    <para>

       GDBus has its own private worker thread, so applications using

       GDBus have at least 3 threads. GIO makes heavy use of the concept

       of a <link linkend="g-main-context-push-thread-default">thread-default

       main context</link> to execute callbacks of asynchronous

       methods in the same context in which the operation was started.

    </para>

 

    </simplesect>

 

    <simplesect><title>Security</title>

 

<para>

When your program needs to carry out some privileged operation (say,

create a new user account), there are various ways in which you can go

about this:

<itemizedlist>

<listitem><para>

Implement a daemon that offers the privileged operation. A convenient

way to do this is as a D-Bus system-bus service. The daemon will probably

need ways to check the identity and authorization of the caller before

executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.

</para></listitem>

<listitem><para>

Use a small helper that is executed with elevated privileges via

pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.

</para></listitem>

<listitem><para>

Use a small helper that is executed with elevated privileges by

being suid root.

</para></listitem>

</itemizedlist>

None of these approaches is the clear winner, they all have their

advantages and disadvantages.

</para>

 

<para>

When writing code that runs with elevated privileges, it is important

to follow some basic rules of secure programming. David Wheeler has an

excellent book on this topic,

<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.

</para>

 

<para>

When using GIO in code that runs with elevated privileges, you have to

be careful. GIO has extension points whose implementations get loaded

from modules (executable code in shared objects), which could allow

an attacker to sneak his own code into your application by tricking it

into loading the code as a module. However, GIO will never load modules

from your home directory except when explictly asked to do so via an

environment variable.

</para>

 

<para>

In most cases, your helper program should be so small that you don't

need GIO, whose APIs are largely designed to support full-blown desktop

applications. If you can't resist the convenience of these APIs, here

are some steps you should take:

<itemizedlist>

<listitem><para>

Clear the environment, e.g. using the <function>clearenv()</function>

function.

David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is

important to sanitize the environment.

See <xref linkend="running-gio-apps"/>

for a list of all environment variables affecting GIO. In particular,

<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.

</para></listitem>

<listitem><para>

Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.

The reason to avoid GVfs in security-sensitive programs is that it uses

many libraries which have not necessarily been audited for security problems.

Gvfs is also heavily distributed and relies on a session bus to be present.

</para></listitem>

</itemizedlist>

</para>

 

    </simplesect>

 

  </chapter>

 

  <chapter>

  <chapter id="running-gio-apps">

      <title><envar>GIO_USE_FILE_MONITOR</envar></title>

 

      <para>

        This variable can be set to the name of a #GFileMonitor

        implementation to override the default for debugging purposes.

        The #GFileMonitor implementation for local files that is included

        in GIO on Linux has the name "inotify", others that are built

        are built as modules (depending on the platform) are called

        "fam" and "fen".

      </para>

    </formalpara>

 

    <formalpara>