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>Secret Service API Draft</title>
		<releaseinfo>
			Secret Service 0.2 DRAFT
		</releaseinfo>

		<authorgroup>
		<author>
			<firstname>Stef</firstname>
			<surname>Walter</surname>
			<affiliation>
				<jobtitle>GNOME Keyring Developer</jobtitle>
				<address>
					<email>stefw@collabora.co.uk</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-2011</year>
			<holder>The Secret Service API Authors</holder>
		</copyright>

	</bookinfo>

	<part xml:id="description">
		<title>API Documentation</title>
		<chapter>
			<title>Introduction</title>

			<para>The Secret Service API allows client applications to store secrets securely 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 by the user before the secrets become available
			for retrieval by client applications.</para>

			<para>The Secret Service stores a secret along with a set of lookup attributes.
			The attributes can be used to look up and retrieve a secret at a later date. The
			lookup attributes are not treated as secret material, and the service may choose
			not to encrypt attributes when storing them to disk.</para>

			<para>This API was desigened by GNOME and KDE developers with the goal of having
			a common way to store secrets. Its predecessors are the desktop-specific APIs
			used by GNOME Keyring and KWallet.</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, multiple
			values may be combined using the 'desktop' key file format, or XML.</para>

			<para>Secrets may be <link linkend='transfer-secrets'>encrypted when transferred</link>
			 to or from the client application.</para>

			<para>The <link linkend='type-Secret'><classname>Secret</classname> structure</link> encapsulates
			a secret value along with its 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.Secret.Item'>item</link>.</para>

			<para>A group of items together form a
			<link linkend='org.freedesktop.Secret.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 has its own
			object path. Under normal circumstances, the object path of a collection or item
			should not change for its lifetime.</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, must <link linkend='unlocking'>unlock it</link> before use.</para>

			<para>The service must prevent modification of locked collections or items. On
			such an invalid access the
			<link linkend='org.freedesktop.Secret.Error.IsLocked'><errorname>IsLocked</errorname></link>
			 error should be raised.</para>

			<para>Client applications without special requirements should store in the default
			collection. The default collection is always accessible through a
			<link linkend='object-paths'>specific object path</link>.</para>

			<para>A new item can be created with the
			<link linkend='org.freedesktop.Secret.Collection.CreateItem'>
			<function>CreateItem()</function></link>
			method on the Collection interface. When creating an item, the properties of the new
			item are specified. The service may ignore or change these properties when creating
			the item.</para>

			<para>When creating an item, the service may need to prompt the user for additional
			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 created. In this case, the
			<link linkend='org.freedesktop.Secret.Prompt.Completed'>result of the prompt</link>
			will contain the object path of the new item.</para>

			<para>An item can be deleted by calling the
			<link linkend='org.freedesktop.Secret.Item.Delete'><function>Delete()</function></link>
			method on the Item interface.</para>

			<para>When deleting an item, the service may need to prompt the user for additional
			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 item to be deleted.</para>

			<para>Client applications with special needs can create a new collection by calling the
			<link linkend='org.freedesktop.Secret.Service.CreateCollection'>
			<function>CreateCollection()</function></link>
			method on the Service interface. When creating a collection, the properties of the new
			collection are specified. The service may ignore or change these properties when creating
			the collection.</para>

			<para>When creating a collection, the service may need to prompt the user for additional
			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 created. In this case, the
			<link linkend='org.freedesktop.Secret.Prompt.Completed'>result of the prompt</link>
			will contain the object path of the new collection.</para>

			<para>A collection can be deleted by calling the
			<link linkend='org.freedesktop.Secret.Collection.Delete'><function>Delete()</function></link>
			method on the Collection interface.</para>

			<para>When deleting a collection, the service may need to prompt the user for additional
			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">
			<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>

			<para>In order to search for items, use the
			<link linkend='org.freedesktop.Secret.Service.SearchItems'><function>SearchItems()</function></link>
			method of the Service interface. The matched items will be returned in two sets. The
			<parameter class='function'>unlocked</parameter> return value will contain the object paths
			of all the items that are not locked. The <parameter class='function'>locked</parameter> return
			value will contain object paths of items that are locked, which can be
			<link linkend='unlocking'>unlocked if desired</link>.</para>

			<para>The
			<link linkend='org.freedesktop.Secret.Collection.SearchItems'><function>SearchItems()</function></link>
			method of the Collection interface is similar, except for it only searches a single collection.</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.Secret.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.Secret.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.Secret.Item.GetSecret'><function>GetSecret()</function></link>,
			<link linkend='org.freedesktop.Secret.Item.SetSecret'><function>SetSecret()</function></link>
			methods on the item interface, or the
			<link linkend='org.freedesktop.Secret.Service.GetSecrets'><function>GetSecrets()</function></link>,
			method on the service interface.</para>

			<para>You must specify a session when retrieving or storing a secret. The session
			controls how the secret is encoded during transfer. 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 arbitrarilyby the OS or elsewhere.</para>

			<para>The Secrets API has provision to encrypt secrets while in transit between
			the service and the client application. 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>

			<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>When the client application opens a <link linkend='sessions'>session</link>
				with the service, it calls the
				<link linkend='org.freedesktop.Secret.Service.OpenSession'><function>
				OpenSession()</function></link> method on the service. The algorithms argument to the
				<function>OpenSession()</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
				<errorname>org.freedesktop.DBus.Error.NotSupported</errorname>
				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>OpenSession()</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. The object path
				'/' is returned from <function>OpenSession()</function> when session negotiation is
				incomplete.</para>

				<para>None of the algorithms documented in this initial version of the specification
				require multiple calls to <function>OpenSession()</function>.</para>

				<para>When <function>OpenSession()</function> completes, it returns the session object
				path along with a valid session object path.</para>

				<para>Once an session algorithm has been negotiated, it is used for all transfer a
				secrets whenever that session is specified along with the
				<link linkend='type-Secret'><classname>secret</classname></link>.</para>
			</section>

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

				<segmentedlist>
					<?dbhtml list-presentation="list"?>
					<segtitle>Session algorithm</segtitle>
					<segtitle><link linkend='org.freedesktop.Secret.Service.OpenSession'>
					Session input</link></segtitle>
					<segtitle><link linkend='org.freedesktop.Secret.Service.OpenSession'>
					Session 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-sha256-aes128-cbc-pkcs7</title>

				<segmentedlist>
					<?dbhtml list-presentation="list"?>
					<segtitle>Session algorithm</segtitle>
					<segtitle><link linkend='org.freedesktop.Secret.Service.OpenSession'>
					Session input</link></segtitle>
					<segtitle><link linkend='org.freedesktop.Secret.Service.OpenSession'>
					Session output</link></segtitle>
					<segtitle><link linkend='type-Secret'>
					<classname>Secret</classname> parameter</link></segtitle>
					<seglistitem>
						<!-- TODO: literal? -->
						<seg><emphasis>dh-ietf1024-sha256-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>DH key agreement <citation>rfc2631</citation> is used to create a secret key
				using 1024 bit parameters of the standard IETF 'Second Oakley Group'
				<citation>rfc2409</citation>. The secret key is then digested into a 128-bit key
				appropriate for AES. This is done using HKDF <citation>rfc5869</citation> with NULL
				salt and empty info, using the SHA-2 256 hash algorithm
				<citation>fips-180-3.2008</citation>. The secrets are encrypted using AES
				<citation>fips-197.2001</citation> in cipher block chaining mode with pkcs7 style
				padding <citation>rfc2315</citation>.</para>

				<para>The public keys are transferred as an array of bytes representing an
				unsigned integer of arbitrary size, most-significant byte first (e.g., the
				integer 32768 is represented as the 2-byte string 0x80 0x00)</para>
			</section>

		</chapter>

		<chapter xml:id='unlocking'>
			<title>Locking and Unlocking</title>

			<para>Some items and/or collections may be marked as locked by the service.
			The secrets of locked items cannot be accessed. Additionally, locked items or collections
			cannot be modified by the client application.</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.</para>

			<para>A service may choose to unlock items or collections just for a single client
			application. Alternatively the service may choose to allow any client application to access
			items or collections unlocked by a another client application.</para>

			<para>A client application should always be ready to unlock the items for 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). The inherent race conditions present due to this are unavoidable, and must be
			handled gracefully.</para>

			<para>In order to unlock an item or collection the service's
			<link linkend='org.freedesktop.Secret.Service.Unlock'>
			<function>Unlock()</function></link>
			method is called with one or more DBus object paths of items or collections. The
			<function>Unlock()</function> will return the DBus object paths of objects it could
			immediately unlock without prompting.</para>

			<para>The <function>Unlock()</function> method may also return a
			<link linkend='org.freedesktop.Secret.Prompt.Prompt'>prompt object</link>. If a prompt
			object is returned, it must be <link linkend='prompts'>acted upon</link> in order to complete
			the unlocking of the remaining objects. The
			<link linkend='org.freedesktop.Secret.Prompt.Completed'>result of the prompt</link>
			will contain the object paths that were successfully unlocked by the prompt.</para>

			<para>In order to lock an item or collection the service's
			<link linkend='org.freedesktop.Secret.Service.Unlock'>
			<function>Lock()</function></link>
			method is called with one or more DBus object paths of items or collections. The
			<function>Lock()</function> will return the DBus object paths of objects it could
			immediately lock without prompting.</para>

			<para>The <function>Lock()</function> method may also return a
			<link linkend='org.freedesktop.Secret.Prompt.Prompt'>prompt object</link>. If a prompt
			object is returned, it must be <link linkend='prompts'>acted upon</link> in order to complete
			the locking of the remaining objects. The
			<link linkend='org.freedesktop.Secret.Prompt.Completed'>result of the prompt</link>
			will contain the object paths that were successfully locked by the prompt.</para>
		</chapter>

		<chapter xml:id='prompts'>
			<title>Prompts and Prompting</title>

			<para>In order to complete various operations, such as unlocking a collection, the
			service may need to prompt the user for additional information, such as a master password.</para>

			<para>The prompts are displayed by the service on behalf of the client application.</para>

			<para>Operations that require a prompt to complete will return a prompt object. The client
			application must then call the
			<link linkend='org.freedesktop.Secret.Prompt.Prompt'><function>Prompt()</function></link>
			method of the prompt object to display the prompt. Client applications can use the
			<parameter class='function'>window-id</parameter>
			argument to display the prompt attached to their application window.</para>

			<para>Once the user provides the additional required information to the prompt, the service
			completes the operation that required the prompt. Then it emits the the
			<link linkend='org.freedesktop.Secret.Prompt.Completed'><function>Completed</function></link>
			signal of the prompt object. The <parameter class='function'>result</parameter> argument of
			the signal contains operation an operation specific result.</para>

			<para>Either the user or the client application can dismiss a prompt. In this case the
			operation that required the additional information is cancelled. The client application
			can dismiss a prompt by calling the
			<link linkend='org.freedesktop.Secret.Prompt.Dismiss'><function>Dismiss()</function></link>
			method of the prompt object. The <function>Completed</function> signal will be emitted
			with its <parameter class='function'>dismissed</parameter> argument set to
			<constant>TRUE</constant>.</para>

			<para>Once the <function>Completed</function> signal is emitted on a prompt object, it
			is no longer valid. Prompt objects are specific to the client application's connection
			to the DBus bus. Once an application disconnects, all its prompts are no longer valid.</para>

			<para>There is an inherent race between the <function>Dismiss()</function> method and the
			<function>Completed</function> signal. An application calling <function>Dismiss()</function>
			must be prepared to handle the fact that the <function>Completed</function> has already been
			emitted (although perhaps not received by the client). In addition the client must be prepared
			to handle the fact that the prompt object is no longer valid.</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 locking
			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 Secret Service 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/aliases/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). Other aliases may also be
			present.</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>

	<xi:include href="xml/annotation-glossary.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
		<xi:fallback/>
	</xi:include>

	<bibliography>
		<title>References</title>

		<bibliomixed>
			<abbrev>rfc2315</abbrev>
			IETF <ulink url="http://www.ietf.org/rfc/rfc2315.txt">RFC 2315</ulink>:
			PKCS #7: Cryptographic Message Syntax Version 1.5
		</bibliomixed>

		<bibliomixed>
			<abbrev>rfc2409</abbrev>
			IETF <ulink url="http://www.ietf.org/rfc/rfc2409.txt">RFC 2409</ulink>:
			The Internet Key Exchange (IKE)
		</bibliomixed>

		<bibliomixed>
			<abbrev>rfc2631</abbrev>
			IETF <ulink url="http://www.ietf.org/rfc/rfc2631.txt">RFC 2631</ulink>:
			Diffie-Hellman Key Agreement Method
		</bibliomixed>

		<bibliomixed>
			<abbrev>rfc5869</abbrev>
			IETF <ulink url="http://www.ietf.org/rfc/rfc5869.txt">RFC 5869</ulink>:
			HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
		</bibliomixed>

		<bibliomixed>
			<abbrev>fips-180-3.2008</abbrev>
			NIST <ulink url="http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf">FIPS PUB 180-3</ulink>:
			Secure Hash Standard (SHS), October 2008
		</bibliomixed>

		<bibliomixed>
			<abbrev>fips-197.2001</abbrev>
			NIST <ulink url="http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf">FIPS PUB 197</ulink>:
			Advanced Encryption Standard (AES), November 2001
		</bibliomixed>

	</bibliography>

</book>