Development/Tutorials/PolicyKit/Introduction

Introduction to PolicyKit

Tutorial Series	PolicyKit Tutorial
Previous	D-Bus activation, Basic D-Bus knowledge, Basic polkit-qt knowledge
What's Next	Using the caller-helper model to perform actions as root
Further Reading	None

WARNING: THIS TUTORIAL IS OBSOLETE. PLEASE USE THE NEW KAUTH FRAMEWORK INSTEAD

The new tutorial series can be found here, please use KAuth when developing with KDE: it's easier, more integrated, and portable

What is PolicyKit

PolicyKit is an authentication system, that lets developers set a policy on specific actions. It works in strict correlation with D-Bus and ConsoleKit, and it is really useful in cases where you need to perform privileged actions

Who is this tutorial for?

This tutorial is aimed to developers who want their application to perform privileged actions in a secure, consistent and easy way.

PolicyKit and KDE

PolicyKit is closely integrated with KDE starting from version 4.3. In kdebase-workspace we have an authorization manager and an authentication agent. What matters the most, though, is polkit-qt library, in kdesupport, that lets us use the PolicyKit library through a nice Qt-styled API. In this tutorial we will be using it as our main development resource.

Prerequisites

Your application does not need very special prerequisites to be integrated with PolicyKit. Console applications or libraries can also link to polkit-qt-core, that doesn't add a dependency to QtGui.

As a developer, you probably need to read the Polkit-qt api documentation, that is a fundamental compound of this tutorial. A fair knowledge of D-Bus (have a look at the D-Bus tutorial series for that) can make your workflow better.

Special files used by PolicyKit

Before you start diving into PolicyKit integration, you have to know how a .policy file is made. Those files contain a definition of actions carried out by your application that require authorization by PolicyKit. So let's suppose we are creating the application foo that can do action1, that requires authentication as the current user, and action2, that requires authentication as an administrator. Our policy file will be named org.kde.foo.policy and will look like this:

<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE policyconfig PUBLIC

"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">

<policyconfig>

 <action id="org.kde.foo.action1">
   <description>Action number one</description>
   <message>Prevents from doing action one</message>
   <defaults>
     <allow_inactive>no</allow_inactive>
     <allow_active>auth_self</allow_active>
   </defaults>
 </action>

 <action id="org.kde.foo.action2">
   <description>Action number two</description>
   <message>Prevents from doing action two</message>
   <defaults>
     <allow_inactive>no</allow_inactive>
     <allow_active>auth_admin</allow_active>
   </defaults>
 </action>

</policyconfig>

Let's see how we wrote it:

action id is the unique identifier for our action. It is a nice convenience to set it as <your app's dbus interface>.<action name>
description is what your action actually does
message is the message that will be displayed when authorization or a negative result is shown to the user. It starts usually with prevents, as the string that will be displayed will be "System policy <message>".
under defaults we usually have to set 2 parameters: allow_inactive and allow_active. Those refer to the active/inactive console in the system. It is a good practice to set auth_inactive to no. Defaults set the default policy for this action in the specified cases. It can be one of:
1. auth_self if authentication as the current user is required
2. auth_admin if authentication as an administrator is required
You can also append to those:
1. _keep_session if you want the auth to be retained for the whole session
2. _keep_always if you want the auth to be retained indefinitely
3. _one_shot if you want the auth to be valid for performing the action just a single time
So, for example, auth_admin_one_shot will make the authentication as an administrator required to perform the action, and the authentication will be revoked after having performed the action

This is a very simple overview on .policy files that should be enough for most needs, should you need some more information, you can consult PolicyKit reference manual.

How to use Polkit-qt

Polkit-qt is splitted into 2 libraries, one for working without GUI interaction (-core), and one for working with it (-gui). It also includes some nice additions to make working with helpers easier, as you will see in the next tutorial. Let's see how to use Polkit-qt

FindPolkitQt.cmake

You will find this file into polkit-qt source. This file not only defines the dbus_add_activation_system_service macro, that will be extremely useful later, but also lets you find and link against -core, -gui or both.

Polkit-qt-core

Polkit-qt-core is composed by Auth and Context. The first is a namespace that lets you easily obtain and check for authorizations, while Context lets you retrieve informations about PolicyKit context. Please refer to polkit-qt docs for more details.

Polkit-qt-gui

Polkit-qt-core is composed by Action, ActionButton and ActionButtons. They are simply wrappers around QAction and QAbstractButton that let you integrate those two elements with a PolicyKit action. The library will take care not only of obtaining and notify you upon authorization, but also to change the GUI elements (text, icon, etc...) accordingly to the result PolicyKit streams to you.

More reference

The api docs for Polkit-qt are really detailed and a strongly advised read. Even if in the next tutorial we'll show you how to use Polkit-qt in the most common case, having some more knowledge on it will surely help you in advanced uses.

Integrating with the application

In the next tutorial, we'll see how to obtain root privileges with an helper, using some of the knowledge we have gathered now