diff options
Diffstat (limited to 'secret-service/specification.xml')
| -rw-r--r-- | secret-service/specification.xml | 47 |
1 files changed, 27 insertions, 20 deletions
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> |