Use the OpenSession function for algorithm Negotiation.

This has several benefits:

 * Removes gray area of whether a single session could renegotiate
   a different key exchange.
 * Removes strange state that a session is in before negotiation of
   an algorithm.
 * Less API.
 * OpenSession() could be called multiple times for algorithms that
   require more than one back and forth negotiation. We have none of
   these presently.

2 files changed, 45 insertions, 46 deletions

diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml
index c514438..430a81e 100644
--- a/secret-service/org.freedesktop.Secrets.xml
+++ b/secret-service/org.freedesktop.Secrets.xml
@@ -102,8 +102,17 @@
 
             <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.</tp:docstring>
+                    <tp:docstring>The object path of the session, if session was created.</tp:docstring>
                 </arg>
             </method>
 
@@ -370,26 +379,6 @@
                 <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>
-
         </interface>
 
     </node>
diff --git a/secret-service/specification.xml b/secret-service/specification.xml
index 92f5f68..e69d116 100644
--- a/secret-service/specification.xml
+++ b/secret-service/specification.xml
@@ -254,12 +254,13 @@
 				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.Secret.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>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
 				<link linkend='org.freedesktop.Secret.Error.NotSupported'>
@@ -267,13 +268,20 @@
 				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>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>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
+				<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>
 
@@ -282,11 +290,11 @@
 
 				<segmentedlist>
 					<?dbhtml list-presentation="list"?>
-					<segtitle>Algorithm string</segtitle>
-					<segtitle><link linkend='org.freedesktop.Secret.Session.Negotiate'>
-					<function>Negotiate</function> input</link></segtitle>
-					<segtitle><link linkend='org.freedesktop.Secret.Session.Negotiate'>
-					<function>Negotiate</function> output</link></segtitle>
+					<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>
@@ -309,23 +317,25 @@
 
 				<segmentedlist>
 					<?dbhtml list-presentation="list"?>
-					<segtitle>Algorithm string</segtitle>
-					<segtitle><link linkend='org.freedesktop.Secret.Session.Negotiate'>
-					<function>Negotiate</function> input</link></segtitle>
-					<segtitle><link linkend='org.freedesktop.Secret.Session.Negotiate'>
-					<function>Negotiate</function> output</link></segtitle>
+					<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-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>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>
+				<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>