diff options
| -rw-r--r-- | doc/spec/Makefile.am | 24 | ||||
| -rw-r--r-- | doc/spec/polkit-arch.dia | bin | 0 -> 2952 bytes | |||
| -rw-r--r-- | doc/spec/polkit-arch.png | bin | 0 -> 59513 bytes | |||
| -rw-r--r-- | doc/spec/polkit-spec.html | 348 | ||||
| -rw-r--r-- | doc/spec/polkit-spec.xml.in | 169 |
5 files changed, 541 insertions, 0 deletions
diff --git a/doc/spec/Makefile.am b/doc/spec/Makefile.am new file mode 100644 index 0000000..dc08beb --- /dev/null +++ b/doc/spec/Makefile.am @@ -0,0 +1,24 @@ + + +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) diff --git a/doc/spec/polkit-arch.dia b/doc/spec/polkit-arch.dia Binary files differnew file mode 100644 index 0000000..d7e4417 --- /dev/null +++ b/doc/spec/polkit-arch.dia diff --git a/doc/spec/polkit-arch.png b/doc/spec/polkit-arch.png Binary files differnew file mode 100644 index 0000000..786221b --- /dev/null +++ b/doc/spec/polkit-arch.png diff --git a/doc/spec/polkit-spec.html b/doc/spec/polkit-spec.html new file mode 100644 index 0000000..ba96e0a --- /dev/null +++ b/doc/spec/polkit-spec.html @@ -0,0 +1,348 @@ +<!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> + <CODE +CLASS="email" +><<A +HREF="mailto:david@fubar.dk" +>david@fubar.dk</A +>></CODE +><br> + </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 +> 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 +> 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 +> 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 +> 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 +> Desktop level applications may initiate a dialogue with + this service to (temporarily) obtain a privilege through + authorization. + </P +></LI +></UL +><P +> 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 +> 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 +> 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 +> 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 +> 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 +> <IMG +SRC="polkit-arch.png"> + </P +><P +> The whole example is outlined in the diagram above. + </P +></DIV +></DIV +></DIV +></BODY +></HTML +>
\ No newline at end of file diff --git a/doc/spec/polkit-spec.xml.in b/doc/spec/polkit-spec.xml.in new file mode 100644 index 0000000..729dd16 --- /dev/null +++ b/doc/spec/polkit-spec.xml.in @@ -0,0 +1,169 @@ +<?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> |
