From 86f0c16391cead728560052a7e8c0aeec4a0cd61 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 25 Nov 2009 02:19:48 +0000 Subject: Implement concept of prompt objects. * Items that could require prompting, return an optional prompt object. * Prompt objects must then be acted upon. * Prompts can be dismissed. * Operation completes with the prompt, and signal is emitted. * When no prompt is needed, returns '/' --- secret-service/org.freedesktop.Secrets.xml | 205 +++++++++++++++-------------- secret-service/specification.xml | 194 +++++++++++++++++++-------- 2 files changed, 246 insertions(+), 153 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index 1053751..b645022 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -108,88 +108,75 @@ - Create a new collection with the specified access attributes. - - - The display name of the new collection + Create a new collection with the specified properties. + + Properties for the new collection. - - - Whether this is a private collection or not. + + The new collection object, or '/' if prompting is necessary. + + + A prompt object if prompting is necessary, or '/' if no prompt was needed. - - - - - Lock down the entire service. Remove secrets from memory, lock all collections etc... - Find items in any collection. - Find secrets in any collection. - Items found. - Items found that require authentication. - - A collection was created. - - - Collection that was created - - - - - A collection was deleted. - - - Collection that was created - - - - - Start asynchronous authentication of objects for the caller. - + + Unlock the specified objects. - Objects to authenticate or unlock. + Objects to unlock. - - - Platform specific window handle to use for showing any prompts. + + Objects that were unlocked without a prompt. + + + A prompt object which can be used to unlock the remaining objects, or the special value '/' when no prompt is necessary. - - Complete asynchronous authentication of objects for the caller. - + + Lock the items. - Objects to authenticate or unlock. + Objects to lock. - - - Objects that were successfully authenticated. + + Objects that were locked without a prompt. + + + A prompt to lock the objects, or the special value '/' when no prompt is necessary. - - An object (collection or item) was authenticated. + + A collection was created. + + Collection that was created + + - - The object that was authenticated. + + A collection was deleted. + + Collection that was deleted. + - - Whether the object was successfully unlocked. + + A collection was changed. + + Collection that was changed. @@ -213,10 +200,6 @@ Items in this collection. - - Whether this is a private collection or not. - - The displayable label of this collection. @@ -237,6 +220,9 @@ Delete this collection. + + A prompt to delete the collection, or the special value '/' when no prompt is necessary. + @@ -250,32 +236,23 @@ - - - Create an item with the given attributes, secret and label. If replace is set, - then it replaces an item already present with the same values for the attributes. - - - - The lookup attributes for the new item. - - - - The label for the new item. + Create an item with the given attributes, secret and label. If replace is set, then it replaces an item already present with the same values for the attributes. + + The properties for the new item. - Whether to replace an item with the same attributes or not. - - The new item, or previous item if replaced. + The item created, or the special value '/' if a prompt is necessary. + + + A prompt object, or the special value '/' if no prompt is necessary. A new item in this collection was created. - The item that was created. @@ -335,6 +312,9 @@ Delete this item. + + A prompt object, or the special value '/' if no prompt is necessary. + @@ -377,37 +357,31 @@ - - Retrieve the secret for this item. - - - The path to the secret we want to retrieve. - - - - The secret retrieved. - - - - - Set the secret for this item. - - - The path to the secret we want to retrieve. - + + Retrieve the secret for this item. + + The path to the secret we want to retrieve. + + + The secret retrieved. + + - - The secret retrieved. - - + + Set the secret for this item. + + The path to the secret we want to retrieve. + + + The secret retrieved. + + Retrieve multiple secrets from different items. - Items to get secrets for. - Secrets for the items. @@ -417,4 +391,43 @@ + + + + + + A prompt necessary to complete an operation. + + + Perform the prompt. + + Platform specific window handle to use for + showing the prompt. + + + + + Dismiss the prompt. + + + + The prompt and operation completed. + + The possibly empty, operation specific, + result. + + + Whether the prompt and operation were dismissed + or not. + + + + + + + diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 592cf13..f0314a7 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -47,8 +47,8 @@ service running in the user's login session. The secrets are usually stored in an encrypted manner by the service. The - service may need to be unlocked and/or authenticated by the user before the - secrets become available for retrieval by client applications. + service may need to be unlocked by the user before the secrets become available + for retrieval by client applications. The Secrets service stores a secret along with a set of lookup attributes. The attributes can be used to lookup and retrieve a secret at a later date. The @@ -74,7 +74,7 @@ to the client application and vice versa. The Secret structure encapsulates - a secret value along with it's transfer encryption parameters. + a secret value along with its transfer encryption parameters. @@ -89,7 +89,7 @@ A collection is similar in concept to the terms 'keyring' or 'wallet'. Collections and items are represented as DBus objects, and each have their own - object paths. The object path of a collection or item should not change for it's lifetime, + object paths. The object path of a collection or item should not change for its lifetime, under normal circumstances. It is strongly recommended that client applications use @@ -99,7 +99,7 @@ An item or a collection may be initially in a locked state. When in a locked state the item or collection may not be modified in any way, and the secret may not be read. Client applications that require access to the secret of a locked item, or - desire to modify a locked item, should unlock it before use. + desire to modify a locked item, should unlock it before use. The service must prevent locked collections or items from modification. On such an invalid access the @@ -114,28 +114,52 @@ the default collection is always accessible through a specific object path. + A new item can be created with the + + CreateItem() + method on the Collection interface. When creating an item, the properties of the new + item are specified. The service may ignore or change these properties when creating + the item. + + When creating an item, the service may need to prompt the user for additional + information. In this case, a prompt object is returned. It + must be acted upon in order for + the collection to be created. In this case, the + result of the prompt + will contain the object path of the new item. + + An item can be deleted by calling the + Delete() + method on the Item interface. + + When deleting an item, the service may need to prompt the user for additional + information. In this case, a prompt object is returned. It + must be acted upon in order for + the item to be deleted. + Client applications with special needs can create a new collection by calling the CreateCollection() - method on the Service interface. A client application must have - opened a session before a collection can be created. The - - A collection may be marked as private on creation. A private collection and the - items within it may only be unlocked by the application that created the collection. - Service implementors may choose not to implement this feature and should ignore the - private argument when - creating a collection. - Client applications that demand this feature, should check the the - Private - property after creating a collection to see if the request for a private collection - was ignored. + method on the Service interface. When creating a collection, the properties of the new + collection are specified. The service may ignore or change these properties when creating + the collection. + + When creating a collection, the service may need to prompt the user for additional + information. In this case, a prompt object is returned. It + must be acted upon in order for + the collection to be created. In this case, the + result of the prompt + will contain the object path of the new collection. A collection can be deleted by calling the Delete() - method on the Service interface. A client application must have - opened a session before a collection can be created. - However the collection does not need to be unlocked. In addition private collections can - be deleted by any application. + method on the Collection interface. + + When deleting a collection, the service may need to prompt the user for additional + information. In this case, a prompt object is returned. It + must be acted upon in order for + the collection to be deleted. + @@ -157,6 +181,19 @@ It's important to remember that attributes are not part of the secret. Services implementing this API will probably store attributes in an unencrypted manner in order to support simple and effecient lookups. + + In order to search for items, use the + SearchItems() + method of the Service interface. The matched items will be returned in two sets. The + unlocked return value will contain the object paths + of all the items that are not locked. The locked return + value will contain object paths of items that are locked, which can be + unlocked if desired. + + The + SearchItems() + method of the Collection interface is similar, except for it only searches a single collection. + @@ -209,7 +246,7 @@ encrypted secrets would be an excersize of questionable value. This API was desigened by GNOME and KDE developers with the goal of having - a common way to store secrets. It's predecessors are the desktop specific APIs + a common way to store secrets. Its predecessors are the desktop specific APIs used by GNOME Keyring and KWallet.
@@ -295,57 +332,100 @@ - - Authentication or Unlocking + + Locking and Unlocking Some items and/or collections may be marked as locked by the service. - The secrets of locked items cannot be accessed. Locked items or collections + The secrets of locked items cannot be accessed. Additionally, locked items or collections cannot be modified by the client application. - 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 - actually unlocked. - - The service will then unlock the item or collection, perhaps by prompting the - user for a password, or it could require use a hardware token of some sort. - - After the service tries to unlock an item or collection, whether successfully - or unsuccessfully, the - - Authenticated() - 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 - items that were successfully authenticated. In addition if the unlock process is not - yet complete for some items or collections, the service should stop trying to ask the - user to unlock or authenticate them. - It's up to the service whether to unlock items individually, or collections as a whole. The client application should act as if it must unlock each item individually. A service may upon unlocking a collection, unlock all items in that collection. If a service is not able to unlock an item individually, it should treat a request to unlock - an item as a request to unlock the connection that the item is in. The Authenticated signal - should however still be emitted for the individual items that were requested to be unlocked. + an item as a request to unlock the connection that the item is in. - A service may choose to authenticate items or collections just for a single client + A service may choose to unlock 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. + items or collections unlocked by a another client application. - A client application should always be ready to call BeginAuthenticate() the secrets + A client application should always be ready to unlock the items for 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). + sleeping). The inherent race conditions present due to this are unavoidable, and must be + handled gracefully. + + In order to unlock an item or collection the service's + + Unlock() + method is called with one or more DBus object paths of items or collections. The + Unlock() will return the DBus object paths of objects it could + immediately unlock without prompting. + + The Unlock() method may also return a + prompt object. If a prompt + object is returned, it must be acted upon in order to complete + the unlocking of the remaining objects. The + result of the prompt + will contain the object paths that were successfully unlocked by the prompt. + + In order to lock an item or collection the service's + + Lock() + method is called with one or more DBus object paths of items or collections. The + Lock() will return the DBus object paths of objects it could + immediately lock without prompting. + + The Lock() method may also return a + prompt object. If a prompt + object is returned, it must be acted upon in order to complete + the locking of the remaining objects. The + result of the prompt + will contain the object paths that were successfully locked by the prompt. + + + + Prompts and Prompting + + In order to complete various operations, such as unlocking a collection, the + service may need to prompt the user for additional information, such as a master password. + + The prompts are displayed by the service on behalf of the client application. + + Operations that require a prompt to complete will return a prompt object. The client + application must then call the + Prompt() + method of the prompt object to display the prompt. Client applications can use the + window-id + argument to display the prompt attached to their application window. + + Once the user provides the additional required information to the prompt, the service + completes the operation that required the prompt. Then it emits the the + Completed + signal of the prompt object. The result argument of + the signal contains operation an operation specific result. + + Either the user or the client application can dismiss a prompt. In this case the + operation that required the additional information is cancelled. The client application + can dismiss a prompt by calling the + Dismiss() + method of the prompt object. The Completed signal will be emitted + with its dismissed argument set to + TRUE. + + Once the Completed signal is emitted on a prompt object, it + is no longer valid. Prompt objects are specific to the client application's connection + to the DBus bus. Once an application disconnects, all its prompts are no longer valid. + + There is an inherent race between the Dismiss() method and the + Completed signal. An application calling Dismiss() + must be prepared to handle the fact that the Completed has already been + emitted (although perhaps not received by the client). In addition the client must be prepared + to handle the fact that the prompt object is no longer valid. @@ -356,7 +436,7 @@ focused tools should make use of these when necessary. This specification does not mandate the use of master passwords to lock a - collection of secrets. The service may choose to implement any method for authenticating + collection of secrets. The service may choose to implement any method for locking secrets. This specification does not mandate any form of access control. The service may -- cgit v1.2.3-70-g09d2