[gnome-keyring/dbus-api] Complete most of the secrets API documentation.

From: Stefan Walter <stefw src gnome org>
To: svn-commits-list gnome org
Subject: [gnome-keyring/dbus-api] Complete most of the secrets API documentation.
Date: Sat, 20 Jun 2009 20:29:22 -0400 (EDT)
commit 17b9c64d857dc68795f57c1e08c15240a051b6ed
Author: Stef Walter <stef memberwebs com>
Date:   Sat Jun 20 18:57:41 2009 +0000

    Complete most of the secrets API documentation.

 .../api/org.freedesktop.Secrets.Collection.xml     |    8 +-
 .../secrets/api/org.freedesktop.Secrets.Item.xml   |    7 +
 .../api/org.freedesktop.Secrets.Service.xml        |    9 +-
 .../api/org.freedesktop.Secrets.Session.xml        |   12 +-
 docs/reference/secrets/secrets-docs.sgml           |  401 +++++++++++++++++++-
 5 files changed, 411 insertions(+), 26 deletions(-)
---
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml b/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
index e2dbd18..24381b4 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Collection.xml
@@ -4,13 +4,19 @@
 <node name="/org/freedesktop/Secrets">
 
 	<interface name="org.freedesktop.Secrets.Collection">
+		<annotation value="Collection of items" name="org.gtk.EggDBus.DocString.Summary"/>
+		<annotation value="A collection of items containing secrets." name="org.gtk.EggDBus.DocString"/>
 
 		<property name="Label" type="s" access="readwrite">
 			<annotation value="The displayable label of this collection." name="org.gtk.EggDBus.DocString"/>
 		</property>
 
 		<property name="Locked" type="s" access="read">
-			<annotation value="Whether the correction is locked or not." name="org.gtk.EggDBus.DocString"/>
+			<annotation value="Whether the collection is locked and must be authenticated by the client application." name="org.gtk.EggDBus.DocString"/>
+		</property>
+		
+		<property name="Private" type="s" access="read">
+			<annotation value="Whether this is a private collection or not." name="org.gtk.EggDBus.DocString"/>
 		</property>
 
 		<method name="Delete">
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Item.xml b/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
index ee91aab..6cc372d 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Item.xml
@@ -5,6 +5,7 @@
 
 	<!-- Secret Struct. Signature: (sayay) -->
 	<annotation value="Secret" name="org.gtk.EggDBus.DeclareStruct">
+		<annotation value="A secret" name="org.gtk.EggDBus.DocString.Summary"/>
 		<annotation value="The #Secret type holds a (possibly encoded) secret." name="org.gtk.EggDBus.DocString"/>
 
 		<annotation value="String:algorithm" name="org.gtk.EggDBus.Struct.Member">
@@ -21,10 +22,16 @@
 	</annotation>
 	
 	<interface name="org.freedesktop.Secrets.Item">
+		<annotation value="Item wraps a secret" name="org.gtk.EggDBus.DocString.Summary"/>
+		<annotation value="An item contains a secret, lookup attributes and has a label." name="org.gtk.EggDBus.DocString"/>
 
 		<signal name="changed">
 			<annotation value="The item changed in some way." name="org.gtk.EggDBus.DocString"/>
 		</signal>
+		
+		<property name="Locked" type="b" access="read">
+			<annotation value="Whether the item is locked and requires authentication, or not." name="org.gtk.EggDBus.DocString"/>
+		</property>
 
 		<property name="Fields" type="a{ss}" access="readwrite">
 			<annotation value="The lookup fields for this item." name="org.gtk.EggDBus.DocString"/>
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Service.xml b/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
index efb81a4..9dc2188 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Service.xml
@@ -10,6 +10,8 @@
 <node name="/org/freedesktop/Secrets">
 
 	<interface name="org.freedesktop.Secrets.Service">
+		<annotation value="Manages collections and sessions" name="org.gtk.EggDBus.DocString.Summary"/>
+		<annotation value="The Secrets service manages all the sessions and collections." name="org.gtk.EggDBus.DocString"/>
 
 		<method name="OpenSession">
 			<annotation value="Open a unique session for the caller application." name="org.gtk.EggDBus.DocString"/>
@@ -30,13 +32,12 @@
 		<method name="CreateCollection">
 			<annotation value="Create a new collection with the specified access attributes" name="org.gtk.EggDBus.DocString"/>
 			            
-			<arg name="display_name" type="s" direction="in">
+			<arg name="label" type="s" direction="in">
 				<annotation value="The display name of the new collection" name="org.gtk.EggDBus.DocString"/>
 			</arg>
 			
-			<!-- TODO: Access rules need more thought. Unimplemented -->
-			<arg name="access_rules" type="as" direction="in">
-				<annotation value="The access rules of the new collection" name="org.gtk.EggDBus.DocString"/>
+			<arg name="private" type="b" direction="in">
+				<annotation value="Whether this is a private collection or not." name="org.gtk.EggDBus.DocString"/>
 			</arg>
 		</method>
 
diff --git a/daemon/secrets/api/org.freedesktop.Secrets.Session.xml b/daemon/secrets/api/org.freedesktop.Secrets.Session.xml
index 8f7692c..b6ede36 100644
--- a/daemon/secrets/api/org.freedesktop.Secrets.Session.xml
+++ b/daemon/secrets/api/org.freedesktop.Secrets.Session.xml
@@ -4,6 +4,8 @@
 <node name="/org/freedesktop/Secrets">
 
 	<interface name="org.freedesktop.Secrets.Session">
+		<annotation value="Client application session" name="org.gtk.EggDBus.DocString.Summary"/>
+		<annotation value="A session tracks state between the service and a client application." name="org.gtk.EggDBus.DocString"/>
 
 		<method name="Close">
 			<annotation value="Close this session." name="org.gtk.EggDBus.DocString"/>
@@ -16,11 +18,11 @@
 				<annotation value="The algorithm the caller wishes to use." name="org.gtk.EggDBus.DocString"/>
 			</arg>
 			
-			<arg name="parameters" type="ay" direction="in">
+			<arg name="input" type="v" direction="in">
 				<annotation value="Input arguments for the algorithm." name="org.gtk.EggDBus.DocString"/>
 			</arg>
 			
-			<arg name="output" type="ay" direction="out">
+			<arg name="output" type="v" direction="out">
 				<annotation value="Output of the negotiation." name="org.gtk.EggDBus.DocString"/>
 			</arg>
 		</method>
@@ -50,11 +52,15 @@
 		</method>
 		
 		<signal name="Authenticated">
-			<annotation value="An object (collection or item) was successfully authenticated." name="org.gtk.EggDBus.DocString"/>
+			<annotation value="An object (collection or item) was authenticated." name="org.gtk.EggDBus.DocString"/>
 		
 			<arg name="object" type="o">
 				<annotation value="The object that was authenticated." name="org.gtk.EggDBus.DocString"/>
 			</arg>
+			
+			<arg name="success" type="b">
+				<annotation value="Whether the object was successfully unlocked." name="org.gtk.EggDBus.DocString"/>
+			</arg>
 		</signal>
 		
 	</interface>
diff --git a/docs/reference/secrets/secrets-docs.sgml b/docs/reference/secrets/secrets-docs.sgml
index 38c8b93..27d09c5 100644
--- a/docs/reference/secrets/secrets-docs.sgml
+++ b/docs/reference/secrets/secrets-docs.sgml
@@ -5,27 +5,391 @@
   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
 ]>
 <book id="index">
-  <bookinfo>
-    <title>secrets Reference Manual</title>
-    <releaseinfo>
-      for secrets [VERSION]
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/secrets/index.html";>http://[SERVER]/secrets/</ulink>.
-    </releaseinfo>
-  </bookinfo>
+	<bookinfo>
+		<title>Secrets API Specification</title>
+		<releaseinfo>
+			Secrets 0.1
+<!--			The latest version of this documentation can be found on-line at
+			<ulink role="online-location" url="http://[SERVER]/secrets/index.html";>http://[SERVER]/secrets/</ulink>.-->
+		</releaseinfo>
+		
+		<authorgroup>
+		<author>
+			<firstname>Stef</firstname>
+			<surname>Walter</surname>
+			<affiliation>
+				<jobtitle>GNOME Keyring Developer</jobtitle>
+				<address>
+					<email>stef memberwebs com</email>
+				</address>
+			</affiliation>
+		</author>
+		<author>
+			<firstname>Michael</firstname>
+			<surname>Leupold</surname>
+			<affiliation>
+				<jobtitle>KWallet Developer</jobtitle>
+				<address>
+					<email>lemma confuego org</email>
+				</address>
+			</affiliation>
+		</author>
+		</authorgroup>
+		
+		<copyright>
+			<year>2008-2009</year>
+			<holder>The Secrets API Authors</holder>
+		</copyright>
+		
+	</bookinfo>
+	
+	<part id="description">
+		<title>API Documentation</title>
+		<chapter>
+			<title>Introduction</title>
+			
+			<para>The Secrets API allows client applications to store secrets securily in a
+			service running in the user's login session. </para>
+			
+			<para>The secrets are usually stored in an encrypted manner by the service. The
+			service may need to be unlocked and/or authenticated by the user before the 
+			secrets become available for retrieval by client applications.</para>  
 
-  <part id="ref-dbus-api">
-    <title>D-Bus API Reference</title>
-    <xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Collection.xml"/>
-    <xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Item.xml"/>
-    <xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Service.xml"/>
-    <xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Session.xml"/>
-  </part>
+			<para>The Secrets service stores a secret along with a set of lookup attributes. 
+			The attributes can be used to lookup and retrieve a secret at a later date. The 
+			lookup attributes are not treated as secret material, and the service may choose 
+			to not encrypt attributes when storing them to disk.</para> 
+		</chapter>
+		
+		<chapter>
+			<title>Secrets</title>
+			
+			<para>A secret is something an application wishes to store securely. A good example
+			is a password that an application needs to save and use at a later date.</para>
+			
+			<para>Within this API a secret value is treated as an array of bytes. It is 
+			recommended that a secret consist of user readable text, although this API has
+			no such requirement.</para>
+			
+			<para>Applications wishing to store multiple values as part of a single secret, may 
+			choose to use a textual format to combine these values into one. For example, the 
+			'desktop' key file format, or XML or another form of markup.</para>    
+			
+			<para>Secrets may be <link linkend='transfer-of-secrets'>encrypted when transferred</link>
+			 to the client application and vice versa.</para>
+			 
+			<para>The <link linkend='eggdbus-structmain-Secret'>Secret structure</link> encapsulates 
+			a secret value along with it's transfer encryption parameters.</para>
+		</chapter>
+		
+		<chapter>
+			<title>Collection and Items</title>
+			
+			<para>Each secret is stored together with 
+			<link linkend='lookup-attributes'>lookup attributes</link> and a label. These together
+			form an <link linkend='eggdbus-interface-org.freedesktop.Secrets.Item'>item</link>.</para>
+			
+			<para>A group of items together form a 
+			<link linkend='eggdbus-interface-org.freedesktop.Secrets.Collection'>collection</link>. 
+			A collection is similar in concept to the terms 'keyring' or 'wallet'.</para>
+			
+			<para>Collections and items are represented as DBus objects, and each have their own
+			object paths. However these may change from time to time.</para>
+			
+			<para>It is strongly recommended that client applications use 
+			<link linkend='lookup-attributes'>lookup attributes</link> to find items rather than 
+			recording the object path of a stored item. This allows maximum interoperability.</para>
+			
+			<para>An item or a collection may be initially in a locked state. When in a locked
+			state the item or collection may not be modified in any way, and the secret may not 
+			be read. Client applications that require access to the secret of a locked item, or 
+			desire to modify a locked item, should <link linkend='authentication-unlocking'>unlock it before use</link>.</para>
+			
+			<para>The service must prevent locked collections or items from modification. On 
+			such an invalid access the [TODO: document error code] error should be raised.</para>
+			
+			<para>Client applications without special requirements should store in the default 
+			collection. Use the 
+			<link linkend='eggdbus-property-org.freedesktop.Secrets.Service:DefaultCollection'>DefaultCollection</link>
+			property on the Service interface to determine the default collection. In addition 
+			the default collection is always accessible through a 
+			<link linkend='object-paths'>specific object path</link>.</para>
+			
+			<para>Client applications with special needs can create a new collection by calling the 
+			<link linkend='eggdbus-property-org.freedesktop.Secrets.Service.CreateCollection'>CreateCollection()</link>
+			method on the Service interface. A client application must have 
+			<link linkend='sessions'>opened a session</link> before a collection can be created. The </para>
+			
+			<para>A collection may be marked as private on creation. A private collection and the 
+			items within it may only be unlocked by the application that created the collection.
+			Service implementors may choose not to implement this feature and should ignore the 
+			private argument when 
+			<link linkend='eggdbus-method-org.freedesktop.Secrets.Service.CreateCollection'>creating a collection</link>. 
+			Client applications that demand this feature, should check the the 
+			<link linkend='eggdbus-property-org.freedesktop.Secrets.Collection:Private'>Private property</link>
+			after creating a collection to see if the request for a private collection was ignored.</para>
+			
+			<para>A collection can be deleted by calling the 
+			<link linkend='eggdbus-property-org.freedesktop.Secrets.Collection.Delete'>Delete()</link>
+			method on the Service interface. A client application must have 
+			<link linkend='sessions'>opened a session</link> before a collection can be created. 
+			However the collection does not need to be unlocked. In addition private collections can 
+			be deleted by any application.</para>
+		</chapter>
 
-  <chapter>
-    <title>[Insert title here]</title>
+		<chapter>
+			<title>Lookup Attributes</title>
+			
+			<para>Attributes can and should be stored with a secret to facilitate lookup
+			of the secret at a later date.</para>
+			
+			<para>An attribute constists of a name, and a value. Both parts are simple 
+			strings.</para>
+			
+			<para>The service may have additional requirements as to what can be present
+			in an attribute name. It is recommended that attribute names are human 
+			readable, and kept simple for the sake of simplicity.</para>
+			
+			<para>During a lookup, attribute names and values are matched via case-sensitive 
+			string equality.</para>
+			
+			<para>It's important to remember that attributes are not part of the secret. 
+			Services implementing this API will probably store attributes in an unencrypted 
+			manner in order to support simple and effecient lookups.</para>
+		</chapter>
+		
+		<chapter id="sessions">
+			<title>Sessions</title>
+			
+			<para>A session is established between a client application and a service. A session 
+			is used to unlock items and collections when necessary. It is also used to 
+			<link linkend='transfer-secrets'>negotiate encryption of transferred secrets</link> 
+			between the client application and the service.</para>
+			
+			<para>A session is established by calling the service's 
+			<link linkend='eggdbus-method-org.freedesktop.Secrets.Service.OpenSession'>OpenSession()</link>
+			method. Once established, a session is bound to calling application's connection to 
+			the DBus session bus. Generally only one session can be established per client 
+			application. Calling OpenSession() a second time results in an error [TODO: document error].</para>
+			 
+			<para>A session is closed when the client application disconnects from the DBus 
+			session bus. Alternatively the client application can call the
+			<link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Close'>Close()</link>
+			method on the session interface. Once a session is closed all session specific
+			negotiations and authentication should be dropped by the service.</para>
+		</chapter>
+		
+		<chapter id='transfer-secrets'>
+			<title>Transfer of Secrets</title>
+			
+			<para>Since this is a D-Bus API, the data in all method calls and other accesses
+			in this API will go through multiple processes, and may be cached arbitrarily
+			by the OS or elsewhere.</para>
+			
+			<para>The Secrets API has provision to encrypt secrets while in transit between 
+			the service and the client application.</para>
+			
+			<para>The encryption is not envisioned to withstand man in the middle attacks, or 
+			other active attacks. It is envisioned to minimize storage of plain text secrets
+			in memory and prevent storage plain text storage of secrets in a swap file or other
+			caching mechanism.</para>   
+			
+			<para>Many client applications may choose not to make use of the provisions to 
+			encrypt secrets in transit. In fact for applications unable to prevent their own
+			memory from being paged to disk (eg: Java, C# or Python apps), transfering 
+			encrypted secrets would be an excersize of questionable value.</para>
+			
+			<para>This API was desigened by GNOME and KDE developers with the goal of having
+			a common way to store secrets. It's predecessors are the desktop specific APIs
+			used by GNOME Keyring and KWallet.</para>
+
+			<sect1>
+				<title>Negotiation of Algorithms</title>
+			
+				<para>In order to encrypt secrets in transit, the service and the client 
+				application must agree on an algorithm, and some algorithm specific 
+				parameters (eg: a key).</para>
+			
+				<para>The client application opens a <link linkend='sessions'>session</link> 
+				with the service, and then calls the 
+				<link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+				Negotiate() method</link> on that session. The algorithms argument to the 
+				Negotiate() method specifies a set of algorithms to be used together for 
+				key agreement and encryption. The other arguments are algorithm specific.</para>
+				
+				<para>If a service does not support a specific set of algorithms, an error 
+				[TODO: Document the error code] is returned, and the client is free to try another 
+				set of algorithms. The <emphasis>PLAIN</emphasis> algorithm is almost always
+				supported.</para>
+				
+				<para>An algorithm may require that the Negotiate() method is called multiple
+				times in succession to be complete. Each iteration transfers algorithm specific
+				data back forth between the service and the client.</para>
+				
+				<para>Once an algorithm has been negotiated, it is used for all transfer of secrets
+				between the service and the client application in both directions. Algorithm 
+				specific parameters may be transfered with each 
+				<link linkend='eggdbus-structmain-Secret'>secret</link>.</para>
+			</sect1>
+			
+			<sect1>
+				<title>Algorithm: PLAIN</title>
+			
+				<simplelist type='vert'>
+				<member>Algorithm string: <emphasis>PLAIN</emphasis></member>
+				<member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+					Negotiate input</link>:  empty string</member>
+				<member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+					Negotiate output</link>:  empty string</member>
+				<member><link linkend='eggdbus-struct-Secret'>
+					Secret parameter</link>:  empty string</member>
+				</simplelist>
+				
+				<para>The plain algorithm does no encryption whatsoever.</para>
+				
+				<para>It is strongly recommended that a service implementing this API support 
+				the <emphasis>PLAIN</emphasis> algorithm.</para>
+			</sect1>
+			
+			<sect1>
+				<title>Algorithm: DH-GROUP-???+AES-128</title>
+				
+				<simplelist type='vert'>
+				<member>Algorithm string: <emphasis>DH-GROUP-???+AES-128</emphasis></member>
+				<member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+					Negotiate input</link>: ???TODO??? </member>
+				<member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+					Negotiate output</link>: ???TODO???</member>
+				<member><link linkend='eggdbus-struct-Secret'>
+					Secret parameter</link>: 16 byte AES Initialization Vector.</member>
+				</simplelist>
+				
+				<para>TODO: Document</para>
+			</sect1>
+			
+		</chapter>
+		
+		<chapter id='authentication-unlocking'>
+			<title>Authentication or Unlocking</title>
+			
+			<para>Some items and/or collections may be marked as locked by the service. 
+			The secrets of locked items cannot be accessed. Locked items or collections
+			cannot be modified by the client application.</para>
+			
+			<para>In order to unlock an item or collection a 
+			<link linkend='sessions'>session</link> is established by the client application,
+			and the 
+			<link linkend='eggdbus-method-org.freedesktop.Secrets.Session.BeginAuthenticate'>BeginAuthenticate()</link>
+			method is called with one or more DBus object paths of items or collections. The 
+			BeginAuthenticate() method is asynchronous and may return before the item is 
+			actually unlocked.</para>
+			
+			<para>The service will then unlock the item or collection, perhaps by prompting the 
+			user for a password, or it could require use a hardware token of some sort.</para>
+			
+			<para>After the service tries to unlock an item or collection, whether successfully
+			or unsuccessfully, the 
+			<link linkend='eggdbus-signal-org.freedesktop.Secrets.Session::Authenticated'>Authenticated</link>
+			signal on the session interface is emitted.</para>
+			
+			<para>The client application may, but is not required to, call the 
+			<link linkend='eggdbus-method-org.freedesktop.Secrets.Session.CompleteAuthenticate'>CompleteAuthenticate()</link>
+			method. One or more DBus object paths of items or collections that BeginAuthenticate()
+			was previously called with, can be passed in. The CompleteAuthenticate() returns the 
+			items that were successfully authenticated. In addition if the unlock process is not 
+			yet complete for some items or collections, the service should stop trying to ask the 
+			user to unlock or authenticate them.</para>
+			
+			<para>It's up to the service whether to unlock items individually, or collections as a 
+			whole. The client application should act as if it must unlock each item individually.</para>
+			
+			<para>A service may upon unlocking a collection, unlock all items in that collection. If
+			a service is not able to unlock an item individually, it should treat a request to unlock
+			an item as a request to unlock the connection that the item is in. The Authenticated signal
+			should however still be emitted for the individual items that were requested to be unlocked.</para>
+			
+			<para>A service may choose to authenticate items or collections just for a single client
+			application. Alternatively the service may choose to allow any client application to access 
+			items or collections authenticated by a single client application. A client application 
+			should always be ready to call BeginAuthenticate() the secrets it needs, or objects it must
+			modify. It must not assume that an item is already unlocked for whatever reason.</para>
+		</chapter>
+		
+		<chapter>
+			<title>What's not included in the API</title>
+			
+			<para>A service may implement additional DBus interfaces for further capabilities not
+			included in this specification. Password management applications or other narrowly 
+			focused tools should make use of these when necessary.</para>
+			
+			<para>This specification does not mandate the use of master passwords to lock a 
+			collection of secrets. The service may choose to implement any method for authenticating
+			secrets.</para>
+			
+			<para>This specification does not mandate any form of access control. The service may
+			choose to allow certain applications to access a keyring, and others.</para>
+			
+			<para>[TODO: complete]</para>
+			 
+		</chapter>
+		
+		<chapter>
+			<title>Notes for Service Implementors</title>
+			
+			<para>[TODO: complete]</para>
+		</chapter>
+		
+	</part>
+
+	<part id="ref-dbus-api">
+		<title>D-Bus API Reference</title>
     
-  </chapter>
+		<refentry id='object-paths'>
+			<refmeta>
+				<refentrytitle role="top_of_page">Object Paths</refentrytitle>
+			</refmeta>
+    	
+			<para>The various DBus object paths used with the Secrets API are designed to be human
+			readable but not displayed to the user.</para>
+
+			<refsect1>
+				<programlisting>/org/freedesktop/Secrets</programlisting>
+				<para>The object path for the service.</para>
+			</refsect1>
+    	
+			<refsect1>
+				<programlisting>/org/freedesktop/Secrets/collection/<emphasis>xxxx</emphasis></programlisting>
+				<para>The object path for a collection, where <emphasis>xxxx</emphasis> represents a 
+				possibly encoded or truncated version of the initial label of the collection.</para>
+			</refsect1>
+			
+			<refsect1>
+				<programlisting>/org/freedesktop/Secrets/collection/<emphasis>xxxx</emphasis>/<emphasis>iiii</emphasis></programlisting>
+				<para>The object path for an item, where <emphasis>xxxx</emphasis> is the collection (above)
+				and <emphasis>iiii</emphasis> is an auto-generated item specific identifier.</para>
+			</refsect1> 
+			
+			<refsect1>
+				<programlisting>/org/freedesktop/Secrets/session/<emphasis>ssss</emphasis></programlisting>
+				<para>The object path for a session, where <emphasis>ssss</emphasis> is an auto-generated
+				session specific identifier.</para>
+			</refsect1>
+			
+			<refsect1>
+				<programlisting>/org/freedesktop/Secrets/default</programlisting>
+				<para>The default collection for client applications to store secrets is available under
+				this object path in addition to its real object path (above).</para>
+			</refsect1>
+		</refentry>
+    
+		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Collection.xml"/>
+		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Item.xml"/>
+		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Service.xml"/>
+		<xi:include href="../../../daemon/secrets/api/docbook-interface-org.freedesktop.Secrets.Session.xml"/>
+		<xi:include href="../../../daemon/secrets/api/docbook-struct-Secret.xml"/>
+	</part>
+
+<!--
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
@@ -34,6 +398,7 @@
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
   </index>
+-->
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]