<chapter id="howitworks">
<title>How it works</title>

<sect1 id="howitworks-overview">
<title>Overview</title>

<para>PolicyKit has a simple way of working, but it requires some
design changes from the applications that want to use it to request
passwords.</para>
</sect1>

<sect1 id="howitworks-problem">
<title>The problem</title>

<para>In GUI applications the common way to gain root privileges is to start
it as root, but there are several security risks in doing this method and
it does not allow a good actions mapping. There is no way to separate actions
like package-install of system-upgrading.
All the users who want to use it must have the root password. Another common
approach is using sudo but once you start an application with sudo you will
have all the rights the root user will have.
If for example the GUI application has a dialog to select files that dialog
is running as root which means that the user might be able to delete any file
on his machine or even coping others user files.
</para>
</sect1>

<sect1 id="howitworks-solution">
<title>The solution</title>

<para>With PolicyKit this problem is solved. The application in question
just need to separate the privileged code into another application,
often called helper (which will not have a GUI), then maps the desired
actions into a <quote>.policy</quote> file. PolicyKit then loads this file
and it can now authenticate applications to use those actions.
The use of &DBus; activated applications is the best if not the only,
way of putting an helper application to run with root privileges.</para>

<para>With this design the GUI application calls an action of the helper
application through &DBus;, which will start the helper with root privileges,
and informing it which action was requested and which application has requested
it. The helper application now calls the PolicyKit agent to see if that application
can do the given task, the helper should report if it could do the requested action.
In case the helper saw that the application didn't have enough rights the GUI
will then need to ask PolicyKit to obtain an authorization.</para>

<para>When PolicyKit receives the request to obtain an authorization it issues an
available Agent, which might happen to be &policykit-kde; if available. After a successful
authentication the GUI application needs to call the helper repeating the
same operation again.</para>
</sect1>

</chapter>
