Commit a586d960 authored by David Zeuthen's avatar David Zeuthen

initial commit

parent 0b0f5012
FIGURE_FILES = \
polkit-arch.png
if DOCBOOK_DOCS_ENABLED
htmldocdir = $(DOCDIR)/spec
htmldoc_DATA = polkit-spec.html $(FIGURE_FILES)
polkit-spec.html : polkit-spec.xml $(FIGURE_FILES)
$(DOCBOOK) --nochunks polkit-spec.xml -o .
clean-local:
rm -f *~
rm -f polkit-spec.html polkit-spec.xml
endif # DOCBOOK_DOCS_ENABLED
EXTRA_DIST = polkit-spec.html \
polkit-spec.xml.in \
polkit-arch.dia \
$(FIGURE_FILES)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>PolicyKit 0.1 Specification</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"></HEAD
><BODY
CLASS="book"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="BOOK"
><A
NAME="index"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
><A
NAME="AEN2"
>PolicyKit 0.1 Specification</A
></H1
><H3
CLASS="author"
><A
NAME="AEN7"
></A
>David Zeuthen</H3
><DIV
CLASS="affiliation"
><DIV
CLASS="address"
><P
CLASS="address"
><br>
&nbsp;&nbsp;&nbsp;&nbsp;<CODE
CLASS="email"
>&#60;<A
HREF="mailto:david@fubar.dk"
>david@fubar.dk</A
>&#62;</CODE
><br>
&nbsp;&nbsp;</P
></DIV
></DIV
><SPAN
CLASS="releaseinfo"
>Version 0.1<BR></SPAN
><HR></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="#introduction"
>Introduction</A
></DT
><DD
><DL
><DT
><A
HREF="#AEN15"
>About</A
></DT
></DL
></DD
><DT
><A
HREF="#privileges"
>Theory of operation</A
></DT
><DD
><DL
><DT
><A
HREF="#AEN20"
>Privileges</A
></DT
><DT
><A
HREF="#AEN26"
>Architecture</A
></DT
><DT
><A
HREF="#AEN37"
>Example</A
></DT
></DL
></DD
></DL
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="introduction"
></A
>Introduction</H1
><DIV
CLASS="sect1"
><H2
CLASS="sect1"
><A
NAME="AEN15"
>About</A
></H2
><P
>&#13; PolicyKit is a system for enabling unprivileged desktop
applications to invoke privileged methods on system-wide
components in a controlled manner.
</P
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="privileges"
></A
>Theory of operation</H1
><DIV
CLASS="sect1"
><H2
CLASS="sect1"
><A
NAME="AEN20"
>Privileges</A
></H2
><P
>&#13; One major concept of the PolicyKit system is the notion of
privileges; a <I
CLASS="emphasis"
>PolicyKit privilege</I
>
(referred to simply as
<I
CLASS="emphasis"
>privilege</I
> in the following) is something
that a given user may or may not possess. The thinking behind
PolicyKit is that privileged system level components offer
functionality to unprivileged desktop applications as D-BUS
method calls through the system message bus. In order to have
a flexible security policy defining the set of users that are
allowed to invoke a method, the system level component defines
a set of
<I
CLASS="emphasis"
>privileges</I
>.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN26"
>Architecture</A
></H2
><P
>&#13; The PolicyKit system is basically client/server and is
implemented as the
system-wide <TT
CLASS="literal"
>org.freedesktop.PolicyKit</TT
> D-BUS
service. This D-BUS service serves two purposes
</P
><P
></P
><UL
><LI
><P
>&#13; System-level components may used D-BUS methods on this
service to determine if a given caller of their methods
are privileged.
</P
></LI
><LI
><P
>&#13; Desktop level applications may initiate a dialogue with
this service to (temporarily) obtain a privilege through
authorization.
</P
></LI
></UL
><P
>&#13; In addition, the PolicyKit system includes client side
libraries and command-line utilities wrapping the D-BUS API of
the <TT
CLASS="literal"
>org.freedesktop.PolicyKit</TT
> service.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H2
CLASS="sect1"
><A
NAME="AEN37"
>Example</A
></H2
><P
>&#13; As an example, HAL exports the method <TT
CLASS="literal"
>Mount</TT
>
on the
<TT
CLASS="literal"
>org.freedesktop.Hal.Device.Volume</TT
> interface
for each hal device object of
capability <I
CLASS="emphasis"
>volume</I
>. HAL defines a number
of privileges for mounting
including <I
CLASS="emphasis"
>hal-storage-fixed-mount</I
>
and <I
CLASS="emphasis"
>hal-storage-removable-mount</I
>. Depending
on the whether the volume stems from a fixed hard disk or a
hotpluggable/removable drive, HAL requires the calling user to
possess either
the <I
CLASS="emphasis"
>hal-storage-fixed-mount</I
>
or <I
CLASS="emphasis"
>hal-storage-removable-mount</I
> privilege
in order to carry out the <TT
CLASS="literal"
>Mount</TT
> method.
</P
><P
>&#13; Upon a user invoking the <TT
CLASS="literal"
>Mount</TT
> method, HAL
simply asks the <TT
CLASS="literal"
>org.freedesktop.PolicyKit</TT
>
D-BUS service if the calling user posses this privilege and if
this is not the case the <TT
CLASS="literal"
>Mount</TT
> method
throws
the <TT
CLASS="literal"
>org.freedesktop.Hal.Device.PermissionDeniedByPolicy</TT
>
exception. Notably, this exception will tell the caller what
privilege the calling user needs to possess,
e.g. either <I
CLASS="emphasis"
>hal-storage-fixed-mount</I
>
or <I
CLASS="emphasis"
>hal-storage-removable-mount</I
>.
</P
><P
>&#13; Should the <TT
CLASS="literal"
>Mount</TT
> method fail with the
exception <TT
CLASS="literal"
>PermissionDeniedByPolicy</TT
> the
caller now knows what privilege is required. The caller can
now initiate a dialogue with the <TT
CLASS="literal"
>PolicyKit</TT
>
service to obtain this privilege. This conversation is
basically equivalent to a PAM authentication; in fact the
<TT
CLASS="literal"
>PolicyKit</TT
> service uses PAM under the hood
and wraps it in D-BUS calls. For details (like what user to
authenticate as) see XXX. When the caller obtains the
privilege (after successful authentication) he can now
invoke <TT
CLASS="literal"
>Mount</TT
> and after this succeeds he may
tell the <TT
CLASS="literal"
>PolicyKit</TT
> service to release the
privilege for the user as it is no longer needed.
</P
><P
>&#13; Hence, <TT
CLASS="literal"
>PolicyKit</TT
> has the notion of
both <I
CLASS="emphasis"
>permament</I
>
and <I
CLASS="emphasis"
>temporary</I
> privileges. The latter may
even be restricted such that only callers from the D-BUS
connection (remember, D-BUS connections has unique names)
obtaining the privilege may use the obtained privilege.
</P
><P
>&#13; <IMG
SRC="polkit-arch.png">
</P
><P
>&#13; The whole example is outlined in the diagram above.
</P
></DIV
></DIV
></DIV
></BODY
></HTML
>
\ No newline at end of file
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- CVSID: $Id$ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<!-- THIS FILE IS AUTOGENERATED FROM polkit-spec.xml.in -->
<book id="index">
<bookinfo>
<title>PolicyKit 0.1 Specification</title>
<releaseinfo>Version 0.1</releaseinfo>
<date>March 28th, 2006</date> <!-- Update this manually -->
<authorgroup>
<author>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<affiliation>
<address>
<email>david@fubar.dk</email>
</address>
</affiliation>
</author>
</authorgroup>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<sect1>
<title>About</title>
<para>
PolicyKit is a system for enabling unprivileged desktop
applications to invoke privileged methods on system-wide
components in a controlled manner.
</para>
</sect1>
</chapter>
<chapter id="privileges">
<title>Theory of operation</title>
<sect1>
<title>Privileges</title>
<para>
One major concept of the PolicyKit system is the notion of
privileges; a <emphasis>PolicyKit privilege</emphasis>
(referred to simply as
<emphasis>privilege</emphasis> in the following) is something
that a given user may or may not possess. The thinking behind
PolicyKit is that privileged system level components offer
functionality to unprivileged desktop applications as D-BUS
method calls through the system message bus. In order to have
a flexible security policy defining the set of users that are
allowed to invoke a method, the system level component defines
a set of
<emphasis>privileges</emphasis>.
</para>
</sect1>
<sect1>
<title>Architecture</title>
<para>
The PolicyKit system is basically client/server and is
implemented as the
system-wide <literal>org.freedesktop.PolicyKit</literal> D-BUS
service. This D-BUS service serves two purposes
</para>
<itemizedlist>
<listitem>
<para>
System-level components may used D-BUS methods on this
service to determine if a given caller of their methods
are privileged.
</para>
</listitem>
<listitem>
<para>
Desktop level applications may initiate a dialogue with
this service to (temporarily) obtain a privilege through
authorization.
</para>
</listitem>
</itemizedlist>
<para>
In addition, the PolicyKit system includes client side
libraries and command-line utilities wrapping the D-BUS API of
the <literal>org.freedesktop.PolicyKit</literal> service.
</para>
</sect1>
<sect1>
<title>Example</title>
<para>
As an example, HAL exports the method <literal>Mount</literal>
on the
<literal>org.freedesktop.Hal.Device.Volume</literal> interface
for each hal device object of
capability <emphasis>volume</emphasis>. HAL defines a number
of privileges for mounting
including <emphasis>hal-storage-fixed-mount</emphasis>
and <emphasis>hal-storage-removable-mount</emphasis>. Depending
on the whether the volume stems from a fixed hard disk or a
hotpluggable/removable drive, HAL requires the calling user to
possess either
the <emphasis>hal-storage-fixed-mount</emphasis>
or <emphasis>hal-storage-removable-mount</emphasis> privilege
in order to carry out the <literal>Mount</literal> method.
</para>
<para>
Upon a user invoking the <literal>Mount</literal> method, HAL
simply asks the <literal>org.freedesktop.PolicyKit</literal>
D-BUS service if the calling user posses this privilege and if
this is not the case the <literal>Mount</literal> method
throws
the <literal>org.freedesktop.Hal.Device.PermissionDeniedByPolicy</literal>
exception. Notably, this exception will tell the caller what
privilege the calling user needs to possess,
e.g. either <emphasis>hal-storage-fixed-mount</emphasis>
or <emphasis>hal-storage-removable-mount</emphasis>.
</para>
<para>
Should the <literal>Mount</literal> method fail with the
exception <literal>PermissionDeniedByPolicy</literal> the
caller now knows what privilege is required. The caller can
now initiate a dialogue with the <literal>PolicyKit</literal>
service to obtain this privilege. This conversation is
basically equivalent to a PAM authentication; in fact the
<literal>PolicyKit</literal> service uses PAM under the hood
and wraps it in D-BUS calls. For details (like what user to
authenticate as) see XXX. When the caller obtains the
privilege (after successful authentication) he can now
invoke <literal>Mount</literal> and after this succeeds he may
tell the <literal>PolicyKit</literal> service to release the
privilege for the user as it is no longer needed.
</para>
<para>
Hence, <literal>PolicyKit</literal> has the notion of
both <emphasis>permament</emphasis>
and <emphasis>temporary</emphasis> privileges. The latter may
even be restricted such that only callers from the D-BUS
connection (remember, D-BUS connections has unique names)
obtaining the privilege may use the obtained privilege.
</para>
<para>
<inlinegraphic fileref="polkit-arch.png" format="PNG"/>
</para>
<para>
The whole example is outlined in the diagram above.
</para>
</sect1>
</chapter>
</book>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment