Changes to allow multiple sessions per application, discussed on mailing list.

2 files changed, 88 insertions, 64 deletions

diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml
index da5d609..1053751 100644
--- a/secret-service/org.freedesktop.Secrets.xml
+++ b/secret-service/org.freedesktop.Secrets.xml
@@ -141,17 +141,6 @@
                 </arg>
             </method>
 
-            <method name="RetrieveSecrets">
-                <tp:docstring>Retrieve multiple secrets from different items.</tp:docstring>
-                <arg name="items" type="ao" direction="in">
-                    <tp:docstring>Items to get secrets for.</tp:docstring>
-                </arg>
-
-                <arg name="secrets" type="a{o(sayay)}" direction="out" tp:type="ObjectPath_Secret_Map">
-                    <tp:docstring>Secrets for the items.</tp:docstring>
-                </arg>
-            </method>
-
             <signal name="CollectionCreated">
                 <tp:docstring>A collection was created.</tp:docstring>
 
@@ -168,6 +157,42 @@
                 </arg>
             </signal>
 
+            <method name="BeginAuthenticate">
+                <tp:docstring>Start asynchronous authentication of objects for the caller.</tp:docstring>
+
+                <arg name="objects" type="ao" direction="in">
+                    <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
+                </arg>
+
+                <arg name="window-id" type="s" direction="in">
+                    <tp:docstring>Platform specific window handle to use for showing any prompts.</tp:docstring>
+                </arg>
+            </method>
+
+            <method name="CompleteAuthenticate">
+                <tp:docstring>Complete asynchronous authentication of objects for the caller.</tp:docstring>
+
+                <arg name="objects" type="ao" direction="in">
+                    <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
+                </arg>
+
+                <arg name="authenticated" type="ao" direction="in">
+                    <tp:docstring>Objects that were successfully authenticated.</tp:docstring>
+                </arg>
+            </method>
+
+            <signal name="Authenticated">
+                <tp:docstring>An object (collection or item) was authenticated.</tp:docstring>
+
+                <arg name="object" type="o">
+                    <tp:docstring>The object that was authenticated.</tp:docstring>
+                </arg>
+
+                <arg name="success" type="b">
+                    <tp:docstring>Whether the object was successfully unlocked.</tp:docstring>
+                </arg>
+            </signal>
+
         </interface>
 
     </node>
@@ -235,10 +260,6 @@
                     <tp:docstring>The lookup attributes for the new item.</tp:docstring>
                 </arg>
 
-                <arg name="secret" type="(sayay)" direction="in" tp:type="Secret">
-                    <tp:docstring>The secret to store in the new item.</tp:docstring>
-                </arg>
-
                 <arg name="label" type="s" direction="in">
                     <tp:docstring>The label for the new item.</tp:docstring>
                 </arg>
@@ -304,10 +325,6 @@
                 <tp:docstring>The displayable label for this item.</tp:docstring>
             </property>
 
-            <property name="Secret" type="(sayay)" access="readwrite" tp:type="Secret">
-                <tp:docstring>The secret, usually transferred encrypted.</tp:docstring>
-            </property>
-
             <property name="Created" type="t" access="read">
                 <tp:docstring>The unix time when the item was created.</tp:docstring>
             </property>
@@ -360,41 +377,41 @@
                 </arg>
             </method>
 
-            <method name="BeginAuthenticate">
-                <tp:docstring>Start asynchronous authentication of objects for the caller.</tp:docstring>
+			<method name="GetSecret">
+				<tp:docstring>Retrieve the secret for this item.</tp:docstring>
 
-                <arg name="objects" type="ao" direction="in">
-                    <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
-                </arg>
+				<arg name="item" type="o" direction="in">
+					<tp:docstring>The path to the secret we want to retrieve.</tp:docstring>
+				</arg>
 
-                <arg name="window-id" type="s" direction="in">
-                    <tp:docstring>Platform specific window handle to use for showing any prompts.</tp:docstring>
-                </arg>
-            </method>
+				<arg name="secret" type="(sayay)" tp:type="Secret" direction="out">
+					<tp:docstring>The secret retrieved.</tp:docstring>
+				</arg>
+			</method>
 
-            <method name="CompleteAuthenticate">
-                <tp:docstring>Complete asynchronous authentication of objects for the caller.</tp:docstring>
+			<method name="SetSecret">
+				<tp:docstring>Set the secret for this item.</tp:docstring>
 
-                <arg name="objects" type="ao" direction="in">
-                    <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
-                </arg>
+				<arg name="item" type="o" direction="in">
+					<tp:docstring>The path to the secret we want to retrieve.</tp:docstring>
+				</arg>
 
-                <arg name="authenticated" type="ao" direction="in">
-                    <tp:docstring>Objects that were successfully authenticated.</tp:docstring>
-                </arg>
-            </method>
+				<arg name="secret" type="(sayay)" tp:type="Secret" direction="in">
+					<tp:docstring>The secret retrieved.</tp:docstring>
+				</arg>
+			</method>
 
-            <signal name="Authenticated">
-                <tp:docstring>An object (collection or item) was authenticated.</tp:docstring>
+            <method name="GetSecrets">
+                <tp:docstring>Retrieve multiple secrets from different items.</tp:docstring>
 
-                <arg name="object" type="o">
-                    <tp:docstring>The object that was authenticated.</tp:docstring>
+                <arg name="items" type="ao" direction="in">
+                    <tp:docstring>Items to get secrets for.</tp:docstring>
                 </arg>
 
-                <arg name="success" type="b">
-                    <tp:docstring>Whether the object was successfully unlocked.</tp:docstring>
+                <arg name="secrets" type="a{o(sayay)}" direction="out" tp:type="ObjectPath_Secret_Map">
+                    <tp:docstring>Secrets for the items.</tp:docstring>
                 </arg>
-            </signal>
+            </method>
 
         </interface>
 
diff --git a/secret-service/specification.xml b/secret-service/specification.xml
index 86acd02..b61fe97 100644
--- a/secret-service/specification.xml
+++ b/secret-service/specification.xml
@@ -163,30 +163,34 @@
 			<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>
+			is used to <link linkend='transfer-secrets'>transfer secrets</link> between the client
+			application and the service.</para>
 
 			<para>A session is established by calling the service's
 			<link linkend='org.freedesktop.Secrets.Service.OpenSession'>
 			<function>OpenSession()</function></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
-			<link linkend='org.freedesktop.Secrets.Error.AlreadyExists'>
-			<errorname>AlreadyExists</errorname></link>
-			error.</para>
+			the DBus session bus.</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='org.freedesktop.Secrets.Session.Close'><function>Close()</function></link>
 			method on the session interface. Once a session is closed all session specific
-			negotiations and authentication should be dropped by the service.</para>
+			negotiations will be dropped by the service.</para>
+
+			<para>More than one session may opened by a client application, although this is
+			not normally necessary.</para>
 		</chapter>
 
 		<chapter xml:id='transfer-secrets'>
 			<title>Transfer of Secrets</title>
 
+			<para>To access or store secrets, use the
+			<link linkend='org.freedesktop.Secrets.Session.GetSecret'><function>GetSecret()</function></link>,
+			<link linkend='org.freedesktop.Secrets.Session.GetSecrets'><function>GetSecrets()</function></link>,
+			<link linkend='org.freedesktop.Secrets.Session.SetSecret'><function>SetSecret()</function></link>
+			methods on the session interface.</para>
+
 			<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>
@@ -298,10 +302,8 @@
 			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='org.freedesktop.Secrets.Session.BeginAuthenticate'>
+			<para>In order to unlock an item or collection the service's
+			<link linkend='org.freedesktop.Secrets.Service.BeginAuthenticate'>
 			<function>BeginAuthenticate()</function></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
@@ -312,12 +314,12 @@
 
 			<para>After the service tries to unlock an item or collection, whether successfully
 			or unsuccessfully, the
-			<link linkend='org.freedesktop.Secrets.Session.Authenticated'>
+			<link linkend='org.freedesktop.Secrets.Service.Authenticated'>
 			<function>Authenticated()</function></link>
-			signal on the session interface is emitted.</para>
+			signal on the service interface is emitted.</para>
 
 			<para>The client application may, but is not required to, call the
-			<link linkend='org.freedesktop.Secrets.Session.CompleteAuthenticate'>
+			<link linkend='org.freedesktop.Secrets.Service.CompleteAuthenticate'>
 			<function>CompleteAuthenticate()</function></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
@@ -335,9 +337,15 @@
 
 			<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>
+			items or collections authenticated by a single client application.</para>
+
+			<para>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>
+
+			<para>A service may lock previously unlocked items for any reason at any time. Usually this
+			is done in response to user actions, timeouts, or external actions (such as the computer
+			sleeping).</para>
 		</chapter>
 
 		<chapter>
@@ -355,7 +363,6 @@
 			choose to allow certain applications to access a keyring, and others.</para>
 
 			<para>[TODO: complete]</para>
-
 		</chapter>
 
 		<chapter>