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 From 3b64399e5549a017b82fb4f7f1a0cc433a0a2492 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 23:56:00 +0200 Subject: Add spec-to-docbook.xsl for converting a telepathy spec to DocBook XML. Improve spec-to-introspect.xsl - no more extra spaces in type declarations. --- secret-service/org.freedesktop.Secrets.xml | 4 +- secret-service/tools/resolve-type.xsl | 122 +++ secret-service/tools/spec-to-docbook.xsl | 1168 +++++++++++++++++++++++++++ secret-service/tools/spec-to-introspect.xsl | 104 +-- 4 files changed, 1305 insertions(+), 93 deletions(-) create mode 100644 secret-service/tools/resolve-type.xsl create mode 100644 secret-service/tools/spec-to-docbook.xsl diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index ac43135..b69f06d 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -48,7 +48,7 @@ --> - The #Secret type holds a (possibly encoded) secret. + The Secret type holds a (possibly encoded) secret. Algorithm used to encode the secrets value. @@ -65,7 +65,7 @@ D-Bus object-path - + A secret diff --git a/secret-service/tools/resolve-type.xsl b/secret-service/tools/resolve-type.xsl new file mode 100644 index 0000000..a37f2af --- /dev/null +++ b/secret-service/tools/resolve-type.xsl @@ -0,0 +1,122 @@ + + + + + + + + + + + + + + + + + + + + + + + Node doesn't contain a type. + + + + + + + + + + + + ObjectPath + String + Byte + Boolean + Int16 + UInt16 + Int32 + UInt32 + Int64 + UInt64 + Double + Signature + Variant + + Dict< + + + + , + + + + > + + + Array< + + + + > + + + + + Unknown DBus Type + + + + + + + + + + + + + + Dict< + + + , + + + + > + + + + Unspecified type . + + + + + diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl new file mode 100644 index 0000000..33446a1 --- /dev/null +++ b/secret-service/tools/spec-to-docbook.xsl @@ -0,0 +1,1168 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + . + + + + + + + + + + + + + + + + + + + + + + ERR: cannot find D-Bus interface, method, + signal or property called ' + + ' + + + + + + + + + + + + + ERR: Cannot use tp:member-ref when not in an + <interface> + + + + + + + + + + ERR: interface + + has no signal/method/property called + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added in version . + + + + + + + + + Changed in version : + + + + Changed in version + + + + + + + + Deprecated since version . + + + + + + + + + + + + + Errors + + + + + + Types + + + + + + + + Simple types + + + + + + + Enumerated types + + + + + + + Sets of flags + + + + + + + Struct types + + + + + + + Map types + + + + + + + Types defined elsewhere + + + + + + + + + + + <literal><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></literal> + + + + + + + + + + + + + + + + + + + + + + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + This interface is + and is likely to cause havoc to your API/ABI if bindings are generated. + Don't include it in libraries that care about compatibility. + + + + + + + Implementations of this interface must also implement: + + + + + + + + + + + + + + + + + + + + + + Methods + + + + + + + Signals + + + + + + + Telepathy Properties + + Accessed using the + + org.freedesktop.Telepathy.Properties + + + + + + + + + + + D-Bus Properties + + Accessed using the org.freedesktop.DBus.Properties interface. + + + + + + + + + + + + + + + + ERR: missing @name on a tp:flags type + + + + + + ERR: missing @type on tp:flags type + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + + + + + + + + + ERR: missing @name on a tp:enum type + + + + + + ERR: missing @type on tp:enum type + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + + + + + + + + + + + + + + + = + + + + + + + + + + + (Undocumented) + + + + + + + + + + + + + + ERR: property + + does not have an interface as parent + + + + + + ERR: missing @name on a property of + + + + + + + + ERR: missing @type on property + + : ' + + ' + + + + + + - + + + + + + , + + + read-only + + + write-only + + + read/write + + + + ERR: unknown or missing value for + @access on property + + : ' + + ' + + + + + + + + + + + + + + + + + + − + + + + + + + + + + + + + + + + <literal><xsl:value-of select="@name"/></literal> + + + + + In bindings that need a separate name, arrays of + should be called + . + + + + Members + + + + + + + + + + + − + + + + + + + ERR: missing @name on a tp:simple-type + + + + + + ERR: missing @type on tp:simple-type + + + + + + + + <literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> + + + + + + + + + + + + + + + ERR: missing @name on a tp:external-type + + + + + + ERR: missing @type on tp:external-type + + + + + + + + − + + Defined by: + + + + + − ( + + , + ) + + + + − a{ + + → + } + + + + + + <literal> + <xsl:value-of select="@name"/> + </literal> + + + + + + + + In bindings that need a separate name, arrays of + should be called + . + + + Arrays of don't generally + make sense. + + + + + struct + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ERR: method + + does not have an interface as parent + + + + + + ERR: missing @name on a method of + + + + + + + + + ERR: an arg of method + + has no type + + + + + + + ERR: an 'in' arg of method + + has no name + + + + + + + INFO: an 'out' arg of method + + has no name + + + + + + ERR: an arg of method + + has direction neither 'in' nor 'out' + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + + + + + + + + + + + Parameters + + + + Name + Type + Direction + Description + + + + + + +
+ + + + + Possible errors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ( + + + + ) + + + + + + + + + a{ + + + + } + + + + + + + ERR: Unable to find type ' + + ' + + + + + + + + ERR: tp:type ' + + ' has D-Bus type ' + + ' but has been used with type=' + + ' + + + + + + + + + + + + ( + + + + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + + + (undocumented) + + + + + + + + + + + + + + + - + + + + + + + + + + (undocumented) + + + + + + + + + + + + + + + + + + + (generic description) + + + (Undocumented.) + + + + + + + + + + + ERR: signal + + does not have an interface as parent + + + + + + ERR: missing @name on a signal of + + + + + + + + + ERR: an arg of signal + + has no type + + + + + ERR: an arg of signal + + has no name + + + + + + + INFO: an arg of signal + + has unnecessary direction 'in' + + + + + ERR: an arg of signal + + has direction other than 'in' + + + + + + + + <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> + + + + + + + + + + + + + + + + + Parameters + + + + Name + Type + Description + + + + + + +
+ + + + + + + + <xsl:value-of select="tp:title"/> + + + + + + + + + + + Interfaces + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Stray text: {{{ + + }}} + + + + + + + Unrecognised element: { + + } + + + + + + + diff --git a/secret-service/tools/spec-to-introspect.xsl b/secret-service/tools/spec-to-introspect.xsl index b2682b1..ca8b4b6 100644 --- a/secret-service/tools/spec-to-introspect.xsl +++ b/secret-service/tools/spec-to-introspect.xsl @@ -8,18 +8,19 @@ Copyright 2009 Michael Leupold - This program is free software; you can redistribute it and/or - modify it under the terms of the GNU General Public License as - published by the Free Software Foundation; either version 2 of - the License, or (at your option) any later version. + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. - This program is distributed in the hope that it will be useful, + This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License - along with this program. If not, see . + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA --> + + @@ -40,87 +43,6 @@ - - - - - - - - - - - - - - - - - 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 . - - - - - @@ -151,7 +73,7 @@ - + -- cgit v1.2.3-70-g09d2 From b4cef1c66a4fd7e19ebcb770fbbc406a4ece4db3 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Fri, 31 Jul 2009 23:58:50 +0200 Subject: sect[1234] -> section --- secret-service/tools/spec-to-docbook.xsl | 76 ++++++++++++++++---------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index 33446a1..b69cf75 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -192,47 +192,47 @@ - +
Simple types - +
- +
Enumerated types - +
- +
Sets of flags - +
- +
Struct types - +
- +
Map types - +
- +
Types defined elsewhere - +
@@ -266,7 +266,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -302,21 +302,21 @@ - +
Methods - +
- +
Signals - +
- +
Telepathy Properties Accessed using the @@ -327,11 +327,11 @@ - +
- +
D-Bus Properties Accessed using the org.freedesktop.DBus.Properties interface. @@ -339,12 +339,12 @@ - +
- +
@@ -362,7 +362,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -400,7 +400,7 @@ - +
@@ -419,7 +419,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -457,7 +457,7 @@ - +
@@ -546,7 +546,7 @@ - +
<literal><xsl:value-of select="@name"/></literal> @@ -558,13 +558,13 @@ . - +
Members - - +
+
@@ -590,7 +590,7 @@ - +
<literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> @@ -600,7 +600,7 @@ - +
@@ -642,7 +642,7 @@ - +
<literal> <xsl:value-of select="@name"/> @@ -673,7 +673,7 @@ <glosslist> <xsl:apply-templates select="tp:member" mode="description"/> </glosslist> - </sect2> + </section> </xsl:template> <xsl:template match="arg" mode="paramdef"> @@ -755,7 +755,7 @@ </xsl:choose> </xsl:for-each> - <sect3> + <section> <title id="{concat(../@name, concat('.', @name))}"> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> @@ -810,7 +810,7 @@ - +
@@ -1032,7 +1032,7 @@ - +
<literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> @@ -1066,7 +1066,7 @@ - +
-- cgit v1.2.3-70-g09d2 From 20c5210807cae6c7724d1aebe2f1d5c3e0f300eb Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 02:53:32 +0200 Subject: Remove superfluous --- secret-service/tools/spec-to-docbook.xsl | 32 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index b69cf75..72763e6 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -759,23 +759,21 @@ <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + -- cgit v1.2.3-70-g09d2 From 4ad12bd950a49c2f96c6125076e141e94cdcde49 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 03:33:14 +0200 Subject: @direction => uppercase. --- secret-service/tools/spec-to-docbook.xsl | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index 72763e6..00fc56e 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -42,6 +42,14 @@ + + + + IN + OUT + + + @@ -663,7 +671,7 @@ make sense. - + struct @@ -678,6 +686,10 @@ + + + + @@ -690,11 +702,15 @@ - + - + + + + + -- cgit v1.2.3-70-g09d2 From 01676233cf76a15dc33555ba7d7fb58d202a31e5 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 04:22:37 +0200 Subject: Minor cleanups. Add copyright (Telepathy D-Bus doesn't know authors). --- secret-service/org.freedesktop.Secrets.xml | 6 ++ secret-service/tools/spec-to-docbook.xsl | 144 +++++------------------------ 2 files changed, 29 insertions(+), 121 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index b69f06d..da5d609 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -9,6 +9,12 @@ Secret Storage specification 0.1 + + Copyright (C) 2009 Stef Walter <stef@memberwebs.com> + + + Copyright (C) 2009 Michael Leupold <lemma@confuego.org> + - - - + + + @@ -569,7 +569,7 @@
Members - +
@@ -690,30 +690,23 @@ - - - + + + + + + - - - - - - - - - - - - - - - - + + + + + + @@ -796,22 +789,9 @@ - - Parameters - - - - Name - Type - Direction - Description - - - - - - -
+ + + @@ -931,32 +911,7 @@ - - - - - - - - - - (undocumented) - - - - - - - - - - - - - - - - - + @@ -1064,21 +1019,9 @@ - - Parameters - - - - Name - Type - Description - - - - - - -
+ + + @@ -1102,17 +1045,6 @@ Interfaces - - - - - - - - - - - @@ -1122,36 +1054,6 @@ - - -- cgit v1.2.3-70-g09d2 From eb47416f4a6e75f77bda61481d2b754b1e5c7638 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 12:11:59 +0200 Subject: Enable building the whole spec with XInclude. --- secret-service/specification.xml | 141 +++++++++++++------------------ secret-service/tools/spec-to-docbook.xsl | 6 +- 2 files changed, 64 insertions(+), 83 deletions(-) diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 57f7cb2..6301ff8 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -72,10 +72,10 @@ 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 + Secrets may be encrypted when transferred to the client application and vice versa. - The Secret structure encapsulates + The Secret structure encapsulates a secret value along with it's transfer encryption parameters. @@ -84,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 @@ -105,18 +105,18 @@ 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 + 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() + CreateCollection() method on the Service interface. A client application must have opened a session before a collection can be created. The @@ -124,20 +124,20 @@ 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. + creating a collection. Client applications that demand this feature, should check the the - Private property + 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() + 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 @@ -167,16 +167,16 @@ between the client application and the service. A session is established by calling the service's - OpenSession() + 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 + AlreadyExists error. 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 and authentication should be dropped by the service. @@ -205,7 +205,7 @@ 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 @@ -214,13 +214,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 + NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. @@ -231,19 +231,19 @@ 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. - + secret. +
- +
Algorithm: plain Algorithm string: plain - + Negotiate input: empty string - + Negotiate output: empty string - + Secret parameter: empty string @@ -251,23 +251,23 @@ 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 - +
@@ -281,7 +281,7 @@ In order to unlock an item or collection a session is established by the client application, and the - BeginAuthenticate() + 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. @@ -291,11 +291,11 @@ After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the - Authenticated + Authenticated signal on the session interface is emitted. The client application may, but is not required to, call the - CompleteAuthenticate() + 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 @@ -346,62 +346,43 @@ D-Bus API Reference - - - Object Paths - + + 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 + 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 + 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 + /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 - - - - - - - - - - + + /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). + + + + + + + + + + + + - + diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index af158fa..e37c1a7 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -192,7 +192,7 @@ - + Types @@ -1043,13 +1043,13 @@ --> - + Interfaces - + -- cgit v1.2.3-70-g09d2 From 28ed9f02cd60403d2b1a92c13f1c06058fa58136 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 13:00:19 +0200 Subject: Add params to control toc generation. --- secret-service/params-html.xsl | 34 ++++++++++++ secret-service/specification.xml | 95 ++++++++++++++++++++------------ secret-service/tools/spec-to-docbook.xsl | 6 +- 3 files changed, 97 insertions(+), 38 deletions(-) create mode 100644 secret-service/params-html.xsl diff --git a/secret-service/params-html.xsl b/secret-service/params-html.xsl new file mode 100644 index 0000000..5f3fb27 --- /dev/null +++ b/secret-service/params-html.xsl @@ -0,0 +1,34 @@ + + + + + + 3 + 0 + + book toc + part nop + chapter nop + + style.css + ansi + + diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 6301ff8..b631b6f 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -75,7 +75,7 @@ Secrets may be encrypted when transferred to the client application and vice versa. - The Secret structure encapsulates + The Secret structure encapsulates a secret value along with it's transfer encryption parameters. @@ -105,18 +105,20 @@ 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 + + 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() + + CreateCollection() method on the Service interface. A client application must have opened a session before a collection can be created. The @@ -126,11 +128,12 @@ 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. + 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() + 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 @@ -167,16 +170,18 @@ between the client application and the service. A session is established by calling the service's - OpenSession() + + 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 + + AlreadyExists error. 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 and authentication should be dropped by the service. @@ -214,13 +219,14 @@ 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 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 + + NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. @@ -231,21 +237,29 @@ 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. + secret.
Algorithm: plain - - Algorithm string: plain - - Negotiate input: empty string - - Negotiate output: empty string - - Secret parameter: empty string - + + + Algorithm string + + Negotiate input + + Negotiate output + + Secret parameter + + + plain + empty string + empty string + empty string + + The plain algorithm does no encryption whatsoever. @@ -256,15 +270,23 @@
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. - + + + Algorithm string + + Negotiate input + + Negotiate output + + Secret parameter + + + dh-ietf1024-aes128-cbc-pkcs7 + client dh pub key as an array of bytes + service dh pub key as an array of bytes + 16 byte AES initialization vector + + TODO: Document
@@ -281,7 +303,8 @@ In order to unlock an item or collection a session is established by the client application, and the - BeginAuthenticate() + + 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. @@ -291,11 +314,13 @@ After the service tries to unlock an item or collection, whether successfully or unsuccessfully, the - Authenticated + + Authenticated() signal on the session interface is emitted. The client application may, but is not required to, call the - CompleteAuthenticate() + + 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 diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index e37c1a7..1de1f89 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -498,12 +498,12 @@ - - - + - + - + , -- cgit v1.2.3-70-g09d2 From c250c5aefcc8e14ffa54463a694c26370c1bcf6a Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 15:56:23 +0200 Subject: -> Docbook 5.0 --- secret-service/params-html.xsl | 1 + secret-service/specification.xml | 22 +- secret-service/tools/spec-to-docbook.xsl | 335 ++++++++++++++++++++----------- 3 files changed, 226 insertions(+), 132 deletions(-) diff --git a/secret-service/params-html.xsl b/secret-service/params-html.xsl index 5f3fb27..cc73eee 100644 --- a/secret-service/params-html.xsl +++ b/secret-service/params-html.xsl @@ -30,5 +30,6 @@ style.css ansi + 1 diff --git a/secret-service/specification.xml b/secret-service/specification.xml index b631b6f..7c1eafd 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -1,7 +1,5 @@ - - + Secrets API Specification @@ -40,7 +38,7 @@ - + API Documentation Introduction @@ -140,7 +138,7 @@ be deleted by any application. - + Lookup Attributes Attributes can and should be stored with a secret to facilitate lookup @@ -161,7 +159,7 @@ manner in order to support simple and effecient lookups. - + Sessions A session is established between a client application and a service. A session @@ -186,7 +184,7 @@ 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 @@ -293,7 +291,7 @@ - + Authentication or Unlocking Some items and/or collections may be marked as locked by the service. @@ -368,10 +366,10 @@ - + D-Bus API Reference - + Object Paths The various DBus object paths used with the Secrets API are designed to be human @@ -411,11 +409,11 @@ + omit-xml-declaration="no"/> @@ -192,7 +190,8 @@ - + + types Types @@ -246,7 +245,10 @@ - + <title> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/> + </xsl:attribute> <literal><xsl:value-of select="concat(../@namespace, '.', translate(@name, ' ', ''))"/></literal> @@ -274,85 +276,130 @@ -
- <literal><xsl:value-of select="@name"/></literal> + - - - - This interface is - and is likely to cause havoc to your API/ABI if bindings are generated. - Don't include it in libraries that care about compatibility. - - - + + + + + + + + + + D-Bus Interface + + + + + + + + + + + + + + + + + + + - - - Implementations of this interface must also implement: - - - - - - - - - - - - - + + + + + This interface is + and is likely to cause havoc to your API/ABI if bindings are generated. + Don't include it in libraries that care about compatibility. + + + + - - - - + + + + Implementations of this interface must also implement: + + + + + + + + + + + + + + - -
- Methods - -
- + + + + Methods + + + + + + Signals + + + + - -
- Signals - -
- + + + Methods + + + - -
- Telepathy Properties - - Accessed using the - - org.freedesktop.Telepathy.Properties - - - - - -
- + + + Signals + + + - -
- D-Bus Properties - - Accessed using the org.freedesktop.DBus.Properties interface. - - - - -
- + + + Telepathy Properties + + Accessed using the + + org.freedesktop.Telepathy.Properties + + + + + + + + + + + D-Bus Properties + + Accessed using the org.freedesktop.DBus.Properties interface. + + + + + + + + - + -
+ @@ -371,7 +418,10 @@
- <literal><xsl:value-of select="@name"/></literal> + + + + <literal><xsl:value-of select="@name"/></literal> @@ -428,7 +478,10 @@
- <literal><xsl:value-of select="@name"/></literal> + + + + <literal><xsl:value-of select="@name"/></literal> @@ -468,7 +521,7 @@
- + @@ -497,7 +550,10 @@ - + + + + - @@ -536,7 +592,7 @@ - + @@ -555,7 +611,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="@name"/></literal> @@ -599,7 +658,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="@name"/> − <xsl:value-of select="@type"/></literal> @@ -628,8 +690,11 @@ - - − + + + + + − Defined by: @@ -651,7 +716,10 @@
- + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat('type-', @name)"/> + </xsl:attribute> + <title> <literal> <xsl:value-of select="@name"/> </literal> @@ -709,7 +777,47 @@ </glossentry> </xsl:template> - <xsl:template match="method"> + <xsl:template match="method|signal" mode="funcsynopsis"> + <funcsynopsis> + <funcprototype> + <funcdef> + <function> + <xsl:value-of select="@name"/> + </function> + </funcdef> + <xsl:choose> + <xsl:when test="arg"> + <xsl:apply-templates select="arg" mode="paramdef"/> + </xsl:when> + <xsl:otherwise> + <void/> + </xsl:otherwise> + </xsl:choose> + </funcprototype> + </funcsynopsis> + </xsl:template> + + <xsl:template match="method|signal" mode="funcsynopsislinked"> + <funcsynopsis> + <funcprototype> + <funcdef> + <function linkend="{concat(parent::interface//@name, '.', @name)}"> + <xsl:value-of select="@name"/> + </function> + </funcdef> + <xsl:choose> + <xsl:when test="arg"> + <xsl:apply-templates select="arg" mode="paramdef"/> + </xsl:when> + <xsl:otherwise> + <void/> + </xsl:otherwise> + </xsl:choose> + </funcprototype> + </funcsynopsis> + </xsl:template> + + <xsl:template match="method" mode="detail"> <xsl:if test="not(parent::interface)"> <xsl:message terminate="yes"> @@ -764,26 +872,15 @@ </xsl:choose> </xsl:for-each> - <section> - <title id="{concat(../@name, concat('.', @name))}"> + <refsection> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@name, concat('.', @name))"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - - - - - - - - - + + @@ -804,7 +901,7 @@ -
+ @@ -949,7 +1046,7 @@ - + @@ -1001,18 +1098,14 @@ -
- + <refsection> + <xsl:attribute name="xml:id"> + <xsl:value-of select="concat(../@name, concat('.', @name))"/> + </xsl:attribute> + <title> <literal><xsl:value-of select="concat(../@name, concat('.', @name))"/></literal> - - - - - - - - + @@ -1023,11 +1116,11 @@ -
+ - + <xsl:value-of select="tp:title"/> @@ -1043,13 +1136,15 @@ --> - + + interfaces Interfaces - + + errors -- cgit v1.2.3-70-g09d2 From 24427d24927bbd22b3b82a6d04d3d0df05346867 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 1 Aug 2009 16:17:51 +0200 Subject: Add links to the funcsynopsis listing in the top section of each interface. Unfortunately xmlto doesn't generate links for them yet. --- secret-service/tools/spec-to-docbook.xsl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index b2cadd6..1917798 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -3,6 +3,7 @@ -- cgit v1.2.3-70-g09d2 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 From 5a9ca68453f5491b26570361e51c4f2a8be57e57 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Thu, 20 Aug 2009 03:18:02 +0000 Subject: Tag functions referenced in text with tag. --- secret-service/specification.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/secret-service/specification.xml b/secret-service/specification.xml index b61fe97..592cf13 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -222,8 +222,8 @@ 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 + 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 @@ -232,7 +232,7 @@ 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 + 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. @@ -306,7 +306,7 @@ 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 + 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 @@ -321,8 +321,8 @@ 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 + 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. @@ -339,7 +339,7 @@ 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 + 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. -- cgit v1.2.3-70-g09d2 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 From f568436db0a1bbb6da96b9443bc1043487d5fc5e Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Wed, 25 Nov 2009 02:42:39 +0000 Subject: Move the GetSecret, SetSecret and GetSecrets methods. Move to more relevant interfaces, and add secret parameter to CreateItem. --- secret-service/org.freedesktop.Secrets.xml | 71 ++++++++++++++++-------------- secret-service/specification.xml | 34 +++++++------- 2 files changed, 54 insertions(+), 51 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index b645022..cce5ddf 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -49,14 +49,14 @@ The Secret type holds a (possibly encoded) secret. - - Algorithm used to encode the secrets value. + + The session that was used to encode the secret. Algorithm dependent parameters for secret value encoding. @@ -71,7 +71,7 @@ D-Bus object-path - + A secret @@ -159,6 +159,19 @@ + + Retrieve multiple secrets from different items. + + Items to get secrets for. + + + The session to use to encode the secrets. + + + Secrets for the items. + + + A collection was created. @@ -240,6 +253,9 @@ The properties for the new item. + + The secret to store in the item, encoded with the included session. + Whether to replace an item with the same attributes or not. @@ -317,6 +333,23 @@ + + Retrieve the secret for this item. + + The session to use to encode the secret. + + + The secret retrieved. + + + + + Set the secret for this item. + + The secret to set, encoded for the included session. + + + @@ -357,36 +390,6 @@ - - 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. - - - The secret retrieved. - - - - - Retrieve multiple secrets from different items. - - Items to get secrets for. - - - Secrets for the items. - - - diff --git a/secret-service/specification.xml b/secret-service/specification.xml index f0314a7..97d4b3b 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -54,6 +54,10 @@ 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. + + This API was desigened by GNOME and KDE developers with the goal of having + a common way to store secrets. Its predecessors are the desktop specific APIs + used by GNOME Keyring and KWallet. @@ -223,32 +227,28 @@ Transfer of Secrets To access or store secrets, use the - GetSecret(), - GetSecrets(), - SetSecret() - methods on the session interface. + GetSecret(), + SetSecret() + methods on the item interface, or the + GetSecrets(), + method on the service 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. + You must specify a session when retrieving or storing a secret. The session + controls how the secret is encoded during transfer. 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 arbitrarilyby 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. + 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. Its predecessors are the desktop specific APIs - used by GNOME Keyring and KWallet. -
Negotiation of Algorithms -- cgit v1.2.3-70-g09d2 From 183f052520635ce550958a4fa6125c703a66b1e0 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 28 Nov 2009 17:44:09 +0000 Subject: Fix whitespace issue --- secret-service/org.freedesktop.Secrets.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index cce5ddf..f2f9761 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -253,7 +253,7 @@ The properties for the new item. - + The secret to store in the item, encoded with the included session. -- cgit v1.2.3-70-g09d2 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 From 7698a065526b2ce68cf626177b28cbedb276b60d Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 28 Nov 2009 18:06:47 +0000 Subject: Use the OpenSession function for algorithm Negotiation. This has several benefits: * Removes gray area of whether a single session could renegotiate a different key exchange. * Removes strange state that a session is in before negotiation of an algorithm. * Less API. * OpenSession() could be called multiple times for algorithms that require more than one back and forth negotiation. We have none of these presently. --- secret-service/org.freedesktop.Secrets.xml | 31 +++++---------- secret-service/specification.xml | 60 +++++++++++++++++------------- 2 files changed, 45 insertions(+), 46 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index c514438..430a81e 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -102,8 +102,17 @@ Open a unique session for the caller application. + + The algorithm the caller wishes to use. + + + Input arguments for the algorithm. + + + Output of the session algorithm negotiation. + - The object path of the session. + The object path of the session, if session was created. @@ -370,26 +379,6 @@ 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. - - - diff --git a/secret-service/specification.xml b/secret-service/specification.xml index 92f5f68..e69d116 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -254,12 +254,13 @@ 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. + When the client application opens a session + with the service, it calls the + + OpenSession() method on the service. The algorithms argument to the + OpenSession() 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 @@ -267,13 +268,20 @@ 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. + An algorithm may require that the OpenSession() method is + called multiple times in succession to be complete. Each iteration transfers + algorithm specific data back forth between the service and the client. The object path + '/' is returned from OpenSession() when session negotiation is + incomplete. - 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 + None of the algorithms documented in this initial version of the specification + require multiple calls to OpenSession(). + + When OpenSession() completes, it returns the session object + path along with a valid session object path. + + Once an session algorithm has been negotiated, it is used for all transfer a + secrets whenever that session is specified along with the secret.
@@ -282,11 +290,11 @@ - Algorithm string - - Negotiate input - - Negotiate output + Session algorithm + + Session input + + Session output Secret parameter @@ -309,23 +317,25 @@ - Algorithm string - - Negotiate input - - Negotiate output + Session algorithm + + Session input + + Session output Secret parameter dh-ietf1024-aes128-cbc-pkcs7 - client dh pub key as an array of bytes - service dh pub key as an array of bytes + Client DH pub key as an array of bytes + Service DH pub key as an array of bytes 16 byte AES initialization vector - TODO: Document + The public keys are transferred as an array of bytes representing an + unsigned integer of arbitrary size, most-significant byte first (e.g., the + integer 32768 is represented as the 2-byte string 0x80 0x00)
-- cgit v1.2.3-70-g09d2 From 3966b1da9e55e941de2ff3f31df336d3490345b0 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 28 Nov 2009 18:27:01 +0000 Subject: Move dismissed argument in Prompt.Completed signal. Move dismissed argument first, so it's easier to parse the result variant (or ignore it). --- secret-service/org.freedesktop.Secrets.xml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index 430a81e..5757abd 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -408,14 +408,13 @@ The prompt and operation completed. + + Whether the prompt and operation were dismissed or not. + The possibly empty, operation specific, result. - - Whether the prompt and operation were dismissed - or not. - -- cgit v1.2.3-70-g09d2 From 33d5f4c05d1f52d1c212633818bdd1038ea5b467 Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sun, 7 Feb 2010 11:35:07 +0100 Subject: Properly added parameters for xhtml generation. --- secret-service/Makefile | 4 ++-- secret-service/docbook-params.xsl | 39 +++++++++++++++++++++++++++++++++++++++ secret-service/params-html.xsl | 37 ------------------------------------- 3 files changed, 41 insertions(+), 39 deletions(-) create mode 100644 secret-service/docbook-params.xsl delete mode 100644 secret-service/params-html.xsl diff --git a/secret-service/Makefile b/secret-service/Makefile index b5c4ab5..27084aa 100644 --- a/secret-service/Makefile +++ b/secret-service/Makefile @@ -3,8 +3,8 @@ SPEC = org.freedesktop.Secrets.xml all: html/index.html -html/index.html: reference.xml params-html.xsl specification.xml - xmlto --skip-validation -o html -p params-html.xsl xhtml specification.xml +html/index.html: reference.xml docbook-params.xsl specification.xml + xmlto --skip-validation -o html/ -x docbook-params.xsl xhtml specification.xml reference.xml: tools/spec-to-docbook.xsl $(SPEC) xsltproc tools/spec-to-docbook.xsl $(SPEC) > $@ diff --git a/secret-service/docbook-params.xsl b/secret-service/docbook-params.xsl new file mode 100644 index 0000000..5d8591a --- /dev/null +++ b/secret-service/docbook-params.xsl @@ -0,0 +1,39 @@ + + + + + + + + 3 + 0 + + book toc + part nop + chapter toc + + style.css + ansi + 1 + 0 + 1 + + diff --git a/secret-service/params-html.xsl b/secret-service/params-html.xsl deleted file mode 100644 index bca2223..0000000 --- a/secret-service/params-html.xsl +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - 3 - 0 - - book toc - part nop - chapter nop - - style.css - ansi - 1 - 0 - 1 - - -- cgit v1.2.3-70-g09d2 From 9b0a610bda7d6b99fa2f61bb77493c671eb1fb41 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Fri, 11 Dec 2009 21:51:30 +0000 Subject: Error code changes. * Remove AlreadyExists. No longer needed. * Remove NotSupported in favor of the one defined in DBus itself: org.freedesktop.DBus.Error.NotSupported * There's no real NoSuchObject error code defined in DBus itself, so defined our own. --- secret-service/org.freedesktop.Secrets.xml | 21 +++++---------------- secret-service/specification.xml | 3 +-- 2 files changed, 6 insertions(+), 18 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index 5757abd..a681d79 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -24,25 +24,14 @@ Errors returned by the Secret Service 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. - + The object must be unlocked before this action can be carried out. - - A session must be established before this action can be carried out. - + The session does not exist. + + + No such item or collection exists. diff --git a/secret-service/specification.xml b/secret-service/specification.xml index e69d116..f305cbe 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -263,8 +263,7 @@ specific. If a service does not support a specific set of algorithms, a - - NotSupported + org.freedesktop.DBus.Error.NotSupported error is returned, and the client is free to try another set of algorithms. The plain algorithm is almost always supported. -- cgit v1.2.3-70-g09d2 From e94829fd5ec3a23ffeda13cd56ec14d5b2eceb3d Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Fri, 11 Dec 2009 21:57:59 +0000 Subject: Support for collection aliases. The collection aliases are present under: /org/freedesktop/secrets/aliases/xxxx So the default and network collections would be usable via the object path, in addition to their normal object paths: /org/freedesktop/secrets/aliases/default /org/freedesktop/secrets/aliases/network To manage the aliases, two new methods are added to the Service interface: ReadAlias() and SetAlias(). BTW, These are not properties on Collection because a collection can be have multiple aliases pointing to it. --- secret-service/org.freedesktop.Secrets.xml | 26 ++++++++++++++++++++------ secret-service/specification.xml | 11 ++++------- 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml index a681d79..73c275b 100644 --- a/secret-service/org.freedesktop.Secrets.xml +++ b/secret-service/org.freedesktop.Secrets.xml @@ -83,12 +83,6 @@ 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. @@ -170,6 +164,26 @@ + + Get the collection with the given alias. + + An alias, such as 'default'. + + + The collection or the the path '/' if no such collection exists. + + + + + Setup a collection alias. + + An alias, such as 'default'. + + + The collection. + + + A collection was created. diff --git a/secret-service/specification.xml b/secret-service/specification.xml index f305cbe..2902232 100644 --- a/secret-service/specification.xml +++ b/secret-service/specification.xml @@ -109,11 +109,7 @@ 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 + collection. The default collection is always accessible through a specific object path. A new item can be created with the @@ -485,9 +481,10 @@ The object path for a session, where ssss is an auto-generated session specific identifier. - /org/freedesktop/secrets/default + /org/freedesktop/secrets/aliases/default The default collection for client applications to store secrets is available under - this object path in addition to its real object path (above). + this object path in addition to its real object path (above). Other aliases may also be + present. -- cgit v1.2.3-70-g09d2 From c450df6716b5a3bb19470cfb41ab3b192251243b Mon Sep 17 00:00:00 2001 From: Michael Leupold Date: Sat, 25 Sep 2010 22:20:16 +0200 Subject: Allow docbook inside tp:docstring. This is useful for examples, eg.: This is the method TestMethod. Example for TestMethod --- secret-service/tools/spec-to-docbook.xsl | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/secret-service/tools/spec-to-docbook.xsl b/secret-service/tools/spec-to-docbook.xsl index d320d61..14d5b24 100644 --- a/secret-service/tools/spec-to-docbook.xsl +++ b/secret-service/tools/spec-to-docbook.xsl @@ -4,6 +4,7 @@ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:docbook="http://docbook.org/ns/docbook" exclude-result-prefixes="tp html">