diff options
| -rw-r--r-- | secret-service/org.freedesktop.Secrets.xml | 105 | ||||
| -rw-r--r-- | secret-service/specification.xml | 47 |
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> |