diff --git a/docs/reference/gio/overview.xml b/docs/reference/gio/overview.xml index 29087ca48..109392d65 100644 --- a/docs/reference/gio/overview.xml +++ b/docs/reference/gio/overview.xml @@ -6,11 +6,13 @@ 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. @@ -168,6 +170,97 @@ + + Writing GIO applications + + + The information in the GLib documentation about writing GLib + applications is generally applicable when writing GIO applications. + + + Threads + + + 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 thread-default + main context to execute callbacks of asynchronous + methods in the same context in which the operation was started. + + + + + Security + + +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: + + +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. polkit is a framework that allows this. + + +Use a small helper that is executed with elevated privileges via +pkexec. pkexec is a small program launcher that is part of polkit. + + +Use a small helper that is executed with elevated privileges by +being suid root. + + +None of these approaches is the clear winner, they all have their +advantages and disadvantages. + + + +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, +Secure Programming for Linux and Unix HOWTO. + + + +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. + + + +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: + + +Clear the environment, e.g. using the clearenv() +function. +David Wheeler has a good explanation for why it is +important to sanitize the environment. +See +for a list of all environment variables affecting GIO. In particular, +PATH (used to locate binaries), GIO_EXTRA_MODULES (used to locate loadable modules) and DBUS_{SYSTEM,SESSION}_BUS_ADDRESS (used to locate the D-Bus system and session bus) are important. + + +Don't use GVfs, by setting GIO_USE_VFS=local 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. + + + + + + + + Compiling GIO applications @@ -195,7 +288,7 @@ - + Running GIO applications diff --git a/docs/reference/glib/programming.xml b/docs/reference/glib/programming.xml index a46895859..7c0180144 100644 --- a/docs/reference/glib/programming.xml +++ b/docs/reference/glib/programming.xml @@ -45,30 +45,6 @@ support multithreaded applications. Security - -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: - - -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. polkit is a framework that allows this. - - -Use a small helper that is executed with elevated privileges via -pkexec. pkexec is a small program launcher that is part of polkit. - - -Use a small helper that is executed with elevated privileges by -being suid root. - - -None of these approaches is the clear winner, they all have their -advantages and disadvantages. - - 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'. - - - -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. - - - -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: - - -Clear the environment, e.g. using the clearenv() -function. -David Wheeler has a good explanation for why it is -important to sanitize the environment. -See the GIO documentation -for a list of all environment variables affecting GIO. In particular, -PATH (used to locate binaries), GIO_EXTRA_MODULES (used to locate loadable modules) and DBUS_{SYSTEM,SESSION}_BUS_ADDRESS (used to locate the D-Bus system and session bus) are important. - - -Don't use GVfs, by setting GIO_USE_VFS=local 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. - - +or run other programs 'behind your back'. GIO has to be used +carefully in privileged programs, see the GIO documentation for details.