From 46ff673063f32027802edf83bfff98f274149036 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 16:38:14 +0200 Subject: Add the current docbook part of the spec and the D-Bus introspection part converted to the Telepathy D-Bus Introspection spec. tools/spec-to-introspect.xsl converts the Telepathy format to the EggDBus format used by keyring. --- secret-service/org.freedesktop.Secrets.xml | 397 ++++++++++++++++++++++++++ secret-service/specification.xml | 418 ++++++++++++++++++++++++++++ secret-service/tools/spec-to-introspect.xsl | 225 +++++++++++++++ 3 files changed, 1040 insertions(+) create mode 100644 secret-service/org.freedesktop.Secrets.xml create mode 100644 secret-service/specification.xml create mode 100644 secret-service/tools/spec-to-introspect.xsl diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml new file mode 100644 index 0000000..ac43135 --- /dev/null +++ b/secret-service/org.freedesktop.Secrets.xml @@ -0,0 +1,397 @@ + + + + + Secret Storage specification + 0.1 + + + + + Errors returned by the Secrets API. + + + An object (session, collection) already exists with the same name. + + + + + The object must be unlocked before this action can be carried out. + + + + + The algorithm is not supported. + + + + + A session must be established before this action can be carried out. + + + + + + + + The #Secret type holds a (possibly encoded) secret. + + Algorithm used to encode the secrets value. + + + Algorithm dependent parameters for secret value encoding. + + + Possibly encoded secret value + + + + + A mapping from object-paths to Secret structs + + D-Bus object-path + + + A secret + + + + + + + + + + + The Secrets service manages all the sessions and collections. + + + + The object paths of all collections (ie: keyrings) + + + + + The object path of the default collection, or an empty string if no collections exist. + + + + + Open a unique session for the caller application. + + The object path of the session. + + + + + Create a new collection with the specified access attributes. + + + The display name of the new collection + + + + Whether this is a private collection or not. + + + + + + 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. + + + + + Retrieve multiple secrets from different items. + + Items to get secrets for. + + + + Secrets for the items. + + + + + A collection was created. + + + Collection that was created + + + + + A collection was deleted. + + + Collection that was created + + + + + + + + + + + + + + A collection of items containing secrets. + + + Items in this collection. + + + + Whether this is a private collection or not. + + + + The displayable label of this collection. + + + + + Whether the collection is locked and must be authenticated by the client application. + + + + + The unix time when the collection was created. + + + + The unix time when the collection was last modified. + + + + Delete this collection. + + + + Search for items in this collection matching the lookup attributes. + + Attributes to match. + + + Items that matched the attributes. + + + + + + + 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 secret to store in the new item. + + + + The label for the new item. + + + + Whether to replace an item with the same attributes or not. + + + + The new item, or previous item if replaced. + + + + + A new item in this collection was created. + + + The item that was created. + + + + + An item in this collection was deleted. + + + The item that was deleted. + + + + + An item in this collection changed. + + + The item that was changed. + + + + + + + + + + + + + + An item contains a secret, lookup attributes and has a label. + + + Whether the item is locked and requires authentication, or not. + + + + The lookup attributes for this item. + + + + The displayable label for this item. + + + + The secret, usually transferred encrypted. + + + + The unix time when the item was created. + + + + The unix time when the item was last modified. + + + + Delete this item. + + + + + + + + + + + + + A session tracks state between the service and a client application. + + + Close this session. + + + + Negotiate key agreement and encryption. + + + The algorithm the caller wishes to use. + + + + Input arguments for the algorithm. + + + + Output of the negotiation. + + + + Whether the negotiation is complete or requires further calls. + + + + + 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. + + + + + + + + diff --git a/secret-service/specification.xml b/secret-service/specification.xml new file mode 100644 index 0000000..57f7cb2 --- /dev/null +++ b/secret-service/specification.xml @@ -0,0 +1,418 @@ + + + + + Secrets API Specification + + Secrets 0.1 + + + + + + Stef + Walter + + GNOME Keyring Developer +
+ stef@memberwebs.com +
+ + + + Michael + Leupold + + KWallet Developer +
+ lemma@confuego.org +
+ + + + + + 2008-2009 + The Secrets API Authors + + + + + + API Documentation + + Introduction + + The Secrets 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 and/or authenticated 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 + lookup attributes are not treated as secret material, and the service may choose + to not encrypt attributes when storing them to disk. + + + + Secrets + + A secret is something an application wishes to store securely. A good example + is a password that an application needs to save and use at a later date. + + Within this API a secret value is treated as an array of bytes. It is + recommended that a secret consist of user readable text, although this API has + no such requirement. + + Applications wishing to store multiple values as part of a single secret, may + choose to use a textual format to combine these values into one. For example, the + 'desktop' key file format, or XML or another form of markup. + + Secrets may be encrypted when transferred + to the client application and vice versa. + + The Secret structure encapsulates + a secret value along with it's transfer encryption parameters. + + + + Collection and Items + + Each secret is stored together with + lookup attributes and a label. These together + form an item. + + A group of items together form a + 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 + object paths. The object path of a collection or item should not change for it's lifetime, + under normal circumstances. + + It is strongly recommended that client applications use + lookup attributes to find items rather than + recording the object path of a stored item. This allows maximum interoperability. + + 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. + + The service must prevent locked collections or items from modification. On + such an invalid access the + 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. + + 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. + + 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. + + + + Lookup Attributes + + Attributes can and should be stored with a secret to facilitate lookup + of the secret at a later date. + + An attribute constists of a name, and a value. Both parts are simple + strings. + + The service may have additional requirements as to what can be present + in an attribute name. It is recommended that attribute names are human + readable, and kept simple for the sake of simplicity. + + During a lookup, attribute names and values are matched via case-sensitive + string equality. + + 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. + + + + 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. + + 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. + + 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. + + + + Transfer of Secrets + + 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. + + The Secrets API has provision to encrypt secrets while in transit between + the service and the client application. + + The encryption is not envisioned to withstand man in the middle attacks, or + other active attacks. It is envisioned to minimize storage of plain text secrets + in memory and prevent storage plain text storage of secrets in a swap file or other + caching mechanism. + + Many client applications may choose not to make use of the provisions to + encrypt secrets in transit. In fact for applications unable to prevent their own + memory from being paged to disk (eg: Java, C# or Python apps), transfering + 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 + used by GNOME Keyring and KWallet. + + + Negotiation of Algorithms + + In order to encrypt secrets in transit, the service and the client + application must agree on an algorithm, and some algorithm specific + parameters (eg: a key). + + 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. + + An algorithm may require that the Negotiate() method is called multiple + times in succession to be complete. Each iteration transfers algorithm specific + data back forth between the service and the client. + + Once an algorithm has been negotiated, it is used for all transfer of secrets + between the service and the client application in both directions. Algorithm + specific parameters may be transfered with each + secret. + + + + Algorithm: plain + + + Algorithm string: plain + + Negotiate input: empty string + + Negotiate output: empty string + + Secret parameter: empty string + + + The plain algorithm does no encryption whatsoever. + + It is strongly recommended that a service implementing this API support + the plain algorithm. + + + + Algorithm: dh-ietf1024-aes128-cbc-pkcs7 + + + Algorithm string: dh-ietf1024-aes128-cbc-pkcs7 + + Negotiate input: client dh pub key as an array of bytes + + Negotiate output: service dh pub key as an array of bytes + + Secret parameter: 16 byte AES initialization vector. + + + TODO: Document + + + + + + Authentication or 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 + 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 + 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 session 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. + + 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. + + + + What's not included in the API + + A service may implement additional DBus interfaces for further capabilities not + included in this specification. Password management applications or other narrowly + 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 + secrets. + + This specification does not mandate any form of access control. The service may + choose to allow certain applications to access a keyring, and others. + + [TODO: complete] + + + + + Notes for Service Implementors + + [TODO: complete] + + + + + + D-Bus API Reference + + + + Object Paths + + + The various DBus object paths used with the Secrets 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. + + + /org/freedesktop/Secrets + The object path for the service. + + + + /org/freedesktop/Secrets/collection/xxxx + The object path for a collection, where xxxx represents a + possibly encoded or truncated version of the initial label of the collection. + + + + /org/freedesktop/Secrets/collection/xxxx/iiii + The object path for an item, where xxxx is the collection (above) + and iiii is an auto-generated item specific identifier. + + + + /org/freedesktop/Secrets/session/ssss + The object path for a session, where ssss is an auto-generated + session specific identifier. + + + + /org/freedesktop/Secrets/default + The default collection for client applications to store secrets is available under + this object path in addition to its real object path (above). + + + + + + org.freedesktop.Secrets.Collection Interface + + + org.freedesktop.Secrets.Collection Interface + Collection of items + + + + + + + + + + + + + + + diff --git a/secret-service/tools/spec-to-introspect.xsl b/secret-service/tools/spec-to-introspect.xsl new file mode 100644 index 0000000..b2682b1 --- /dev/null +++ b/secret-service/tools/spec-to-introspect.xsl @@ -0,0 +1,225 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Node doesn't contain a type. + + + + + + + + + + ObjectPath + String + Byte + Boolean + Int16 + UInt16 + Int32 + UInt32 + Int64 + UInt64 + Double + Signature + + Array< + + + + > + + + + + Unknown DBus Type + + + + + + + + + + + + + + Dict< + + + , + + + + > + + + + Unspecified type . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3-70-g09d2