hal: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Mon Apr 2 19:50:18 PDT 2007
doc/spec/Makefile.am | 3 -
doc/spec/hal-spec-access-control.xml | 75 ++++++++++++++++++++++++++++++
doc/spec/hal-spec-fdi-files.xml | 6 +-
doc/spec/hal-spec-introduction.xml | 6 +-
doc/spec/hal-spec-properties.xml | 87 +++++++++++++++++++++++++++++++++++
doc/spec/hal-spec.xml.in.in | 3 -
6 files changed, 172 insertions(+), 8 deletions(-)
New commits:
diff-tree df05ad6981dbd2158386c1e9a0190a973f7f4f45 (from 1a08f8d8d9612647d53571b87c2049b0e7099cde)
Author: David Zeuthen <davidz at redhat.com>
Date: Mon Apr 2 22:50:12 2007 -0400
add docs for access_control namespace
Also add missing id's to Docbook sections
diff --git a/doc/spec/Makefile.am b/doc/spec/Makefile.am
index df1ea9b..db6d477 100644
--- a/doc/spec/Makefile.am
+++ b/doc/spec/Makefile.am
@@ -6,8 +6,9 @@ FIGURE_FILES = \
SPEC_XML_EXTRA_FILES = \
hal-spec-introduction.xml \
hal-spec-fdi-files.xml \
- hal-spec-properties.xml \
hal-spec-locking.xml \
+ hal-spec-access-control.xml \
+ hal-spec-properties.xml \
hal-spec-interfaces.xml
if DOCBOOK_DOCS_ENABLED
diff --git a/doc/spec/hal-spec-access-control.xml b/doc/spec/hal-spec-access-control.xml
new file mode 100644
index 0000000..249d8bf
--- /dev/null
+++ b/doc/spec/hal-spec-access-control.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<chapter id="access-control">
+ <title>Access Control</title>
+
+ <para>
+ Access to hardware by unprivileged users is traditionally granted
+ in two ways either by granting access to the <emphasis>special
+ device file</emphasis> or allowing access through another process,
+ using IPC acting on behalf of the user. HAL follows the latter
+ model and uses the system-wide message bus (D-Bus) as the IPC
+ mechanism. In addition, HAL has support for modifying the ACL's
+ (access control lists) on a device file to grant/revoke access to
+ users based on several criteria.
+ </para>
+
+ <sect1 id="access-control-device-file">
+ <title>Device Files</title>
+ <para>
+ If HAL is built with <literal>--enable-acl-management</literal>
+ (and also <literal>--enable-console-kit</literal>) then ACL's on
+ device objects with the
+ capability <literal>access_control</literal> are automatically
+ managed according to the properties defined in
+ <xref linkend="device-properties-access-control"/>. In addition,
+ for this configuration, HAL ships with a device information file
+ that merges this capability on device objects that are normally
+ accessed by unprivileged users through the device file. This
+ includes e.g. sound cards, webcams and other devices but
+ excludes drives and volumes as the latter two are normally
+ accessed by a user through mounting them into the file system.
+ </para>
+ <para>
+ Currently this HAL device information file specifies that all
+ local users (e.g. logged in at the system console) will gain
+ access to such devices. This hard coded policy is subject to
+ change in the future when the freedesktop.org PolicyKit project is
+ will be an optional dependency of HAL.
+ </para>
+ <para>
+ In addition, 3rd party packages can supply device information
+ files to specify (via
+ the <literal>access_control.grant_user</literal>
+ and <literal>access_control.grant_group</literal> properties)
+ that a given user or group should always have access to a device
+ file. This is useful for system-wide software (such as AV
+ streaming management) that runs as an unprivileged system
+ user. This interface is supposed to be stable so 3rd party
+ packages can depend on it.
+ </para>
+ </sect1>
+
+ <sect1 id="access-control-ipc">
+ <title>D-Bus method calls</title>
+ <para>
+ If HAL is built without ConsoleKit support
+ (e.g. without <literal>--enable-console-kit</literal>) access to
+ the various D-Bus interfaces that provides mechanisms is only
+ protected by the D-Bus security configuration files
+ (e.g. using <literal>at_console</literal> to restrict to console
+ user on Red Hat systems) and, in certain cases, restricted to
+ the super user.
+ </para>
+ <para>
+ If ConsoleKit support is enabled, access to D-Bus interfaces is
+ currently hardcoded to only allow active users at the system
+ console. This hard coded policy is subject to change in the
+ future when the freedesktop.org PolicyKit project is will be an
+ optional dependency of HAL.
+ </para>
+ </sect1>
+
+</chapter>
+
diff --git a/doc/spec/hal-spec-fdi-files.xml b/doc/spec/hal-spec-fdi-files.xml
index 06190ba..a51e5f5 100644
--- a/doc/spec/hal-spec-fdi-files.xml
+++ b/doc/spec/hal-spec-fdi-files.xml
@@ -13,7 +13,7 @@
settings about devices.
</para>
- <sect1>
+ <sect1 id="fdi-matching">
<title>Matching</title>
<para>
@@ -172,7 +172,7 @@
</para>
</sect1>
- <sect1>
+ <sect1 id="fdi-merging">
<title>Merging</title>
<para>
@@ -236,7 +236,7 @@
</para>
</sect1>
- <sect1>
+ <sect1 id="fdi-search-paths">
<title>Search Paths</title>
<para>
diff --git a/doc/spec/hal-spec-introduction.xml b/doc/spec/hal-spec-introduction.xml
index 5a9873c..81ba558 100644
--- a/doc/spec/hal-spec-introduction.xml
+++ b/doc/spec/hal-spec-introduction.xml
@@ -4,7 +4,7 @@
<chapter id="introduction">
<title>Introduction</title>
- <sect1>
+ <sect1 id="introduction-about">
<title>About</title>
<para>
This document concerns the specification of HAL which is a
@@ -48,7 +48,7 @@
</para>
</sect1>
- <sect1>
+ <sect1 id="introduction-acknowledgements">
<title>Acknowledgements</title>
<para>
Havoc Pennington's article
@@ -172,7 +172,7 @@
</para>
</sect1>
- <sect1>
+ <sect1 id="introduction-device-objects">
<title>Device Objects</title>
<para>
It is important to precisely define the term HAL device
diff --git a/doc/spec/hal-spec-properties.xml b/doc/spec/hal-spec-properties.xml
index 6023990..e4e58f8 100644
--- a/doc/spec/hal-spec-properties.xml
+++ b/doc/spec/hal-spec-properties.xml
@@ -6111,6 +6111,93 @@ org.freedesktop.Hal.Device.Volume.method
</sect2>
</sect1>
+ <sect1 id="properties-misc">
+ <title>Misc. Properties</title>
+ <sect2 id="device-properties-access-control">
+ <title>
+ access_control namespace
+ </title>
+ <para>
+ Device objects with the
+ capability <literal>access_control</literal> represent devices
+ where access to a special device file can be granted/revoked
+ to unprivileged users.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key (type)</entry>
+ <entry>Values</entry>
+ <entry>Mandatory</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>access_control.file</literal> (string)
+ </entry>
+ <entry>Example: /dev/snd/pcmC0D1p</entry>
+ <entry>Yes</entry>
+ <entry>
+ Name of the special device file that access can be granted to.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>access_control.grant_user</literal> (strlist)
+ </entry>
+ <entry>Example: "gdm, flumotion"</entry>
+ <entry>No</entry>
+ <entry>
+ List of UNIX user names to always grant access to the
+ device. This is useful for 3rd party system-wide
+ packages that need access to a device to function
+ properly.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>access_control.grant_group</literal> (strlist)
+ </entry>
+ <entry>Example: "pvr_software, staff"</entry>
+ <entry>No</entry>
+ <entry>
+ List of UNIX group names to always grant access to the
+ device. This is useful for 3rd party system-wide
+ packages that need access to a device to function
+ properly.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>access_control.grant_local_session</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ If true, access to this device should be granted to local sessions.
+ (NOTE NOTE NOTE: this property is experimental and may disappear in the future).
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>access_control.grant_local_active_session</literal> (bool)
+ </entry>
+ <entry></entry>
+ <entry>No</entry>
+ <entry>
+ If true, access to this device should be granted to active local sessions.
+ (NOTE NOTE NOTE: this property is experimental and may disappear in the future).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </sect2>
+ </sect1>
+
<sect1 id="properties-deprecated">
<title>Deprecated Properties</title>
<para>
diff --git a/doc/spec/hal-spec.xml.in.in b/doc/spec/hal-spec.xml.in.in
index acc0d40..320b6ab 100644
--- a/doc/spec/hal-spec.xml.in.in
+++ b/doc/spec/hal-spec.xml.in.in
@@ -20,9 +20,10 @@
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-introduction.xml" />
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-properties.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-fdi-files.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-access-control.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-locking.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-properties.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hal-spec-interfaces.xml" />
</book>
More information about the hal-commit
mailing list