From 3447cfa25193eaa5c038ff1fb0b99db14758c1d3 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Thu, 20 Aug 2009 03:15:33 +0000 Subject: Changes to allow multiple sessions per application, discussed on mailing list. --- secret-service/org.freedesktop.Secrets.xml | 105 +++++++++++++++++------------ 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 @@ - - Retrieve multiple secrets from different items. - - Items to get secrets for. - - - - Secrets for the items. - - - A collection was created. @@ -168,6 +157,42 @@ + + Start asynchronous authentication of objects for the caller. + + + Objects to authenticate or unlock. + + + + Platform specific window handle to use for showing any prompts. + + + + + Complete asynchronous authentication of objects for the caller. + + + Objects to authenticate or unlock. + + + + Objects that were successfully authenticated. + + + + + An object (collection or item) was authenticated. + + + The object that was authenticated. + + + + Whether the object was successfully unlocked. + + + @@ -235,10 +260,6 @@ The lookup attributes for the new item. - - The secret to store in the new item. - - The label for the new item. @@ -304,10 +325,6 @@ The displayable label for this item. - - The secret, usually transferred encrypted. - - The unix time when the item was created. @@ -360,41 +377,41 @@ - - Start asynchronous authentication of objects for the caller. + + Retrieve the secret for this item. - - Objects to authenticate or unlock. - + + The path to the secret we want to retrieve. + - - Platform specific window handle to use for showing any prompts. - - + + The secret retrieved. + + - - Complete asynchronous authentication of objects for the caller. + + Set the secret for this item. - - Objects to authenticate or unlock. - + + The path to the secret we want to retrieve. + - - Objects that were successfully authenticated. - - + + The secret retrieved. + + - - An object (collection or item) was authenticated. + + Retrieve multiple secrets from different items. - - The object that was authenticated. + + Items to get secrets for. - - Whether the object was successfully unlocked. + + Secrets for the items. - + 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 @@ Sessions 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 - negotiate encryption of transferred secrets - between the client application and the service. + is used to transfer secrets between the client + application and the service. A session is established by calling the service's OpenSession() 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 - - AlreadyExists - error. + the DBus session bus. A session is closed when the client application disconnects from the DBus session bus. Alternatively the client application can call the Close() method on the session interface. Once a session is closed all session specific - negotiations and authentication should be dropped by the service. + negotiations will be dropped by the service. + + More than one session may opened by a client application, although this is + not normally necessary. Transfer of Secrets + To access or store secrets, use the + GetSecret(), + GetSecrets(), + SetSecret() + methods on the session interface. + 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. @@ -298,10 +302,8 @@ The secrets of locked items cannot be accessed. Locked items or collections cannot be modified by the client application. - In order to unlock an item or collection a - session is established by the client application, - and the - + In order to unlock an item or collection the service's + BeginAuthenticate() 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 @@ After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the - + Authenticated() - signal on the session interface is emitted. + signal on the service interface is emitted. The client application may, but is not required to, call the - + CompleteAuthenticate() 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 @@ 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. + 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. + + 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). @@ -355,7 +363,6 @@ choose to allow certain applications to access a keyring, and others. [TODO: complete] - -- cgit v1.2.3-70-g09d2