[PATCH] Use the OpenSession function for algorithm Negotiation.
Stef Walter
stef at memberwebs.com
Sat Nov 28 10:06:47 PST 2009
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.
---
specifications/Secrets/org.freedesktop.Secrets.xml | 31 +++-------
specifications/Secrets/specification.xml | 64 +++++++++++--------
2 files changed, 47 insertions(+), 48 deletions(-)
diff --git a/specifications/Secrets/org.freedesktop.Secrets.xml b/specifications/Secrets/org.freedesktop.Secrets.xml
index d3571e5..f2cf663 100644
--- a/specifications/Secrets/org.freedesktop.Secrets.xml
+++ b/specifications/Secrets/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/specifications/Secrets/specification.xml b/specifications/Secrets/specification.xml
index 07d2293..2caf5c7 100644
--- a/specifications/Secrets/specification.xml
+++ b/specifications/Secrets/specification.xml
@@ -254,26 +254,34 @@
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'>
<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
+
+ <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>
@@ -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>
--
1.6.3.3
--------------010301020301000800080405--
More information about the Authentication
mailing list