path: root/secret-service/specification.xml

<?xml version="1.0"?>
<book xml:id="index" xmlns="http://docbook.org/ns/docbook" version="5.0">
	<bookinfo>
		<title>Secrets API Draft</title>
		<releaseinfo>
			Secrets 0.1 DRAFT
<!--			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 xml: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-secrets'>encrypted when transferred</link>
			 to the client application and vice versa.</para>

			<para>The <link linkend='type-Secret'><classname>Secret</classname> 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='org.freedesktop.Secrets.Item'>item</link>.</para>

			<para>A group of items together form a
			<link linkend='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='org.freedesktop.Secrets.Error.IsLocked'><errorname>IsLocked</errorname></link>
			 error should be raised.</para>

			<para>Client applications without special requirements should store in the default
			collection. Use the
			<link linkend='org.freedesktop.Secrets.Service.DefaultCollection'>
			<property>DefaultCollection</property></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='org.freedesktop.Secrets.Service.CreateCollection'>
			<function>CreateCollection()</function></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='org.freedesktop.Secrets.Service.CreateCollection'>creating a collection</link>.
			Client applications that demand this feature, should check the the
			<link linkend='org.freedesktop.Secrets.Collection.Private'><property>Private</property>
			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='org.freedesktop.Secrets.Collection.Delete'><function>Delete()</function></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 xml:id="lookup-attributes">
			<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 xml:id="sessions">
			<title>Sessions</title>

			<para>A session is established between a client application and a service. A session
			is used to <link linkend='transfer-secrets'>transfer secrets</link> between the client
			application and the service.</para>

			<para>A session is established by calling the service's
			<link linkend='org.freedesktop.Secrets.Service.OpenSession'>
			<function>OpenSession()</function></link>
			method. Once established, a session is bound to calling application's connection to
			the DBus session bus.</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='org.freedesktop.Secrets.Session.Close'><function>Close()</function></link>
			method on the session interface. Once a session is closed all session specific
			negotiations will be dropped by the service.</para>

			<para>More than one session may opened by a client application, although this is
			not normally necessary.</para>
		</chapter>

		<chapter xml:id='transfer-secrets'>
			<title>Transfer of Secrets</title>

			<para>To access or store secrets, use the
			<link linkend='org.freedesktop.Secrets.Session.GetSecret'><function>GetSecret()</function></link>,
			<link linkend='org.freedesktop.Secrets.Session.GetSecrets'><function>GetSecrets()</function></link>,
			<link linkend='org.freedesktop.Secrets.Session.SetSecret'><function>SetSecret()</function></link>
			methods on the session interface.</para>

			<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>

			<section>
				<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='org.freedesktop.Secrets.Session.Negotiate'><function>
				Negotiate()</function></link> method on that session. The algorithms argument to the
				<function>Negotiate()</function> 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='org.freedesktop.Secrets.Error.NotSupported'>
				<errorname>NotSupported</errorname></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 <function>Negotiate()</function> 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='type-Secret'><classname>secret</classname></link>.</para>
			</section>

			<section>
				<title>Algorithm: plain</title>

				<segmentedlist>
					<?dbhtml list-presentation="list"?>
					<segtitle>Algorithm string</segtitle>
					<segtitle><link linkend='org.freedesktop.Secrets.Session.Negotiate'>
					<function>Negotiate</function> input</link></segtitle>
					<segtitle><link linkend='org.freedesktop.Secrets.Session.Negotiate'>
					<function>Negotiate</function> output</link></segtitle>
					<segtitle><link linkend='type-Secret'>
					<classname>Secret</classname> parameter</link></segtitle>
					<seglistitem>
						<!-- TODO: literal? -->
						<seg><emphasis>plain</emphasis></seg>
						<seg>empty string</seg>
						<seg>empty string</seg>
						<seg>empty string</seg>
					</seglistitem>
				</segmentedlist>

				<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>
			</section>

			<section>
				<title>Algorithm: dh-ietf1024-aes128-cbc-pkcs7</title>

				<segmentedlist>
					<?dbhtml list-presentation="list"?>
					<segtitle>Algorithm string</segtitle>
					<segtitle><link linkend='org.freedesktop.Secrets.Session.Negotiate'>
					<function>Negotiate</function> input</link></segtitle>
					<segtitle><link linkend='org.freedesktop.Secrets.Session.Negotiate'>
					<function>Negotiate</function> output</link></segtitle>
					<segtitle><link linkend='type-Secret'>
					<classname>Secret</classname> parameter</link></segtitle>
					<seglistitem>
						<!-- TODO: literal? -->
						<seg><emphasis>dh-ietf1024-aes128-cbc-pkcs7</emphasis></seg>
						<seg>client dh pub key as an array of bytes</seg>
						<seg>service dh pub key as an array of bytes</seg>
						<seg>16 byte AES initialization vector</seg>
					</seglistitem>
				</segmentedlist>

				<para>TODO: Document</para>
			</section>

		</chapter>

		<chapter xml: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 the service's
			<link linkend='org.freedesktop.Secrets.Service.BeginAuthenticate'>
			<function>BeginAuthenticate()</function></link>
			method is called with one or more DBus object paths of items or collections. The
			<function>BeginAuthenticate()</function> 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='org.freedesktop.Secrets.Service.Authenticated'>
			<function>Authenticated()</function></link>
			signal on the service interface is emitted.</para>

			<para>The client application may, but is not required to, call the
			<link linkend='org.freedesktop.Secrets.Service.CompleteAuthenticate'>
			<function>CompleteAuthenticate()</function></link>
			method. One or more DBus object paths of items or collections that <function>BeginAuthenticate()</function>
			was previously called with, can be passed in. The <function>CompleteAuthenticate()</function> 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.</para>

			<para>A client application should always be ready to call <function>BeginAuthenticate()</function> the secrets
			it needs, or objects it must modify. It must not assume that an item is already unlocked
			for whatever reason.</para>

			<para>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).</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 xml:id="ref-dbus-api">
		<title>D-Bus API Reference</title>

    <chapter xml:id='object-paths'>
			<title>Object Paths</title>

			<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>

			<programlisting>/org/freedesktop/secrets</programlisting>
			<para>The object path for the service.</para>

			<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>

			<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>

			<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>

			<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>
		</chapter>

		<xi:include href="reference.xml" xpointer="interfaces" xmlns:xi="http://www.w3.org/2001/XInclude">
			<xi:fallback/>
		</xi:include>
		<xi:include href="reference.xml" xpointer="types" xmlns:xi="http://www.w3.org/2001/XInclude">
			<xi:fallback/>
		</xi:include>
		<xi:include href="reference.xml" xpointer="errors" xmlns:xi="http://www.w3.org/2001/XInclude">
			<xi:fallback/>
		</xi:include>

	</part>

<!--
  <chapter xml:id="object-tree">
    <title>Object Hierarchy</title>
     <xi:include href="xml/tree_index.sgml"/>
  </chapter>
  <index xml: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" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback /></xi:include>
</book>