mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-13 07:56:17 +01:00
Move GIO-specific information to the GIO docs
This commit is contained in:
Matthias Clasen
parent
fc7dc33113
commit
47a3b76ac5
@ -6,11 +6,13 @@
|
||||
|
||||
<para>
|
||||
GIO is striving to provide a modern, easy-to-use VFS API that sits
|
||||
at the right level in the library stack. 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.
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -168,6 +170,97 @@
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<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>
|
||||
<title>Compiling GIO applications</title>
|
||||
|
||||
@ -195,7 +288,7 @@
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter>
|
||||
<chapter id="running-gio-apps">
|
||||
<title>Running GIO applications</title>
|
||||
|
||||
<para>
|
||||
|
||||
@ -45,30 +45,6 @@ support multithreaded applications.
|
||||
<refsect2>
|
||||
<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
|
||||
@ -80,38 +56,8 @@ excellent book on this topic,
|
||||
When it comes to GLib and its associated libraries, GLib and
|
||||
GObject are generally fine to use in code that runs with elevated
|
||||
privileges; they don't load modules (executable code in shared objects)
|
||||
or run other programs 'behind your back'.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When using GIO, you have to be more careful, since GIO has extension
|
||||
points whose implementations get loaded from modules. 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 the GIO <ulink url="http://developer.gnome.org/gio/stable/ch03.html">documentation</ulink>
|
||||
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>
|
||||
or run other programs 'behind your back'. GIO has to be used
|
||||
carefully in privileged programs, see the <unlink url="http://developer.gnome.org/gio/stable/ch02.html">GIO documentation</ulink> for details.
|
||||
</para>
|
||||
|
||||
</refsect2>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user