[Pkg-privacy-commits] [libotr] 112/225: Document the v3 whitespace tag, and better document the extra symmetric key.

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch master
in repository libotr.

commit 7c66924347852fd7a4415022725fb8bcd46f5382
Author: Ian Goldberg <iang at cs.uwaterloo.ca>
Date:   Sun Aug 26 14:16:12 2012 -0400

    Document the v3 whitespace tag, and better document the extra symmetric key.
    
    Thanks to Kjell Braden <kb at pentabarf.de> for noticing the omission.
---
 ChangeLog        |  4 ++++
 Protocol-v3.html | 31 ++++++++++++++++++++++++-------
 src/dh.c         |  1 -
 3 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f0e4107..8bfadb7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -8,6 +8,10 @@
 	functions to start with otrl_.  Thanks to David Goulet
 	<dgoulet at ev0ke.net> for noticing it.
 
+	* Protocol-v3.html: Document the v3 whitespace tag, and better
+	document the extra symmetric key.  Thanks to Kjell Braden
+	<kb at pentabarf.de> for noticing the omission.
+
 2012-08-25
 
 	* src/sm.c:
diff --git a/Protocol-v3.html b/Protocol-v3.html
index 9f29186..75828a5 100644
--- a/Protocol-v3.html
+++ b/Protocol-v3.html
@@ -313,6 +313,8 @@ whitespace version tags, if it is present, for backwards
 compatibility)</li>
 <li>"\x20\x20\x09\x09\x20\x20\x09\x20" to indicate a willingness to use
 OTR version 2 with Bob</li>
+<li>"\x20\x20\x09\x09\x20\x20\x09\x09" to indicate a willingness to use
+OTR version 3 with Bob</li>
 </ul>
 <p>If Bob is willing to use OTR with Alice (with a protocol version that
 Alice has offered), he should start the AKE.  On the other hand, if
@@ -623,11 +625,16 @@ you should change the SMP state to SMP_EXPECT1 (see below).</dd>
 <dd>Like a SMP Message 1, but whose value begins with a NUL-terminated
 user-specified question.</dd>
 <dt>Type 8: Extra symmetric key</dt>
-<dd>The value begins with a 4-byte indication of what this symmetric key
-will be used for (file transfer, voice encryption, etc.). After that, the
-contents are use-specific (which file, etc.). There are no currently
-defined uses. See the "extra symmetric key" section below for details on
-how this key is derived.</dd>
+<dd>If you wish to use the extra symmetric key, compute it yourself as
+outlined in the section "Extra symmetric key", below.  Then send this
+type 8 TLV to your buddy to indicate that you'd like to use the extra
+symmetric key for something.  The value of the TLV begins with a 4-byte
+indication of what this symmetric key will be used for (file transfer,
+voice encryption, etc.). After that, the contents are use-specific
+(which file, etc.). There are no currently defined uses.  Note that the
+value of the key itself is <em>not</em> placed into the TLV; your buddy
+will compute it on his/her own.
+</dd>
 </dl>
 <p>SMP Message TLVs (types 2-5) all carry data sharing the same general
 format:</p> 
@@ -1209,10 +1216,20 @@ sending AES key.</li>
 receiving AES key.</li>
 </ul>
 <h4>Extra symmetric key</h4>
-<p>OTR version 3 defined an additional symmetric key that is derived
-during the AKE. The extra symmetric key is derived by calculating
+<p>OTR version 3 defines an additional symmetric key that can be derived
+by the communicating parties to use for application-specific purposes,
+such as file transfer, voice encryption, etc.  When one party wishes to
+use the extra symmetric key, he or she creates a type 8 TLV attached to
+a Data Message (see above).  The key itself is then derived using the
+same "secbytes" used to compute the encryption and MAC keys used to
+protect the Data Message.
+The extra symmetric key is derived by calculating
 h2(0xFF) and keeping the entire 256 bits, using the same definition
 of h2 as above.</p>
+<p>Upon receipt of the Data Message containing the type 8 TLV, the
+recipient will compute the extra symmetric key in the same way.  Note
+that the value of the extra symmetric key is <em>not</em> contained in
+the TLV itself.</p>
 <h4>Revealing MAC keys</h4>
 <p>Whenever you are about to forget either one of your old D-H key pairs, or
 one of your correspondent's old D-H public keys, take all of the
diff --git a/src/dh.c b/src/dh.c
index 8a22437..c5425a4 100644
--- a/src/dh.c
+++ b/src/dh.c
@@ -205,7 +205,6 @@ gcry_error_t otrl_dh_session(DH_sesskeys *sess, const DH_keypair *kp,
 
     /* Calculate the extra key (used if applications wish to extract a
      * symmetric key for transferring files, or something like that) */
-    /* XXX: Document this in the protocol spec */
     gabdata[0] = 0xff;
     gcry_md_hash_buffer(GCRY_MD_SHA256, sess->extrakey, gabdata, gablen+5);
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/libotr.git