luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-04-28 01:56:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Move GIO-specific information to the GIO docs

Browse Source
This commit is contained in:
Matthias Clasen 2012-09-11 23:14:39 -04:00
parent fc7dc33113
commit 47a3b76ac5
2 changed files with 101 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/reference/gio/overview.xml
View File

@ -6,11 +6,13 @@
<para> <para>
GIO is striving to provide a modern, easy-to-use VFS API that sits 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 at the right level in the library stack, as well as other generally
shortcomings of GnomeVFS and provide an API that is so good that useful APIs for desktop applications (such as networking and
developers prefer it over raw POSIX calls. Among other things D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
that means using GObject. It also means not cloning the POSIX and provide an API that is so good that developers prefer it over raw
API, but providing higher-level, document-centric interfaces. 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>
<para> <para>
@ -168,6 +170,97 @@
</para> </para>
</chapter> </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> <chapter>
<title>Compiling GIO applications</title> <title>Compiling GIO applications</title>
@ -195,7 +288,7 @@
</para> </para>
</chapter> </chapter>
<chapter> <chapter id="running-gio-apps">
<title>Running GIO applications</title> <title>Running GIO applications</title>
<para> <para>

58
docs/reference/glib/programming.xml
View File

@ -45,30 +45,6 @@ support multithreaded applications.
<refsect2> <refsect2>
<title>Security</title> <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> <para>
When writing code that runs with elevated privileges, it is important When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an 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 When it comes to GLib and its associated libraries, GLib and
GObject are generally fine to use in code that runs with elevated GObject are generally fine to use in code that runs with elevated
privileges; they don't load modules (executable code in shared objects) privileges; they don't load modules (executable code in shared objects)
or run other programs 'behind your back'. or run other programs 'behind your back'. GIO has to be used
</para> carefully in privileged programs, see the <unlink url="http://developer.gnome.org/gio/stable/ch02.html">GIO documentation</ulink> for details.
<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>
</para> </para>
</refsect2> </refsect2>