summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--secret-service/org.freedesktop.Secrets.xml15
-rw-r--r--secret-service/specification.xml24
2 files changed, 39 insertions, 0 deletions
diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml
index 6a9e495..7d23c78 100644
--- a/secret-service/org.freedesktop.Secrets.xml
+++ b/secret-service/org.freedesktop.Secrets.xml
@@ -121,6 +121,21 @@ properties = { "Label": "MyCollection" }
</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>
diff --git a/secret-service/specification.xml b/secret-service/specification.xml
index 65045d6..a0a293b 100644
--- a/secret-service/specification.xml
+++ b/secret-service/specification.xml
@@ -157,7 +157,31 @@
information. In this case, a <link linkend='prompts'>prompt object</link> is returned. It
must be <link linkend='org.freedesktop.Secret.Prompt.Prompt'>acted upon</link> in order for
the collection to be deleted.</para>
+ </chapter>
+ <chapter xml:id="aliases">
+ <title>Aliases</title>
+
+ <para>Collections may be accessed via well known aliases. For example an alias
+ called <literal>default</literal> tells applications which is the default
+ collection to store secrets.</para>
+
+ <para>The aliased collections will be available at a
+ <link linkend='object-paths'>well-known DBus object path</link>.</para>
+
+ <para>If an application needs to create a collection with a given alias, this can
+ be done in a race free fashion by specifying the alias parameter of the
+ <link linkend='org.freedesktop.Secret.Service.CreateCollection'>CreateCollection()</link>
+ method on the service interface. If a collection with that alias already exists,
+ then it will be returned instead of creating a new one.</para>
+
+ <para>For applications like password managers it can be useful to allow the user to
+ configure which collection is associated with which well known alias. To alias or
+ unalias a collection use the
+ <link linkend='org.freedesktop.Secret.Service.SetAlias'>SetAlias()</link> method on the
+ service interface. Use the
+ <link linkend='org.freedesktop.Secret.Service.ReadAlias'>ReadAlias()</link> method on the
+ service interface to discover which collection is associated with a given alias.</para>
</chapter>
<chapter xml:id="lookup-attributes">