path: root/secret-service/org.freedesktop.Secrets.xml

<!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 service 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 Service API Specification</tp:title>
    <tp:version>0.1</tp:version>
    <tp:copyright>
      Copyright (C) 2009 Stef Walter &lt;stef@memberwebs.com&gt;
    </tp:copyright>
    <tp:copyright>
      Copyright (C) 2009 Michael Leupold &lt;lemma@confuego.org&gt;
    </tp:copyright>

    <!--
     * ======================================================================================
     * ERROR CODES
     *
    -->

    <tp:errors namespace="org.freedesktop.Secret.Error">
        <tp:docstring>Errors returned by the Secret Service API.</tp:docstring>
        <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="NoSession">
            <tp:docstring>The session does not exist.</tp:docstring>
         </tp:error>
        <tp:error name="NoSuchObject">
            <tp:docstring>No such item or collection exists.</tp:docstring>
        </tp:error>
    </tp:errors>

    <!--
     * ======================================================================================
     * SECRET STRUCT
     * Signature: (oayays)
     *
    -->

    <tp:struct name="Secret">
        <tp:docstring>The Secret type holds a (possibly encoded) secret.</tp:docstring>
        <tp:member type="o" name="session">
            <tp:docstring>The session that was used to encode the secret.</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:member type="s" name="content_type">
            <tp:docstring>The content type of the secret. For example: 'text/plain; charset=utf8'</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="(oayays)" 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.Secret.Service">

            <tp:docstring>
                The Secret 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>

            <method name="OpenSession">
                <tp:docstring>Open a unique session for the caller application.</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 session algorithm negotiation.</tp:docstring>
                </arg>
                <arg name="result" type="o" direction="out">
                    <tp:docstring>The object path of the session, if session was created.</tp:docstring>
                </arg>
            </method>

            <method name="CreateCollection">
                <tp:docstring>Create a new collection with the specified properties.</tp:docstring>
                <arg name="properties" type="a{sv}" direction="in">
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            Properties for the new collection. This allows setting the new collection's
                            properties upon its creation. All READWRITE properties are useable. Specify
                            the property names in full interface.Property form.
                            <example>
                                <title>Example for properties</title>
                                <programlisting>
<![CDATA[
properties = { "org.freedesktop.Secret.Collection.Label": "MyCollection" }
]]>
                                </programlisting>
                            </example>
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="alias" type="s" direction="in">
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            If creating this connection for a well known alias then a string like
                            <literal>default</literal>. If an collection with this well-known alias already
                            exists, then that collection will be returned instead of creating a new
                            collection. Any readwrite properties provided to this function will be set on
                            the collection.
                        </para>
                        <para>
                            Set this to an empty string if the new collection should not be associated with a
                            well known alias.
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="collection" type="o" direction="out">
                    <tp:docstring>The new collection object, or '/' if prompting is necessary.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object if prompting is necessary, or '/' if no prompt was needed.</tp:docstring>
                </arg>
            </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="Unlock">
                <tp:docstring>Unlock the specified objects.</tp:docstring>
                <arg name="objects" type="ao" direction="in">
                    <tp:docstring>Objects to unlock.</tp:docstring>
                </arg>
                <arg name="unlocked" type="ao" direction="out">
                    <tp:docstring>Objects that were unlocked without a prompt.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object which can be used to unlock the remaining objects, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="Lock">
                <tp:docstring>Lock the items.</tp:docstring>
                <arg name="objects" type="ao" direction="in">
                    <tp:docstring>Objects to lock.</tp:docstring>
                </arg>
                <arg name="locked" type="ao" direction="out">
                    <tp:docstring>Objects that were locked without a prompt.</tp:docstring>
                </arg>
                <arg name="Prompt" type="o" direction="out">
                    <tp:docstring>A prompt to lock the objects, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="GetSecrets">
                <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="session" type="o" direction="in">
                    <tp:docstring>The session to use to encode the secrets.</tp:docstring>
                </arg>
                <arg name="secrets" type="a{o(oayays)}" direction="out" tp:type="ObjectPath_Secret_Map">
                    <tp:docstring>Secrets for the items.</tp:docstring>
                </arg>
            </method>

            <method name="ReadAlias">
                <tp:docstring>Get the collection with the given alias.</tp:docstring>
                <arg name="name" type='s' direction='in'>
                    <tp:docstring>An alias, such as 'default'.</tp:docstring>
                </arg>
                <arg name="collection" type='o' direction='out'>
                    <tp:docstring>The collection or the the path '/' if no such collection exists.</tp:docstring>
                </arg>
            </method>

            <method name="SetAlias">
                <tp:docstring>Setup a collection alias.</tp:docstring>
                <arg name="name" type='s' direction='in'>
                    <tp:docstring>An alias, such as 'default'.</tp:docstring>
                </arg>
                <arg name="collection" type='o' direction='in'>
                    <tp:docstring>
                        The collection to make the alias point to. To remove an alias use the special value '/'.
                    </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 deleted.</tp:docstring>
                </arg>
            </signal>

            <signal name="CollectionChanged">
                <tp:docstring>A collection was changed.</tp:docstring>
                <arg name="collection" type="o">
                    <tp:docstring>Collection that was changed.</tp:docstring>
                </arg>
            </signal>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * COLLECTION INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secrets/collection/xxxx">

        <interface name="org.freedesktop.Secret.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="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>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt to delete the collection, or the special value '/' when no prompt is necessary.</tp:docstring>
                </arg>
            </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="properties" type="a{sv}" direction="in">
                    <tp:docstring>The properties for the new item.</tp:docstring>
                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
                        <para>
                            Properties for the new item. This allows setting the new item's
                            properties upon its creation. All READWRITE properties are useable.
                            Specify the property names in full interface.Property form.
                            <example>
                                <title>Example for properties</title>
                                <programlisting>
<![CDATA[
properties = {
               "org.freedesktop.Secret.Item.Label": "MyItem",
               "org.freedesktop.Secret.Item.Attributes": {
                          "Attribute1": "Value1",
                          "Attribute2": "Value2"
                    }
             }
]]>
                                </programlisting>
                            </example>
                            <note>
                                <para>
                                    Please note that there is a distinction between the terms
                                    <emphasis>Property</emphasis>, which refers to a D-Bus properties
                                    of an object, and <emphasis>Attribute</emphasis>, which refers to one
                                    of a secret item's string-valued attributes.
                                </para>
                            </note>
                        </para>
                    </tp:docstring>
                </arg>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="in">
                    <tp:docstring>The secret to store in the item, encoded with the included session.</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 item created, or the special value '/' if a prompt is necessary.</tp:docstring>
                </arg>
                <arg name="prompt" type="o" direction="out">
                    <tp:docstring>A prompt object, or the special value '/' if no prompt is necessary.</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/Secret/collection/xxxx/iiii">

        <interface name="org.freedesktop.Secret.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="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>
                <arg name="Prompt" type="o" direction="out">
                     <tp:docstring>A prompt object, or the special value '/' if no prompt is necessary.</tp:docstring>
                </arg>
            </method>

            <method name="GetSecret">
                <tp:docstring>Retrieve the secret for this item.</tp:docstring>
                <arg name="session" type="o" direction="in">
                    <tp:docstring>The session to use to encode the secret.</tp:docstring>
                </arg>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="out">
                    <tp:docstring>The secret retrieved.</tp:docstring>
                </arg>
            </method>

            <method name="SetSecret">
                <tp:docstring>Set the secret for this item.</tp:docstring>
                <arg name="secret" type="(oayays)" tp:type="Secret" direction="in">
                    <tp:docstring>The secret to set, encoded for the included session.</tp:docstring>
                </arg>
            </method>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * SESSION INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secret/session/ssss">

        <interface name="org.freedesktop.Secret.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>

        </interface>

    </node>

    <!--
     * ======================================================================================
     * PROMPT INTERFACE
     *
    -->

    <node name="/org/freedesktop/Secret/prompts/pppp">

        <interface name="org.freedesktop.Secret.Prompt">
            <tp:docstring>A prompt necessary to complete an operation.</tp:docstring>

            <method name="Prompt">
                <tp:docstring>Perform the prompt.</tp:docstring>
                        <arg name="window-id" type="s" direction="in">
                            <tp:docstring>Platform specific window handle to use for
                    showing the prompt.</tp:docstring>
                        </arg>
            </method>

            <method name="Dismiss">
                <tp:docstring>Dismiss the prompt.</tp:docstring>
            </method>

            <signal name="Completed">
                <tp:docstring>The prompt and operation completed.</tp:docstring>
                <arg name="dismissed" type="b">
                    <tp:docstring>Whether the prompt and operation were dismissed or not.</tp:docstring>
                </arg>
                <arg name="result" type="v">
                    <tp:docstring>The possibly empty, operation specific,
                        result.</tp:docstring>
                </arg>
            </signal>

        </interface>

    </node>

</tp:spec>