Commit 4bfbb829 authored by David Goulet's avatar David Goulet

Add OTR protocol v3 spec. web page

Signed-off-by: default avatarDavid Goulet <dgoulet@ev0ke.net>
parent 22d2b554
<!DOCTYPE html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8 ie-7"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9 ie-8"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="OTR developers">
<title>OTR.im - Whispering Off The Record</title>
<link href="./assets/css/style.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="./assets/js/html5shiv.js"></script>
<script src="./assets/js/respond.min.js"></script>
<![endif]-->
</head>
<!-- NAVBAR
================================================== -->
<body>
<div class="navbar-wrapper">
<div class="container">
<div class="navbar navbar-inverse navbar-static-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="#">OTR.im</a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li><a href="index.html">Home</a></li>
<li><a href="clients.html">Clients</a></li>
<li><a href="chat.html">Chat</a></li>
<li><a href="about.html">About</a></li>
<li><a href="blog/">Blog</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="container" id="container3">
<div class="container-inner">
<div class="row featurette">
<h1 class=featurette-heading>Off-the-Record Messaging Protocol version 3</h1>
<p>This document describes version 3 of the Off-the-Record Messaging
protocol. The main changes over version 2 include:</p>
<ul>
<li>Both fragmented and unfragmented messages contain sender and
recipient instance tags. This avoids an issue on IM networks that
always relay all messages to all sessions of a client who is logged
in multiple times. In this situation, OTR clients can attempt to
establish an OTR session indefinitely if there are interleaving
messages from each of the sessions.</li>
<li>An extra symmetric key is derived during AKE. This may be used for
secure communication over a different channel (e.g., file transfer,
voice chat).</li>
</ul>
<h2>Very high level overview</h2>
<p>OTR assumes a network model which provides in-order delivery of
messages, but that some messages may not get delivered at all
(for example, if the user disconnects). There may be
an active attacker, who is allowed to perform a Denial of
Service attack, but not to learn the contents of messages.</p>
<ol>
<li>Alice signals to Bob that she would like (using an OTR Query Message)
or is willing (using a whitespace-tagged plaintext message) to use OTR
to communicate. Either mechanism should convey the version(s) of OTR
that Alice is willing to use.</li>
<li>Bob initiates the authenticated key exchange (AKE) with Alice.
Versions 2 and 3 of OTR use a variant of the SIGMA protocol as its AKE.</li>
<li>Alice and Bob exchange Data Messages to send information to each
other.</li>
</ol>
<h2>High level overview</h2>
<h3>Requesting an OTR conversation</h3>
<p>There are two ways Alice can inform Bob that she is willing to use
the OTR protocol to speak with him: by sending him the OTR Query Message,
or by including a special "tag" consisting of whitespace characters in
one of her messages to him. Each method also includes a way for Alice
to communicate to Bob which versions of the OTR protocol she is willing
to speak with him.</p>
<p>The semantics of the OTR Query Message are that Alice is
<em>requesting</em> that Bob start an OTR conversation with her (if, of
course, he is willing and able to do so). On the other hand, the
semantics of the whitespace tag are that Alice is merely
<em>indicating</em> to Bob that she is willing and able to have an OTR
conversation with him. If Bob has a policy of "only use OTR when it's
explicitly requested", for example, then he <em>would</em> start an OTR
conversation upon receiving an OTR Query Message, but <em>would not</em>
upon receiving the whitespace tag.</p>
<h3>Authenticated Key Exchange (AKE)</h3>
<p>This section outlines the version of the SIGMA protocol used as the
AKE. All exponentiations are done modulo a particular 1536-bit prime,
and g is a generator of that group, as indicated in the detailed
description below. Alice and Bob's long-term authentication public keys
are pub<sub>A</sub> and pub<sub>B</sub>, respectively.</p>
<p>The general idea is that Alice and Bob do an <em>unauthenticated</em>
Diffie-Hellman (D-H) key exchange to set up an encrypted channel, and
then do mutual authentication <em>inside</em> that channel.</p>
<p>Bob will be initiating the AKE with Alice.</p>
<ul>
<li>Bob:
<ol>
<li>Picks a random value <code>r</code> (128 bits)</li>
<li>Picks a random value x (at least 320 bits)</li>
<li>Sends Alice <code>AES<sub>r</sub>(g<sup>x</sup>), HASH(g<sup>x</sup>)</code></li>
</ol></li>
<li>Alice:
<ol>
<li>Picks a random value y (at least 320 bits)</li>
<li>Sends Bob g<sup>y</sup></li>
</ol></li>
<li>Bob:
<ol>
<li>Verifies that Alice's g<sup>y</sup> is a legal value (2 &lt;=
g<sup>y</sup> &lt;= modulus-2)</li>
<li>Computes s = (g<sup>y</sup>)<sup>x</sup></li>
<li>Computes two AES keys c, c' and four MAC keys m1, m1', m2, m2' by
hashing s in various ways</li>
<li>Picks keyid<sub>B</sub>, a serial number for his D-H key
g<sup>x</sup></li>
<li>Computes M<sub>B</sub> = MAC<sub>m1</sub>(g<sup>x</sup>, g<sup>y</sup>,
pub<sub>B</sub>, keyid<sub>B</sub>)</li>
<li>Computes X<sub>B</sub> = pub<sub>B</sub>, keyid<sub>B</sub>,
sig<sub>B</sub>(M<sub>B</sub>)</li>
<li>Sends Alice r, AES<sub>c</sub>(X<sub>B</sub>),
MAC<sub>m2</sub>(AES<sub>c</sub>(X<sub>B</sub>))</li>
</ol></li>
<li>Alice:
<ol>
<li>Uses r to decrypt the value of g<sup>x</sup> sent earlier</li>
<li>Verifies that HASH(g<sup>x</sup>) matches the value sent earlier</li>
<li>Verifies that Bob's g<sup>x</sup> is a legal value (2 &lt;=
g<sup>x</sup> &lt;= modulus-2)</li>
<li>Computes s = (g<sup>x</sup>)<sup>y</sup> (note that this will be the
same as the value of s Bob calculated)</li>
<li>Computes two AES keys c, c' and four MAC keys m1, m1', m2, m2' by
hashing s in various ways (the same as Bob)</li>
<li>Uses m2 to verify MAC<sub>m2</sub>(AES<sub>c</sub>(X<sub>B</sub>))</li>
<li>Uses c to decrypt AES<sub>c</sub>(X<sub>B</sub>) to obtain
X<sub>B</sub> = pub<sub>B</sub>, keyid<sub>B</sub>,
sig<sub>B</sub>(M<sub>B</sub>)</li>
<li>Computes M<sub>B</sub> = MAC<sub>m1</sub>(g<sup>x</sup>,
g<sup>y</sup>, pub<sub>B</sub>, keyid<sub>B</sub>)</li>
<li>Uses pub<sub>B</sub> to verify sig<sub>B</sub>(M<sub>B</sub>)</li>
<li>Picks keyid<sub>A</sub>, a serial number for her D-H key
g<sup>y</sup></li>
<li>Computes M<sub>A</sub> = MAC<sub>m1'</sub>(g<sup>y</sup>, g<sup>x</sup>,
pub<sub>A</sub>, keyid<sub>A</sub>)</li>
<li>Computes X<sub>A</sub> = pub<sub>A</sub>, keyid<sub>A</sub>,
sig<sub>A</sub>(M<sub>A</sub>)</li>
<li>Sends Bob AES<sub>c'</sub>(X<sub>A</sub>),
MAC<sub>m2'</sub>(AES<sub>c'</sub>(X<sub>A</sub>))</li>
</ol></li>
<li>Bob:
<ol>
<li>Uses m2' to verify MAC<sub>m2'</sub>(AES<sub>c'</sub>(X<sub>A</sub>))</li>
<li>Uses c' to decrypt AES<sub>c'</sub>(X<sub>A</sub>) to obtain
X<sub>A</sub> = pub<sub>A</sub>, keyid<sub>A</sub>,
sig<sub>A</sub>(M<sub>A</sub>)</li>
<li>Computes M<sub>A</sub> = MAC<sub>m1'</sub>(g<sup>y</sup>,
g<sup>x</sup>, pub<sub>A</sub>, keyid<sub>A</sub>)</li>
<li>Uses pub<sub>A</sub> to verify sig<sub>A</sub>(M<sub>A</sub>)</li>
</ol></li>
<li>If all of the verifications succeeded, Alice and Bob now know each
other's Diffie-Hellman public keys, and share the value s. Alice is
assured that s is known by someone with access to the private key
corresponding to pub<sub>B</sub>, and similarly for Bob.</li>
</ul>
<h3>Exchanging data</h3>
<p>This section outlines the method used to protect data being exchanged
between Alice and Bob. As above, all exponentiations are done modulo
a particular 1536-bit prime, and g is a generator of
that group, as indicated in the detailed description below.</p>
<p>Suppose Alice has a message (msg) to send to Bob.</p>
<ul>
<li>Alice:
<ol>
<li>Picks the most recent of her own D-H encryption keys that Bob has
acknowledged receiving (by using it in a Data Message, or failing that,
in the AKE). Let key<sub>A</sub> by that key, and let keyid<sub>A</sub>
be its serial number.</li>
<li>If the above key is Alice's most recent key, she generates a new D-H key
(next_dh), to get the serial number keyid<sub>A</sub>+1.</li>
<li>Picks the most recent of Bob's D-H encryption keys that she has
received from him (either in a Data Message or in the AKE). Let
key<sub>B</sub> by that key, and let keyid<sub>B</sub> be its serial
number.</li>
<li>Uses Diffie-Hellman to compute a shared secret from the two keys
key<sub>A</sub> and key<sub>B</sub>, and generates the
sending AES key, ek, and the sending MAC key, mk, as detailed
below.</li>
<li>Collects any old MAC keys that were used in previous messages, but
will never again be used (because their associated D-H keys are no
longer the most recent ones) into a list, oldmackeys.</li>
<li>Picks a value of the counter, ctr, so that the triple
(key<sub>A</sub>, key<sub>B</sub>, ctr) is never the same for more
than one Data Message Alice sends to Bob.</li>
<li>Computes T<sub>A</sub> = (keyid<sub>A</sub>, keyid<sub>B</sub>, next_dh,
ctr, AES-CTR<sub>ek,ctr</sub>(msg))</li>
<li>Sends Bob T<sub>A</sub>, MAC<sub>mk</sub>(T<sub>A</sub>),
oldmackeys</li>
</ol></li>
<li>Bob:
<ol>
<li>Uses Diffie-Hellman to compute a shared secret from the two keys
labelled by keyid<sub>A</sub> and keyid<sub>B</sub>, and generates the
receiving AES key, ek, and the receiving MAC key, mk, as detailed
below. (These will be the same as the keys Alice generated, above.)</li>
<li>Uses mk to verify MAC<sub>mk</sub>(T<sub>A</sub>).</li>
<li>Uses ek and ctr to decrypt
AES-CTR<sub>ek,ctr</sub>(msg).</li>
</ol>
</li>
</ul>
<h3>Socialist Millionaires' Protocol (SMP)</h3>
<p>While data messages are being exchanged, either Alice or Bob may
run SMP to detect impersonation or man-in-the-middle attacks.
As above, all exponentiations are done modulo a particular 1536-bit
prime, and g<sub>1</sub> is a generator of that group. All sent values
include zero-knowledge proofs that they were generated according to
this protocol, as indicated in the detailed description below.</p>
<p>Suppose Alice and Bob have secret information x and y respectively,
and they wish to know whether x = y. The Socialist Millionaires' Protocol
allows them to compare x and y without revealing any other information
than the value of (x == y). For OTR, the secrets contain
information about both parties' long-term authentication public keys,
as well as information entered by the users themselves. If x = y,
this means that Alice and Bob entered the same secret information, and
so must be the same entities who established that secret to begin with.</p>
<p>Assuming that Alice begins the exchange:</p>
<ul>
<li>Alice:
<ol>
<li>Picks random exponents a<sub>2</sub> and a<sub>3</sub></li>
<li>Sends Bob g<sub>2a</sub> = g<sub>1</sub><sup>a<sub>2</sub></sup> and
g<sub>3a</sub> = g<sub>1</sub><sup>a<sub>3</sub></sup></li>
</ol></li>
<li>Bob:
<ol>
<li>Picks random exponents b<sub>2</sub> and b<sub>3</sub></li>
<li>Computes g<sub>2b</sub> = g<sub>1</sub><sup>b<sub>2</sub></sup> and
g<sub>3b</sub> = g<sub>1</sub><sup>b<sub>3</sub></sup></li>
<li>Computes g<sub>2</sub> = g<sub>2a</sub><sup>b<sub>2</sub></sup> and
g<sub>3</sub> = g<sub>3a</sub><sup>b<sub>3</sub></sup></li>
<li>Picks random exponent r</li>
<li>Computes P<sub>b</sub> = g<sub>3</sub><sup>r</sup> and
Q<sub>b</sub> = g<sub>1</sub><sup>r</sup> g<sub>2</sub><sup>y</sup></li>
<li>Sends Alice g<sub>2b</sub>, g<sub>3b</sub>, P<sub>b</sub> and
Q<sub>b</sub></li>
</ol></li>
<li>Alice:
<ol>
<li>Computes g<sub>2</sub> = g<sub>2b</sub><sup>a<sub>2</sub></sup> and
g<sub>3</sub> = g<sub>3b</sub><sup>a<sub>3</sub></sup></li>
<li>Picks random exponent s</li>
<li>Computes P<sub>a</sub> = g<sub>3</sub><sup>s</sup> and
Q<sub>a</sub> = g<sub>1</sub><sup>s</sup> g<sub>2</sub><sup>x</sup></li>
<li>Computes R<sub>a</sub> = (Q<sub>a</sub> / Q<sub>b</sub>)
<sup>a<sub>3</sub></sup></li>
<li>Sends Bob P<sub>a</sub>, Q<sub>a</sub> and R<sub>a</sub></li>
</ol></li>
<li>Bob:
<ol>
<li>Computes R<sub>b</sub> = (Q<sub>a</sub> / Q<sub>b</sub>)
<sup>b<sub>3</sub></sup></li>
<li>Computes R<sub>ab</sub> = R<sub>a</sub><sup>b<sub>3</sub></sup></li>
<li>Checks whether R<sub>ab</sub> == (P<sub>a</sub> / P<sub>b</sub>)</li>
<li>Sends Alice R<sub>b</sub></li>
</ol></li>
<li>Alice:
<ol>
<li>Computes R<sub>ab</sub> = R<sub>b</sub><sup>a<sub>3</sub></sup></li>
<li>Checks whether R<sub>ab</sub> == (P<sub>a</sub> / P<sub>b</sub>)</li>
</ol></li>
<li>If everything is done correctly, then R<sub>ab</sub> should hold the
value of (P<sub>a</sub> / P<sub>b</sub>) times
(g<sub>2</sub><sup>a<sub>3</sub>b<sub>3</sub></sup>)<sup>(x - y)</sup>, which means that the test at the end of
the protocol will only succeed if x == y. Further, since
g<sub>2</sub><sup>a<sub>3</sub>b<sub>3</sub></sup> is a random number
not known to any party, if x is not equal to y, no other information is
revealed.</li>
</ul>
<h2>Details of the protocol</h2>
<h3>Unencoded messages</h3>
<p>This section describes the messages in the OTR protocol that are not
base-64 encoded binary.</p>
<h4>OTR Query Messages</h4>
<p>If Alice wishes to communicate to Bob that she would like to use OTR,
she sends a message containing the string "?OTR" followed by an
indication of what versions of OTR she is willing to use with Bob. The
version string is constructed as follows:</p>
<ul>
<li>If she is willing to use OTR version 1, the version string must
start with "?".</li>
<li>If she is willing to use OTR versions other than 1, a "v" followed
by the byte identifiers for the versions in question, followed by "?".
The byte identifier for OTR version 2 is "2", and similarly for 3. The
order of the identifiers between the "v" and the "?" does not matter,
but none should be listed more than once.</li>
</ul>
<p>For example:</p>
<dl>
<dt>"?OTR?"</dt>
<dd>Version 1 only</dd>
<dt>"?OTRv2?"</dt>
<dd>Version 2 only</dd>
<dt>"?OTRv23?"</dt>
<dd>Versions 2 and 3</dd>
<dt>"?OTR?v2?"</dt>
<dd>Versions 1 and 2</dd>
<dt>"?OTRv24x?"</dt>
<dd>Version 2, and hypothetical future versions identified by "4" and
"x"</dd>
<dt>"?OTR?v24x?"</dt>
<dd>Versions 1, 2, and hypothetical future versions identified by "4" and
"x"</dd>
<dt>"?OTR?v?"</dt>
<dd>Also version 1 only</dd>
<dt>"?OTRv?"</dt>
<dd>A bizarre claim that Alice would like to start an OTR conversation,
but is unwilling to speak any version of the protocol</dd>
</dl>
<p>These strings may be hidden from the user (for example, in
an attribute of an HTML tag), and/or may be accompanied by an
explanitory message ("Alice has requested an Off-the-Record private
conversation."). If Bob is willing to use OTR with Alice (with a
protocol version that Alice has offered), he should start the AKE.</p>
<h4>Tagged plaintext messages</h4>
<p>If Alice wishes to communicate to Bob that she is willing to use OTR,
she can attach a special whitespace tag to any plaintext message she
sends him. This tag may occur anywhere in the message, and may be
hidden from the user (as in the Query Messages, above).</p>
<p>The tag consists of the following 16 bytes, followed by one or more
sets of 8 bytes indicating the version of OTR Alice is willing to
use:</p>
<ul>
<li>Always send "\x20\x09\x20\x20\x09\x09\x09\x09"
"\x20\x09\x20\x09\x20\x09\x20\x20", followed by one or more of:</li>
<li>"\x20\x09\x20\x09\x20\x20\x09\x20" to indicate a willingness to use
OTR version 1 with Bob (note: this string must come before all other
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
Alice receives a plaintext message from Bob (rather than an initiation
of the AKE), she should stop sending him the whitespace tag.</p>
<h4>OTR Error Messages</h4>
<p>Any message containing the string "?OTR Error:" is an OTR Error
Message. The following part of the message should contain
human-readable details of the error.</p>
<h3>Encoded messages</h3>
<p>This section describes the byte-level format of the base-64 encoded
binary OTR messages. The binary form of each of the messages is
described below. To transmit one of these messages, construct the ASCII
string consisting of the five bytes "?OTR:", followed by the base-64
encoding of the binary form of the message, followed by the byte
".".</p>
<p>For the Diffie-Hellman group computations, the group is the one
defined in RFC 3526 with 1536-bit modulus (hex, big-endian):</p>
<blockquote><pre>
FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1
29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD
EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245
E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED
EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D
C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F
83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D
670C354E 4ABC9804 F1746C08 CA237327 FFFFFFFF FFFFFFFF
</pre></blockquote>
<p>and a generator (g) of 2. Note that this means that whenever you see a
Diffie-Hellman exponentiation in this document, it always means that the
exponentiation is done modulo the above 1536-bit number.</p>
<h4>Data types</h4>
<dl>
<dt>Bytes (BYTE):</dt>
<dd> 1 byte unsigned value</dd>
<dt>Shorts (SHORT):</dt>
<dd> 2 byte unsigned value, big-endian</dd>
<dt>Ints (INT):</dt>
<dd> 4 byte unsigned value, big-endian</dd>
<dt>Multi-precision integers (MPI):</dt>
<dd> 4 byte unsigned len, big-endian
<br /> len byte unsigned value, big-endian
<br /> (MPIs must use the minimum-length encoding; i.e. no leading 0x00
bytes. This is important when calculating public key
fingerprints.)</dd>
<dt>Opaque variable-length data (DATA):</dt>
<dd> 4 byte unsigned len, big-endian
<br /> len byte data</dd>
<dt>Initial CTR-mode counter value (CTR):</dt>
<dd> 8 bytes data</dd>
<dt>Message Authentication Code (MAC):</dt>
<dd> 20 bytes MAC data</dd>
</dl>
<h4>Public keys, signatures, and fingerprints</h4>
<p>OTR users have long-lived public keys that they use for
authentication (but <em>not</em> encryption). The current version of
the OTR protocol only supports DSA public keys, but there is a key type
marker for future extensibility.</p>
<dl>
<dt>OTR public authentication DSA key (PUBKEY):</dt>
<dd>Pubkey type (SHORT)
<ul class="note"><li>DSA public keys have type 0x0000</li></ul>
p (MPI)
<br />q (MPI)
<br />g (MPI)
<br />y (MPI)
<ul class="note"><li>(p,q,g,y) are the DSA public key parameters</li></ul>
</dd>
</dl>
<p>OTR public keys are used to generate <b>signatures</b>; different
types of keys produce signatures in different formats. The format for a
signature made by a DSA public key is as follows:</p>
<dl>
<dt>DSA signature (SIG):</dt>
<dd> (len is the length of the DSA public parameter q, which in
current implementations must be 20 bytes, or 160 bits)
<br /> len byte unsigned r, big-endian
<br /> len byte unsigned s, big-endian</dd>
</dl>
<p>OTR public keys have <b>fingerprints</b>, which are hex strings that
serve as identifiers for the public key. The fingerprint is calculated
by taking the SHA-1 hash of the byte-level representation of the public
key. However, there is an exception for backwards compatibility: if the
pubkey type is 0x0000, those two leading 0x00 bytes are omitted from the
data to be hashed. The encoding assures that, assuming the hash
function itself has no useful collisions, and DSA keys have length less
than 524281 bits (500 times larger than most DSA keys), no two public
keys will have the same fingerprint.</p>
<h4>Instance Tags</h4>
<p>Clients include instance tags in all OTR version 3 messages. Instance
tags are 32-bit values that are intended to be persistent. If the same
client is logged into the same account from multiple locations, the
intention is that the client will have different instance tags at each
location. As shown below, OTR version 3 messages (fragmented and
unfragmented) include the source and destination instance tags. If a client
receives a message that lists a destination instance tag different from its
own, the client should discard the message.</p>
<p>The smallest valid instance tag is 0x00000100. It is appropriate to set the
destination instance tag to '0' when an actual destination instance tag is
not known at the time the message is prepared. If a client receives a
message with the sender instance tag set to less than 0x00000100, it should
discard the message. Similarly, if a client receives a message with the
recipient instance tag set to greater than 0 but less than 0x00000100, it
should discard the message.
</p>
<p>This avoids an issue on IM networks that always relay all messages to
all sessions of a client who is logged in multiple times. In this
situation, OTR clients can attempt to establish an OTR session indefinitely
if there are interleaving messages from each of the sessions.</p>
<h4>D-H Commit Message</h4>
<p>This is the first message of the AKE. Bob sends it to Alice to
commit to a choice of D-H encryption key (but the key itself is not yet
revealed). This allows the secure session id to be much shorter than in
OTR version 1, while still preventing a man-in-the-middle attack on
it.</p>
<dl>
<dt>Protocol version (SHORT)</dt>
<dd>The version number of this protocol is 0x0003.</dd>
<dt>Message type (BYTE)</dt>
<dd>The D-H Commit Message has type 0x02.</dd>
<dt>Sender Instance tag (INT)</dt>
<dd>The instance tag of the person sending this message.</dd>
<dt>Receiver Instance tag (INT)</dt>
<dd>The instance tag of the intended recipient.
For a commit message this will often be 0, since the other party
may not have identified their instance tag yet.</dd>
<dt>Encrypted g<sup>x</sup> (DATA)</dt>
<dd>Produce this field as follows:
<ul>
<li>Choose a random value r (128 bits)</li>
<li>Choose a random value x (at least 320 bits)</li>
<li>Serialize g<sup>x</sup> as an MPI, gxmpi. [gxmpi will probably be
196 bytes long, starting with "\x00\x00\x00\xc0".]</li>
<li>Encrypt gxmpi using AES128-CTR, with key r and initial counter value
0. The result will be the same length as gxmpi.</li>
<li>Encode this encrypted value as the DATA field.</li>
</ul></dd>
<dt>Hashed g<sup>x</sup> (DATA)</dt>
<dd>This is the SHA256 hash of gxmpi.</dd>
</dl>
<h4>D-H Key Message</h4>
<p>This is the second message of the AKE. Alice sends it to Bob, and it
simply consists of Alice's D-H encryption key.</p>
<dl>
<dt>Protocol version (SHORT)</dt>
<dd>The version number of this protocol is 0x0003.</dd>
<dt>Message type (BYTE)</dt>
<dd>The D-H Key Message has type 0x0a.</dd>
<dt>Sender Instance tag (INT)</dt>
<dd>The instance tag of the person sending this message.</dd>
<dt>Receiver Instance tag (INT)</dt>
<dd>The instance tag of the intended recipient.</dd>
<dt>g<sup>y</sup> (MPI)</dt>
<dd>Choose a random value y (at least 320 bits), and calculate
g<sup>y</sup>.</dd>
</dl>
<h4>Reveal Signature Message</h4>
<p>This is the third message of the AKE. Bob sends it to Alice,
revealing his D-H encryption key (and thus opening an encrypted
channel), and also authenticating himself (and the parameters of the
channel, preventing a man-in-the-middle attack on the channel itself) to
Alice.</p>
<dl>
<dt>Protocol version (SHORT)</dt>
<dd>The version number of this protocol is 0x0003.</dd>
<dt>Message type (BYTE)</dt>
<dd>The Reveal Signature Message has type 0x11.</dd>
<dt>Sender Instance tag (INT)</dt>
<dd>The instance tag of the person sending this message.</dd>
<dt>Receiver Instance tag (INT)</dt>
<dd>The instance tag of the intended recipient.</dd>
<dt>Revealed key (DATA)</dt>
<dd>This is the value r picked earlier.</dd>
<dt>Encrypted signature (DATA)</dt>
<dd>This field is calculated as follows:
<ul>
<li>Compute the Diffie-Hellman shared secret s.</li>
<li>Use s to compute an AES key c and two MAC keys m1 and m2, as specified below.</li>
<li>Select keyid<sub>B</sub>, a serial number for the D-H key computed
earlier. It is an INT, and must be greater than 0.</li>
<li>Compute the 32-byte value M<sub>B</sub> to be the SHA256-HMAC of the
following data, using the key m1:<dl>
<dt>g<sup>x</sup> (MPI)</dt>
<dt>g<sup>y</sup> (MPI)</dt>
<dt>pub<sub>B</sub> (PUBKEY)</dt>
<dt>keyid<sub>B</sub> (INT)</dt>
</dl></li>
<li>Let X<sub>B</sub> be the following structure:<dl>
<dt>pub<sub>B</sub> (PUBKEY)</dt>
<dt>keyid<sub>B</sub> (INT)</dt>
<dt>sig<sub>B</sub>(M<sub>B</sub>) (SIG)</dt>
<dd>This is the signature, using the private part of the key
pub<sub>B</sub>, of the 32-byte M<sub>B</sub> (which does not need to be
hashed again to produce the signature).</dd>
</dl></li>
<li>Encrypt X<sub>B</sub> using AES128-CTR with key c and initial
counter value 0.</li>
<li>Encode this encrypted value as the DATA field.</li>
</ul></dd>
<dt>MAC'd signature (MAC)</dt>
<dd>This is the SHA256-HMAC-160 (that is, the first 160 bits of the
SHA256-HMAC) of the encrypted signature field (including the four-byte
length), using the key m2.</dd>
</dl>
<h4>Signature Message</h4>
<p>This is the final message of the AKE. Alice sends it to Bob,
authenticating herself and the channel parameters to him.</p>
<dl>
<dt>Protocol version (SHORT)</dt>
<dd>The version number of this protocol is 0x0003.</dd>
<dt>Message type (BYTE)</dt>
<dd>The Signature Message has type 0x12.</dd>
<dt>Sender Instance tag (INT)</dt>
<dd>The instance tag of the person sending this message.</dd>
<dt>Receiver Instance tag (INT)</dt>
<dd>The instance tag of the intended recipient.</dd>
<dt>Encrypted signature (DATA)</dt>
<dd>This field is calculated as follows:
<ul>
<li>Compute the Diffie-Hellman shared secret s.</li>
<li>Use s to compute an AES key c' and two MAC keys m1' and m2', as specified below.</li>
<li>Select keyid<sub>A</sub>, a serial number for the D-H key computed
earlier. It is an INT, and must be greater than 0.</li>
<li>Compute the 32-byte value M<sub>A</sub> to be the SHA256-HMAC of the
following data, using the key m1':<dl>
<dt>g<sup>y</sup> (MPI)</dt>
<dt>g<sup>x</sup> (MPI)</dt>
<dt>pub<sub>A</sub> (PUBKEY)</dt>
<dt>keyid<sub>A</sub> (INT)</dt>
</dl></li>
<li>Let X<sub>A</sub> be the following structure:<dl>
<dt>pub<sub>A</sub> (PUBKEY)</dt>
<dt>keyid<sub>A</sub> (INT)</dt>
<dt>sig<sub>A</sub>(M<sub>A</sub>) (SIG)</dt>
<dd>This is the signature, using the private part of the key
pub<sub>A</sub>, of the 32-byte M<sub>A</sub> (which does not need to be
hashed again to produce the signature).</dd>
</dl></li>
<li>Encrypt X<sub>A</sub> using AES128-CTR with key c' and initial
counter value 0.</li>
<li>Encode this encrypted value as the DATA field.</li>
</ul></dd>
<dt>MAC'd signature (MAC)</dt>
<dd>This is the SHA256-HMAC-160 (that is, the first 160 bits of the
SHA256-HMAC) of the encrypted signature field (including the four-byte
length), using the key m2'.</dd>
</dl>
<h4>Data Message</h4>
<p>This message is used to transmit a private message to the
correspondent. It is also used to reveal old MAC keys.</p>
<p>The plaintext message (either before encryption, or after decryption)
consists of a human-readable message (encoded in UTF-8, optionally with
HTML markup), optionally followed by:</p>
<ul>
<li>a single NUL (a BYTE with value 0x00), <b>and</b></li>
<li>zero or more TLV (type/length/value) records (with no padding
between them)</li>
</ul>
<p>Each TLV record is of the form:</p>
<dl>
<dt>Type (SHORT)</dt>
<dd>The type of this record. Records with unrecognized types should be
ignored.</dd>
<dt>Length (SHORT)</dt>
<dd>The length of the following field</dd>
<dt>Value (len BYTEs) [where len is the value of the Length field]</dt>
<dd>Any pertinent data for the record type.</dd>
</dl>
<p>Some TLV examples:</p>
<dl>
<dt>\x00\x01\x00\x00</dt>
<dd>A TLV of type 1, containing no data</dd>
<dt>\x00\x00\x00\x05\x68\x65\x6c\x6c\x6f</dt>
<dd>A TLV of type 0, containing the value "hello"</dd>
</dl>
<p>The currently defined TLV record types are:</p>
<dl>
<dt>Type 0: Padding</dt>
<dd>The value may be an arbitrary amount of data, which should be
ignored. This type can be used to disguise the length of the plaintext
message.</dd>
<dt>Type 1: Disconnected</dt>
<dd>If the user requests to close the private connection, you may send a
message (possibly with empty human-readable part) containing a record
with this TLV type just before you discard the session keys, and
transition to MSGSTATE_PLAINTEXT (see below). If you receive a TLV
record of this type, you should transition to MSGSTATE_FINISHED (see
below), and inform the user that his correspondent has closed his end of
the private connection, and the user should do the same.</dd>
<dt>Type 2: SMP Message 1</dt>
<dd>The value represents an initiating message of the Socialist
Millionaires' Protocol, described below.</dd>
<dt>Ty