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.

1 files changed, 397 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>