# PolicyKit Overview

## Introduction

PolicyKit provides an authorization API intended to be used by privileged programs (MECHANISMS) offering service to unprivileged programs (CLIENTS). See the PolicyKit-1 manual page for the system architecture and big picture.

## Writing PolicyKit applications

PolicyKit applications are privileged mechanisms using the PolicyKit authority as a decider component. To do this, a mechanism use either the GObject API, the D-Bus API or the pkcheck command to communicate with the PolicyKit Authority.

Note that clients never use the PolicyKit API directly – it is intended solely for privileged mechanisms. If a client needs to disable, modify or remove UI elements to e.g. convey to the user that a certain action cannot be carried out (because e.g. the user is not authorized) or authentication is needed (by e.g. displaying a padlock icon in the UI), the mechanism will need to provide API for this.

As an example of code using the GObject API, see . For an example using the D-Bus API, see .

Querying the Authority

    FIXME: MISSING XINCLUDE CONTENT

Accessing the Authority via D-Bus

    FIXME: MISSING XINCLUDE CONTENT

## Writing PolicyKit Authentication Agents

Authentication agents are provided by desktop environments. When an user session starts, the agent registers with the PolicyKit Authority using the RegisterAuthenticationAgent() method. When services are needed, the authority will invoke methods on the org.freedesktop.PolicyKit1.AuthenticationAgent D-Bus interface. Once the user is authenticated, (a privileged part of) the agent invokes the AuthenticationAgentResponse() method. Note that the PolicyKit Authority itself does not care how the agent authenticates the user.

The libpolkit-agent-1 library provides helpers to make it easy to build authentication agents that use the native authentication system e.g. pam`(8)`.

## Extending PolicyKit

PolicyKit exports a number of extension points to replace/customize behavior of the PolicyKit daemon. Note that all extensions run with super user privileges in the same process as the PolicyKit daemon.

The PolicyKit daemons loads extensions from the `&extensiondir;` directory. See the GIO Extension Point documentation for more information about the extension system used by PolicyKit.

The following extension points are currently defined by PolicyKit:

POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME

Allows replacing the Authority – the entity responsible for making authorization decisions. Implementations of this extension point must be derived from the PolkitBackendAuthority class. See the `src/nullbackend/` directory in the PolicyKit sources for an example.

POLKIT_BACKEND_ACTION_LOOKUP_EXTENSION_POINT_NAME

Allows a mechanism to customize the contents of authentication dialogs. Implementations of this extension point must implement the #PolkitBackendActionLookup interface.