[PATCH] Changes to allow multiple sessions per application, discussed on mailing list.
Stef Walter
stef at memberwebs.com
Wed Aug 19 20:15:33 PDT 2009
---
specifications/Secrets/org.freedesktop.Secrets.xml | 105 +++++++++++--------
specifications/Secrets/specification.xml | 49 +++++----
2 files changed, 89 insertions(+), 65 deletions(-)
diff --git a/specifications/Secrets/org.freedesktop.Secrets.xml b/specifications/Secrets/org.freedesktop.Secrets.xml
index 150a8b6..072ca2f 100644
--- a/specifications/Secrets/org.freedesktop.Secrets.xml
+++ b/specifications/Secrets/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>
@@ -167,6 +156,42 @@
<tp:docstring>Collection that was created</tp:docstring>
</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>
@@ -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/specifications/Secrets/specification.xml b/specifications/Secrets/specification.xml
index 779e722..4677dee 100644
--- a/specifications/Secrets/specification.xml
+++ b/specifications/Secrets/specification.xml
@@ -105,7 +105,7 @@
such an invalid access the
<link linkend='org.freedesktop.Secrets.Error.IsLocked'><errorname>IsLocked</errorname></link>
error should be raised.</para>
-
+
<para>Client applications without special requirements should store in the default
collection. Use the
<link linkend='org.freedesktop.Secrets.Service.DefaultCollection'>
@@ -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>
--
1.6.0.4
--------------040202060809000000050004
Content-Type: text/x-diff;
name="0004-Tag-functions-referenced-in-text-with-function-tag.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
filename*0="0004-Tag-functions-referenced-in-text-with-function-tag.patc";
filename*1="h"
More information about the Authentication
mailing list