summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--secret-service/org.freedesktop.Secrets.xml397
-rw-r--r--secret-service/specification.xml418
-rw-r--r--secret-service/tools/spec-to-introspect.xsl225
3 files changed, 1040 insertions, 0 deletions
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 @@
+<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+ "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+
+<!--
+ * This is the well known dbus service name for controlling the
+ * entire daemon. The services manages collections of secrets. These
+ * are analogous to the gnome-keyring 'keyrings'.
+-->
+<tp:spec xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+ <tp:title>Secret Storage specification</tp:title>
+ <tp:version>0.1</tp:version>
+
+ <!--
+ * ======================================================================================
+ * ERROR CODES
+ *
+ -->
+
+ <tp:errors namespace="org.freedesktop.Secrets.Error">
+ <tp:docstring>Errors returned by the Secrets API.</tp:docstring>
+ <tp:error name="AlreadyExists">
+ <tp:docstring>
+ An object (session, collection) already exists with the same name.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="IsLocked">
+ <tp:docstring>
+ The object must be unlocked before this action can be carried out.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="NotSupported">
+ <tp:docstring>
+ The algorithm is not supported.
+ </tp:docstring>
+ </tp:error>
+ <tp:error name="NoSession">
+ <tp:docstring>
+ A session must be established before this action can be carried out.
+ </tp:docstring>
+ </tp:error>
+ </tp:errors>
+
+ <!--
+ * ======================================================================================
+ * SECRET STRUCT
+ * Signature: (sayay)
+ *
+ -->
+
+ <tp:struct name="Secret">
+ <tp:docstring>The #Secret type holds a (possibly encoded) secret.</tp:docstring>
+ <tp:member type="s" name="algorithm">
+ <tp:docstring>Algorithm used to encode the secrets value.</tp:docstring>
+ </tp:member>
+ <tp:member type="ay" name="parameters">
+ <tp:docstring>Algorithm dependent parameters for secret value encoding.</tp:docstring>
+ </tp:member>
+ <tp:member type="ay" name="value">
+ <tp:docstring>Possibly encoded secret value</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
+ <tp:mapping name="ObjectPath_Secret_Map">
+ <tp:docstring>A mapping from object-paths to Secret structs</tp:docstring>
+ <tp:member type="o" name="Key">
+ <tp:docstring>D-Bus object-path</tp:docstring>
+ </tp:member>
+ <tp:member type="sayay" name="Value" tp:type="Secret">
+ <tp:docstring>A secret</tp:docstring>
+ </tp:member>
+ </tp:mapping>
+
+ <!--
+ * ======================================================================================
+ * SERVICE INTERFACE
+ *
+ -->
+
+ <node name="/org/freedesktop/Secrets">
+
+ <interface name="org.freedesktop.Secrets.Service">
+
+ <tp:docstring>
+ The Secrets service manages all the sessions and collections.
+ </tp:docstring>
+
+ <property name="Collections" type="ao" access="read">
+ <tp:docstring>The object paths of all collections (ie: keyrings)</tp:docstring>
+ </property>
+
+ <property name="DefaultCollection" type="o" access="readwrite">
+ <tp:docstring>
+ The object path of the default collection, or an empty string if no collections exist.
+ </tp:docstring>
+ </property>
+
+ <method name="OpenSession">
+ <tp:docstring>Open a unique session for the caller application.</tp:docstring>
+ <arg name="result" type="o" direction="out">
+ <tp:docstring>The object path of the session.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="CreateCollection">
+ <tp:docstring>Create a new collection with the specified access attributes.</tp:docstring>
+
+ <arg name="label" type="s" direction="in">
+ <tp:docstring>The display name of the new collection</tp:docstring>
+ </arg>
+
+ <arg name="private" type="b" direction="in">
+ <tp:docstring>Whether this is a private collection or not.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="LockService">
+ <tp:docstring>
+ Lock down the entire service. Remove secrets from memory, lock all collections etc...
+ </tp:docstring>
+ </method>
+
+ <method name="SearchItems">
+ <tp:docstring>Find items in any collection.</tp:docstring>
+
+ <arg name="attributes" type="a{ss}" direction="in">
+ <tp:docstring>Find secrets in any collection.</tp:docstring>
+ </arg>
+
+ <arg name="unlocked" type="ao" direction="out">
+ <tp:docstring>Items found.</tp:docstring>
+ </arg>
+
+ <arg name="locked" type="ao" direction="out">
+ <tp:docstring>Items found that require authentication.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="RetrieveSecrets">
+ <tp:docstring>Retrieve multiple secrets from different items.</tp:docstring>
+ <arg name="items" type="ao" direction="in">
+ <tp:docstring>Items to get secrets for.</tp:docstring>
+ </arg>
+
+ <arg name="secrets" type="a{o(sayay)}" direction="out" tp:type="ObjectPath_Secret_Map">
+ <tp:docstring>Secrets for the items.</tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="CollectionCreated">
+ <tp:docstring>A collection was created.</tp:docstring>
+
+ <arg name="collection" type="o">
+ <tp:docstring>Collection that was created</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="CollectionDeleted">
+ <tp:docstring>A collection was deleted.</tp:docstring>
+
+ <arg name="collection" type="o">
+ <tp:docstring>Collection that was created</tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+ </node>
+
+ <!--
+ * ======================================================================================
+ * COLLECTION INTERFACE
+ *
+ -->
+
+ <node name="/org/freedesktop/Secrets/collection/xxxx">
+
+ <interface name="org.freedesktop.Secrets.Collection">
+
+ <tp:docstring>A collection of items containing secrets.</tp:docstring>
+
+ <property name="Items" type="ao" access="read">
+ <tp:docstring>Items in this collection.</tp:docstring>
+ </property>
+
+ <property name="Private" type="s" access="read">
+ <tp:docstring>Whether this is a private collection or not.</tp:docstring>
+ </property>
+
+ <property name="Label" type="s" access="readwrite">
+ <tp:docstring>The displayable label of this collection.</tp:docstring>
+ </property>
+
+ <property name="Locked" type="s" access="read">
+ <tp:docstring>
+ Whether the collection is locked and must be authenticated by the client application.
+ </tp:docstring>
+ </property>
+
+ <property name="Created" type="t" access="read">
+ <tp:docstring>The unix time when the collection was created.</tp:docstring>
+ </property>
+
+ <property name="Modified" type="t" access="read">
+ <tp:docstring>The unix time when the collection was last modified.</tp:docstring>
+ </property>
+
+ <method name="Delete">
+ <tp:docstring>Delete this collection.</tp:docstring>
+ </method>
+
+ <method name="SearchItems">
+ <tp:docstring>Search for items in this collection matching the lookup attributes.</tp:docstring>
+ <arg name="attributes" type="a{ss}" direction="in">
+ <tp:docstring>Attributes to match.</tp:docstring>
+ </arg>
+ <arg name="results" type="ao" direction="out">
+ <tp:docstring>Items that matched the attributes.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="CreateItem">
+
+ <tp:docstring>
+ 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.
+ </tp:docstring>
+
+ <arg name="attributes" type="a{ss}" direction="in">
+ <tp:docstring>The lookup attributes for the new item.</tp:docstring>
+ </arg>
+
+ <arg name="secret" type="(sayay)" direction="in" tp:type="Secret">
+ <tp:docstring>The secret to store in the new item.</tp:docstring>
+ </arg>
+
+ <arg name="label" type="s" direction="in">
+ <tp:docstring>The label for the new item.</tp:docstring>
+ </arg>
+
+ <arg name="replace" type="b" direction="in">
+ <tp:docstring>Whether to replace an item with the same attributes or not.</tp:docstring>
+ </arg>
+
+ <arg name="item" type="o" direction="out">
+ <tp:docstring>The new item, or previous item if replaced.</tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="ItemCreated">
+ <tp:docstring>A new item in this collection was created.</tp:docstring>
+
+ <arg name="item" type="o">
+ <tp:docstring>The item that was created.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ItemDeleted">
+ <tp:docstring>An item in this collection was deleted.</tp:docstring>
+
+ <arg name="item" type="o">
+ <tp:docstring>The item that was deleted.</tp:docstring>
+ </arg>
+ </signal>
+
+ <signal name="ItemChanged">
+ <tp:docstring>An item in this collection changed.</tp:docstring>
+
+ <arg name="item" type="o">
+ <tp:docstring>The item that was changed.</tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+ </node>
+
+ <!--
+ * ======================================================================================
+ * ITEM INTERFACE
+ *
+ -->
+
+ <node name="/org/freedesktop/Secrets/collection/xxxx/iiii">
+
+ <interface name="org.freedesktop.Secrets.Item">
+
+ <tp:docstring>An item contains a secret, lookup attributes and has a label.</tp:docstring>
+
+ <property name="Locked" type="b" access="read">
+ <tp:docstring>Whether the item is locked and requires authentication, or not.</tp:docstring>
+ </property>
+
+ <property name="Attributes" type="a{ss}" access="readwrite">
+ <tp:docstring>The lookup attributes for this item.</tp:docstring>
+ </property>
+
+ <property name="Label" type="s" access="readwrite">
+ <tp:docstring>The displayable label for this item.</tp:docstring>
+ </property>
+
+ <property name="Secret" type="(sayay)" access="readwrite" tp:type="Secret">
+ <tp:docstring>The secret, usually transferred encrypted.</tp:docstring>
+ </property>
+
+ <property name="Created" type="t" access="read">
+ <tp:docstring>The unix time when the item was created.</tp:docstring>
+ </property>
+
+ <property name="Modified" type="t" access="read">
+ <tp:docstring>The unix time when the item was last modified.</tp:docstring>
+ </property>
+
+ <method name="Delete">
+ <tp:docstring>Delete this item.</tp:docstring>
+ </method>
+
+ </interface>
+
+ </node>
+
+ <!--
+ * ======================================================================================
+ * SESSION INTERFACE
+ *
+ -->
+
+ <node name="/org/freedesktop/Secrets/session/ssss">
+
+ <interface name="org.freedesktop.Secrets.Session">
+
+ <tp:docstring>A session tracks state between the service and a client application.</tp:docstring>
+
+ <method name="Close">
+ <tp:docstring>Close this session.</tp:docstring>
+ </method>
+
+ <method name="Negotiate">
+ <tp:docstring>Negotiate key agreement and encryption.</tp:docstring>
+
+ <arg name="algorithm" type="s" direction="in">
+ <tp:docstring>The algorithm the caller wishes to use.</tp:docstring>
+ </arg>
+
+ <arg name="input" type="v" direction="in">
+ <tp:docstring>Input arguments for the algorithm.</tp:docstring>
+ </arg>
+
+ <arg name="output" type="v" direction="out">
+ <tp:docstring>Output of the negotiation.</tp:docstring>
+ </arg>
+
+ <arg name="complete" type="b" direction="out">
+ <tp:docstring>Whether the negotiation is complete or requires further calls.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="BeginAuthenticate">
+ <tp:docstring>Start asynchronous authentication of objects for the caller.</tp:docstring>
+
+ <arg name="objects" type="ao" direction="in">
+ <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
+ </arg>
+
+ <arg name="window-id" type="s" direction="in">
+ <tp:docstring>Platform specific window handle to use for showing any prompts.</tp:docstring>
+ </arg>
+ </method>
+
+ <method name="CompleteAuthenticate">
+ <tp:docstring>Complete asynchronous authentication of objects for the caller.</tp:docstring>
+
+ <arg name="objects" type="ao" direction="in">
+ <tp:docstring>Objects to authenticate or unlock.</tp:docstring>
+ </arg>
+
+ <arg name="authenticated" type="ao" direction="in">
+ <tp:docstring>Objects that were successfully authenticated.</tp:docstring>
+ </arg>
+ </method>
+
+ <signal name="Authenticated">
+ <tp:docstring>An object (collection or item) was authenticated.</tp:docstring>
+
+ <arg name="object" type="o">
+ <tp:docstring>The object that was authenticated.</tp:docstring>
+ </arg>
+
+ <arg name="success" type="b">
+ <tp:docstring>Whether the object was successfully unlocked.</tp:docstring>
+ </arg>
+ </signal>
+
+ </interface>
+
+ </node>
+
+</tp:spec>
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 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book id="index">
+ <bookinfo>
+ <title>Secrets API Specification</title>
+ <releaseinfo>
+ Secrets 0.1
+<!-- The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://[SERVER]/secrets/index.html">http://[SERVER]/secrets/</ulink>.-->
+ </releaseinfo>
+
+ <authorgroup>
+ <author>
+ <firstname>Stef</firstname>
+ <surname>Walter</surname>
+ <affiliation>
+ <jobtitle>GNOME Keyring Developer</jobtitle>
+ <address>
+ <email>stef@memberwebs.com</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Michael</firstname>
+ <surname>Leupold</surname>
+ <affiliation>
+ <jobtitle>KWallet Developer</jobtitle>
+ <address>
+ <email>lemma@confuego.org</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2008-2009</year>
+ <holder>The Secrets API Authors</holder>
+ </copyright>
+
+ </bookinfo>
+
+ <part id="description">
+ <title>API Documentation</title>
+ <chapter>
+ <title>Introduction</title>
+
+ <para>The Secrets API allows client applications to store secrets securily in a
+ service running in the user's login session. </para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+ </chapter>
+
+ <chapter>
+ <title>Secrets</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>Secrets may be <link linkend='transfer-of-secrets'>encrypted when transferred</link>
+ to the client application and vice versa.</para>
+
+ <para>The <link linkend='eggdbus-structmain-Secret'>Secret structure</link> encapsulates
+ a secret value along with it's transfer encryption parameters.</para>
+ </chapter>
+
+ <chapter>
+ <title>Collection and Items</title>
+
+ <para>Each secret is stored together with
+ <link linkend='lookup-attributes'>lookup attributes</link> and a label. These together
+ form an <link linkend='eggdbus-interface-org.freedesktop.Secrets.Item'>item</link>.</para>
+
+ <para>A group of items together form a
+ <link linkend='eggdbus-interface-org.freedesktop.Secrets.Collection'>collection</link>.
+ A collection is similar in concept to the terms 'keyring' or 'wallet'.</para>
+
+ <para>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.</para>
+
+ <para>It is strongly recommended that client applications use
+ <link linkend='lookup-attributes'>lookup attributes</link> to find items rather than
+ recording the object path of a stored item. This allows maximum interoperability.</para>
+
+ <para>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 <link linkend='authentication-unlocking'>unlock it before use</link>.</para>
+
+ <para>The service must prevent locked collections or items from modification. On
+ such an invalid access the
+ <link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.IsLocked'>IsLocked</link>
+ error should be raised.</para>
+
+ <para>Client applications without special requirements should store in the default
+ collection. Use the
+ <link linkend='eggdbus-property-org.freedesktop.Secrets.Service:DefaultCollection'>DefaultCollection</link>
+ property on the Service interface to determine the default collection. In addition
+ the default collection is always accessible through a
+ <link linkend='object-paths'>specific object path</link>.</para>
+
+ <para>Client applications with special needs can create a new collection by calling the
+ <link linkend='eggdbus-property-org.freedesktop.Secrets.Service.CreateCollection'>CreateCollection()</link>
+ method on the Service interface. A client application must have
+ <link linkend='sessions'>opened a session</link> before a collection can be created. The </para>
+
+ <para>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
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Service.CreateCollection'>creating a collection</link>.
+ Client applications that demand this feature, should check the the
+ <link linkend='eggdbus-property-org.freedesktop.Secrets.Collection:Private'>Private property</link>
+ after creating a collection to see if the request for a private collection was ignored.</para>
+
+ <para>A collection can be deleted by calling the
+ <link linkend='eggdbus-property-org.freedesktop.Secrets.Collection.Delete'>Delete()</link>
+ method on the Service interface. A client application must have
+ <link linkend='sessions'>opened a session</link> 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.</para>
+ </chapter>
+
+ <chapter>
+ <title>Lookup Attributes</title>
+
+ <para>Attributes can and should be stored with a secret to facilitate lookup
+ of the secret at a later date.</para>
+
+ <para>An attribute constists of a name, and a value. Both parts are simple
+ strings.</para>
+
+ <para>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.</para>
+
+ <para>During a lookup, attribute names and values are matched via case-sensitive
+ string equality.</para>
+
+ <para>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.</para>
+ </chapter>
+
+ <chapter id="sessions">
+ <title>Sessions</title>
+
+ <para>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
+ <link linkend='transfer-secrets'>negotiate encryption of transferred secrets</link>
+ between the client application and the service.</para>
+
+ <para>A session is established by calling the service's
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Service.OpenSession'>OpenSession()</link>
+ 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
+ <link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.AlreadyExists'>AlreadyExists</link>
+ error.</para>
+
+ <para>A session is closed when the client application disconnects from the DBus
+ session bus. Alternatively the client application can call the
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Close'>Close()</link>
+ method on the session interface. Once a session is closed all session specific
+ negotiations and authentication should be dropped by the service.</para>
+ </chapter>
+
+ <chapter id='transfer-secrets'>
+ <title>Transfer of Secrets</title>
+
+ <para>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.</para>
+
+ <para>The Secrets API has provision to encrypt secrets while in transit between
+ the service and the client application.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <sect1>
+ <title>Negotiation of Algorithms</title>
+
+ <para>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).</para>
+
+ <para>The client application opens a <link linkend='sessions'>session</link>
+ with the service, and then calls the
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+ Negotiate() method</link> 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.</para>
+
+ <para>If a service does not support a specific set of algorithms, a
+ <link linkend='eggdbus-constant-Error.org.freedesktop.Secrets.Error.NotSupported'>NotSupported</link>
+ error is returned, and the client is free to try another set of algorithms.
+ The <emphasis>plain</emphasis> algorithm is almost always supported.</para>
+
+ <para>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.</para>
+
+ <para>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
+ <link linkend='eggdbus-structmain-Secret'>secret</link>.</para>
+ </sect1>
+
+ <sect1>
+ <title>Algorithm: plain</title>
+
+ <simplelist type='vert'>
+ <member>Algorithm string: <emphasis>plain</emphasis></member>
+ <member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+ Negotiate input</link>: empty string</member>
+ <member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+ Negotiate output</link>: empty string</member>
+ <member><link linkend='eggdbus-struct-Secret'>
+ Secret parameter</link>: empty string</member>
+ </simplelist>
+
+ <para>The plain algorithm does no encryption whatsoever.</para>
+
+ <para>It is strongly recommended that a service implementing this API support
+ the <emphasis>plain</emphasis> algorithm.</para>
+ </sect1>
+
+ <sect1>
+ <title>Algorithm: dh-ietf1024-aes128-cbc-pkcs7</title>
+
+ <simplelist type='vert'>
+ <member>Algorithm string: <emphasis>dh-ietf1024-aes128-cbc-pkcs7</emphasis></member>
+ <member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+ Negotiate input</link>: client dh pub key as an array of bytes</member>
+ <member><link linkend='eggdbus-method-org.freedesktop.Secrets.Session.Negotiate'>
+ Negotiate output</link>: service dh pub key as an array of bytes</member>
+ <member><link linkend='eggdbus-struct-Secret'>
+ Secret parameter</link>: 16 byte AES initialization vector.</member>
+ </simplelist>
+
+ <para>TODO: Document</para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id='authentication-unlocking'>
+ <title>Authentication or Unlocking</title>
+
+ <para>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.</para>
+
+ <para>In order to unlock an item or collection a
+ <link linkend='sessions'>session</link> is established by the client application,
+ and the
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Session.BeginAuthenticate'>BeginAuthenticate()</link>
+ 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.</para>
+
+ <para>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.</para>
+
+ <para>After the service tries to unlock an item or collection, whether successfully
+ or unsuccessfully, the
+ <link linkend='eggdbus-signal-org.freedesktop.Secrets.Session::Authenticated'>Authenticated</link>
+ signal on the session interface is emitted.</para>
+
+ <para>The client application may, but is not required to, call the
+ <link linkend='eggdbus-method-org.freedesktop.Secrets.Session.CompleteAuthenticate'>CompleteAuthenticate()</link>
+ 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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+ </chapter>
+
+ <chapter>
+ <title>What's not included in the API</title>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>This specification does not mandate any form of access control. The service may
+ choose to allow certain applications to access a keyring, and others.</para>
+
+ <para>[TODO: complete]</para>
+
+ </chapter>
+
+ <chapter>
+ <title>Notes for Service Implementors</title>
+
+ <para>[TODO: complete]</para>
+ </chapter>
+
+ </part>
+
+ <part id="ref-dbus-api">
+ <title>D-Bus API Reference</title>
+
+ <refentry id='object-paths'>
+ <refmeta>
+ <refentrytitle role="top_of_page">Object Paths</refentrytitle>
+ </refmeta>
+
+ <para>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.</para>
+
+ <refsect1>
+ <programlisting>/org/freedesktop/Secrets</programlisting>
+ <para>The object path for the service.</para>
+ </refsect1>
+
+ <refsect1>
+ <programlisting>/org/freedesktop/Secrets/collection/<emphasis>xxxx</emphasis></programlisting>
+ <para>The object path for a collection, where <emphasis>xxxx</emphasis> represents a
+ possibly encoded or truncated version of the initial label of the collection.</para>
+ </refsect1>
+
+ <refsect1>
+ <programlisting>/org/freedesktop/Secrets/collection/<emphasis>xxxx</emphasis>/<emphasis>iiii</emphasis></programlisting>
+ <para>The object path for an item, where <emphasis>xxxx</emphasis> is the collection (above)
+ and <emphasis>iiii</emphasis> is an auto-generated item specific identifier.</para>
+ </refsect1>
+
+ <refsect1>
+ <programlisting>/org/freedesktop/Secrets/session/<emphasis>ssss</emphasis></programlisting>
+ <para>The object path for a session, where <emphasis>ssss</emphasis> is an auto-generated
+ session specific identifier.</para>
+ </refsect1>
+
+ <refsect1>
+ <programlisting>/org/freedesktop/Secrets/default</programlisting>
+ <para>The default collection for client applications to store secrets is available under
+ this object path in addition to its real object path (above).</para>
+ </refsect1>
+ </refentry>
+
+ <refentry id='eggdbus-interface.org.freedesktop.Secrets.Collection'>
+ <refmeta>
+ <refentrytitle role="top_of_page">org.freedesktop.Secrets.Collection Interface</refentrytitle>
+ </refmeta>
+ <refnamediv>
+ <refname>org.freedesktop.Secrets.Collection Interface</refname>
+ <refpurpose>Collection of items</refpurpose>
+ </refnamediv>
+
+ </refentry>
+
+ <xi:include href="../../../secrets/docbook-interface-org.freedesktop.Secrets.Collection.xml"/>
+ <xi:include href="../../../secrets/docbook-interface-org.freedesktop.Secrets.Item.xml"/>
+ <xi:include href="../../../secrets/docbook-interface-org.freedesktop.Secrets.Service.xml"/>
+ <xi:include href="../../../secrets/docbook-interface-org.freedesktop.Secrets.Session.xml"/>
+ <xi:include href="../../../secrets/docbook-struct-Secret.xml"/>
+ <xi:include href="../../../secrets/docbook-enum-Error.xml"/>
+ </part>
+
+<!--
+ <chapter id="object-tree">
+ <title>Object Hierarchy</title>
+ <xi:include href="xml/tree_index.sgml"/>
+ </chapter>
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+-->
+ <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
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 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"
+ exclude-result-prefixes="tp">
+
+<!--
+ Telepathy D-Bus Introspection to EggDBus Introspection format translator.
+
+ Copyright 2009 Michael Leupold <lemma@confuego.org>
+
+ 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 program 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.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<!--
+ TODO:
+ - Enable conversion of dictionary element types (eg. "{ss}") and
+ struct types (eg. "(sayay)")
+ - unhandled: tp:simple-type, tp:enum, tp:flags, tp:external-type
+ - tp:docstring may contain XHTML which this template doesn't handle
+-->
+
+ <!-- main template -->
+ <xsl:template match="tp:spec">
+ <node>
+ <xsl:apply-templates select="tp:errors"/>
+ <xsl:apply-templates select="tp:struct"/>
+ <!-- TODO: <xsl:apply-templates select="tp:mapping"/> -->
+ <xsl:apply-templates select="node/interface"/>
+ </node>
+ </xsl:template>
+
+ <!-- Resolve the type a node has. This will first look at tp:type and
+ - if not found - use the type attribute -->
+ <xsl:template name="ResolveType">
+ <xsl:param name="node"/>
+ <xsl:choose>
+ <xsl:when test="$node//@tp:type">
+ <xsl:call-template name="TpType">
+ <xsl:with-param name="type" select="$node//@tp:type"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="$node//@type">
+ <xsl:call-template name="DBusType">
+ <xsl:with-param name="type" select="$node//@type"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:message terminate="yes">
+ Node doesn't contain a type.
+ </xsl:message>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Map a D-Bus type to its EggDBus counterpart -->
+ <xsl:template name="DBusType">
+ <xsl:param name="type"/>
+ <xsl:choose>
+ <xsl:when test="$type='o'">ObjectPath</xsl:when>
+ <xsl:when test="$type='s'">String</xsl:when>
+ <xsl:when test="$type='y'">Byte</xsl:when>
+ <xsl:when test="$type='b'">Boolean</xsl:when>
+ <xsl:when test="$type='n'">Int16</xsl:when>
+ <xsl:when test="$type='q'">UInt16</xsl:when>
+ <xsl:when test="$type='i'">Int32</xsl:when>
+ <xsl:when test="$type='u'">UInt32</xsl:when>
+ <xsl:when test="$type='x'">Int64</xsl:when>
+ <xsl:when test="$type='t'">UInt64</xsl:when>
+ <xsl:when test="$type='d'">Double</xsl:when>
+ <xsl:when test="$type='g'">Signature</xsl:when>
+ <xsl:when test="starts-with($type, 'a')">
+ Array&lt;
+ <xsl:call-template name="DBusType">
+ <xsl:with-param name="type" select="substring($type, 2)"/>
+ </xsl:call-template>
+ &gt;
+ </xsl:when>
+ <!-- TODO: doesn't implement dict-entries and structs -->
+ <xsl:otherwise>
+ <xsl:message terminate="yes">
+ Unknown DBus Type <xsl:value-of select="$type"/>
+ </xsl:message>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Resolve tp:type attributes by searching for matching tp:struct
+ and tp:mapping elements -->
+ <xsl:template name="TpType">
+ <xsl:param name="type"/>
+ <xsl:choose>
+ <xsl:when test="/tp:spec/tp:struct[@name=$type]">
+ <xsl:value-of select="$type"/>
+ </xsl:when>
+ <xsl:when test="/tp:spec/tp:mapping[@name=$type]">
+ Dict&lt;
+ <xsl:call-template name="ResolveType">
+ <xsl:with-param name="node" select="/tp:spec/tp:mapping[@name=$type]/tp:member[@name='Key']"/>
+ </xsl:call-template>,
+ <xsl:call-template name="ResolveType">
+ <xsl:with-param name="node" select="/tp:spec/tp:mapping[@name=$type]/tp:member[@name='Value']"/>
+ </xsl:call-template>
+ &gt;
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:message terminate="yes">
+ Unspecified type <xsl:value-of select="$type"/>.
+ </xsl:message>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- handle most of the D-Bus introspection elements -->
+ <xsl:template match="interface|annotation|method|signal">
+ <xsl:copy>
+ <xsl:for-each select="@*">
+ <xsl:if test="not(starts-with(name(), 'tp:'))">
+ <xsl:copy/>
+ </xsl:if>
+ </xsl:for-each>
+ <xsl:apply-templates/>
+ </xsl:copy>
+ </xsl:template>
+
+ <!-- handle the arg and property D-Bus introspection elements.
+ They get special handling because they may contain a tp:type
+ attribute -->
+ <xsl:template match="arg|property">
+ <xsl:copy>
+ <xsl:for-each select="@*">
+ <xsl:choose>
+ <xsl:when test="not(starts-with(name(), 'tp:'))">
+ <xsl:copy/>
+ </xsl:when>
+ <xsl:when test="name() = 'tp:type'">
+ <xsl:variable name="type">
+ <xsl:call-template name="TpType">
+ <xsl:with-param name="type" select="."/>
+ </xsl:call-template>
+ </xsl:variable>
+ <annotation name="org.gtk.EggDBus.Type">
+ <xsl:attribute name="value">
+ <xsl:value-of select="normalize-space($type)"/>
+ </xsl:attribute>
+ </annotation>
+ </xsl:when>
+ <xsl:otherwise/>
+ </xsl:choose>
+ </xsl:for-each>
+ <xsl:apply-templates/>
+ </xsl:copy>
+ </xsl:template>
+
+ <!-- tp:docstring to org.gtk.EggDBus.DocString -->
+ <xsl:template match="tp:docstring">
+ <annotation name="org.gtk.EggDBus.DocString">
+ <xsl:attribute name="value">
+ <xsl:value-of select="normalize-space(text())"/>
+ </xsl:attribute>
+ </annotation>
+ </xsl:template>
+
+ <!-- tp:errors to org.gtk.EggDBus.DeclareErrorDomain -->
+ <xsl:template match="tp:errors">
+ <annotation value="Error" name="org.gtk.EggDBus.DeclareErrorDomain">
+ <xsl:apply-templates select="tp:docstring"/>
+ <xsl:apply-templates select="tp:error"/>
+ </annotation>
+ </xsl:template>
+
+ <!-- tp:error to org.gtk.EggDBus.ErrorDomain.Member -->
+ <xsl:template match="tp:error">
+ <annotation name="org.gtk.EggDBus.ErrorDomain.Member">
+ <xsl:attribute name="value">
+ <xsl:value-of select="concat(../@namespace, '.', @name)"/>
+ </xsl:attribute>
+ <xsl:apply-templates select="tp:docstring"/>
+ </annotation>
+ </xsl:template>
+
+ <!-- tp:struct to org.gtk.EggDBus.DeclareStruct -->
+ <xsl:template match="tp:struct">
+ <annotation name="org.gtk.EggDBus.DeclareStruct">
+ <xsl:attribute name="value">
+ <xsl:value-of select="@name"/>
+ </xsl:attribute>
+ <xsl:apply-templates select="tp:docstring"/>
+ <xsl:apply-templates select="tp:member"/>
+ </annotation>
+ </xsl:template>
+
+ <!-- tp:member to org.gtk.EggDBus.Struct.Member -->
+ <xsl:template match="tp:member">
+ <xsl:variable name="type">
+ <xsl:call-template name="ResolveType">
+ <xsl:with-param name="node" select="."/>
+ </xsl:call-template>
+ </xsl:variable>
+ <annotation name="org.gtk.EggDBus.Struct.Member">
+ <xsl:attribute name="value">
+ <xsl:value-of select="concat(normalize-space($type), ':', @name)"/>
+ </xsl:attribute>
+ <xsl:apply-templates select="tp:docstring"/>
+ </annotation>
+ </xsl:template>
+
+ <xsl:template match="text()"/>
+
+ <xsl:output method="xml" indent="yes" encoding="UTF-8"
+ omit-xml-declaration="no"
+ doctype-system="http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"
+ doctype-public="-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"/>
+
+</xsl:stylesheet>