From a1535b2d74866e3307f1ae67debcbce9e5cc0a19 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 28 Nov 2009 17:52:39 +0000 Subject: Rename API to 'Secret Service API' This was discussed on the mailing list a while back. Interfaces: org.freedesktop.Secret.Xxxx Service: org.freedesktop.Secrets Object Paths: /org/freedesktop/secrets/xxxx --- secret-service/README | 2 +- secret-service/org.freedesktop.Secrets.xml | 26 ++++---- secret-service/specification.xml | 100 +++++++++++++---------------- 3 files changed, 59 insertions(+), 69 deletions(-) diff --git a/secret-service/README b/secret-service/README index 3f9eadd..72a9997 100644 --- a/secret-service/README +++ b/secret-service/README @@ -17,4 +17,4 @@ html/style.css to that location. Then open the resulting html/index.html in your favourite browser. -Michael Leupold \ No newline at end of file +Michael Leupold diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index f2f9761..c514438 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -3,11 +3,11 @@ - Secret Storage specification + Secret Service API Specification 0.1 Copyright (C) 2009 Stef Walter <stef@memberwebs.com> @@ -22,8 +22,8 @@ * --> - - Errors returned by the Secrets API. + + Errors returned by the Secret Service API. An object (session, collection) already exists with the same name. @@ -84,10 +84,10 @@ - + - The Secrets service manages all the sessions and collections. + The Secret Service manages all the sessions and collections. @@ -205,7 +205,7 @@ - + A collection of items containing secrets. @@ -300,9 +300,9 @@ * --> - + - + An item contains a secret, lookup attributes and has a label. @@ -360,9 +360,9 @@ * --> - + - + A session tracks state between the service and a client application. @@ -400,9 +400,9 @@ * --> - + - + A prompt necessary to complete an operation. diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 97d4b3b..92f5f68 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -1,11 +1,9 @@ - Secrets API Draft + Secrets Service API Draft - Secrets 0.1 DRAFT - + Secrets Service 0.1 DRAFT @@ -33,7 +31,7 @@ 2008-2009 - The Secrets API Authors + The Secrets Service API Authors @@ -43,14 +41,14 @@ Introduction - The Secrets API allows client applications to store secrets securily in a + The Secret Service API allows client applications to store secrets securily in a 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 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 Secret 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 lookup attributes are not treated as secret material, and the service may choose to not encrypt attributes when storing them to disk. @@ -86,10 +84,10 @@ Each secret is stored together with lookup attributes and a label. These together - form an item. + form an item. A group of items together form a - collection. + collection. 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 @@ -107,19 +105,19 @@ The service must prevent locked collections or items from modification. On such an invalid access the - IsLocked + IsLocked error should be raised. Client applications without special requirements should store in the default collection. Use the - + DefaultCollection property on the Service interface to determine the default collection. In addition 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 @@ -127,22 +125,22 @@ 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 + must be acted upon in order for the collection to be created. In this case, the - result of the prompt + result of the prompt will contain the object path of the new item. An item can be deleted by calling the - Delete() + 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 + 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. When creating a collection, the properties of the new collection are specified. The service may ignore or change these properties when creating @@ -150,18 +148,18 @@ 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 + must be acted upon in order for the collection to be created. In this case, the - result of the prompt + result of the prompt will contain the object path of the new collection. A collection can be deleted by calling the - Delete() + Delete() 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 + must be acted upon in order for the collection to be deleted. @@ -187,7 +185,7 @@ manner in order to support simple and effecient lookups. In order to search for items, use the - SearchItems() + 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 @@ -195,7 +193,7 @@ unlocked if desired. The - SearchItems() + SearchItems() method of the Collection interface is similar, except for it only searches a single collection. @@ -208,14 +206,14 @@ 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. A session is closed when the client application disconnects from the DBus session bus. Alternatively the client application can call the - Close() + Close() method on the session interface. Once a session is closed all session specific negotiations will be dropped by the service. @@ -227,10 +225,10 @@ Transfer of Secrets To access or store secrets, use the - GetSecret(), - SetSecret() + GetSecret(), + SetSecret() methods on the item interface, or the - GetSecrets(), + GetSecrets(), method on the service interface. You must specify a session when retrieving or storing a secret. The session @@ -258,13 +256,13 @@ The client application opens a session with the service, and then calls the - + Negotiate() method on that session. The algorithms argument to the Negotiate() method specifies a set of algorithms to be used together for key agreement and encryption. The other arguments are algorithm specific. If a service does not support a specific set of algorithms, a - + NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. @@ -285,9 +283,9 @@ Algorithm string - + Negotiate input - + Negotiate output Secret parameter @@ -312,9 +310,9 @@ Algorithm string - + Negotiate input - + Negotiate output Secret parameter @@ -360,31 +358,31 @@ 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 + 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 + 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 + 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 + result of the prompt will contain the object paths that were successfully locked by the prompt. @@ -398,21 +396,21 @@ Operations that require a prompt to complete will return a prompt object. The client application must then call the - Prompt() + 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 + 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() + Dismiss() method of the prompt object. The Completed signal will be emitted with its dismissed argument set to TRUE. @@ -459,7 +457,7 @@ Object Paths - The various DBus object paths used with the Secrets API are designed to be human + The various DBus object paths used with the Secret Service API are designed to be human readable but not displayed to the user. The object path of an item or collection should not change for its lifetime, under normal circumstances. @@ -495,15 +493,7 @@ - - + + + -- cgit v1.2.3-70-g09d2