@tradle/otr

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html><head> <title>Off-the-Record Messaging Protocol version 3 - DRAFT</title> <style type="text/css"> body { background: white; color: black } h1 { text-align: center } dd ul.note { list-style: none } dl.doublespace dd { margin-bottom: 2ex } </style> </head><body> <h1>Off-the-Record Messaging Protocol version 3</h1> This document describes version 3 of the Off-the-Record Messaging protocol. The main changes over version 2 include: <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> 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. <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> 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. The semantics of the OTR Query Message are that Alice is requesting 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 indicating 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 would start an OTR conversation upon receiving an OTR Query Message, but would not upon receiving the whitespace tag. <h3>Authenticated Key Exchange (AKE)</h3> 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 pubA and pubB, respectively. The general idea is that Alice and Bob do an unauthenticated Diffie-Hellman (D-H) key exchange to set up an encrypted channel, and then do mutual authentication inside that channel. Bob will be initiating the AKE with Alice. <ul> <li>Bob: <ol> <li>Picks a random value r (128 bits)</li> <li>Picks a random value x (at least 320 bits)</li> <li>Sends Alice AESr(gx), HASH(gx)</li> </ol></li> <li>Alice: <ol> <li>Picks a random value y (at least 320 bits)</li> <li>Sends Bob gy</li> </ol></li> <li>Bob: <ol> <li>Verifies that Alice's gy is a legal value (2 <= gy <= modulus-2)</li> <li>Computes s = (gy)x</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 keyidB, a serial number for his D-H key gx</li> <li>Computes MB = MACm1(gx, gy, pubB, keyidB)</li> <li>Computes XB = pubB, keyidB, sigB(MB)</li> <li>Sends Alice r, AESc(XB), MACm2(AESc(XB))</li> </ol></li> <li>Alice: <ol> <li>Uses r to decrypt the value of gx sent earlier</li> <li>Verifies that HASH(gx) matches the value sent earlier</li> <li>Verifies that Bob's gx is a legal value (2 <= gx <= modulus-2)</li> <li>Computes s = (gx)y (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 MACm2(AESc(XB))</li> <li>Uses c to decrypt AESc(XB) to obtain XB = pubB, keyidB, sigB(MB)</li> <li>Computes MB = MACm1(gx, gy, pubB, keyidB)</li> <li>Uses pubB to verify sigB(MB)</li> <li>Picks keyidA, a serial number for her D-H key gy</li> <li>Computes MA = MACm1'(gy, gx, pubA, keyidA)</li> <li>Computes XA = pubA, keyidA, sigA(MA)</li> <li>Sends Bob AESc'(XA), MACm2'(AESc'(XA))</li> </ol></li> <li>Bob: <ol> <li>Uses m2' to verify MACm2'(AESc'(XA))</li> <li>Uses c' to decrypt AESc'(XA) to obtain XA = pubA, keyidA, sigA(MA)</li> <li>Computes MA = MACm1'(gy, gx, pubA, keyidA)</li> <li>Uses pubA to verify sigA(MA)</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 pubB, and similarly for Bob.</li> </ul> <h3>Exchanging data</h3> 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. Suppose Alice has a message (msg) to send to Bob. <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 keyA by that key, and let keyidA 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 keyidA+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 keyB by that key, and let keyidB be its serial number.</li> <li>Uses Diffie-Hellman to compute a shared secret from the two keys keyA and keyB, 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 (keyA, keyB, ctr) is never the same for more than one Data Message Alice sends to Bob.</li> <li>Computes TA = (keyidA, keyidB, next_dh, ctr, AES-CTRek,ctr(msg))</li> <li>Sends Bob TA, MACmk(TA), oldmackeys</li> </ol></li> <li>Bob: <ol> <li>Uses Diffie-Hellman to compute a shared secret from the two keys labelled by keyidA and keyidB, 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 MACmk(TA).</li> <li>Uses ek and ctr to decrypt AES-CTRek,ctr(msg).</li> </ol> </li> </ul> <h3>Socialist Millionaires' Protocol (SMP)</h3> 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 g1 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. 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. Assuming that Alice begins the exchange: <ul> <li>Alice: <ol> <li>Picks random exponents a2 and a3</li> <li>Sends Bob g2a = g1a2 and g3a = g1a3</li> </ol></li> <li>Bob: <ol> <li>Picks random exponents b2 and b3</li> <li>Computes g2b = g1b2 and g3b = g1b3</li> <li>Computes g2 = g2ab2 and g3 = g3ab3</li> <li>Picks random exponent r</li> <li>Computes Pb = g3r and Qb = g1r g2y</li> <li>Sends Alice g2b, g3b, Pb and Qb</li> </ol></li> <li>Alice: <ol> <li>Computes g2 = g2ba2 and g3 = g3ba3</li> <li>Picks random exponent s</li> <li>Computes Pa = g3s and Qa = g1s g2x</li> <li>Computes Ra = (Qa / Qb) a3</li> <li>Sends Bob Pa, Qa and Ra</li> </ol></li> <li>Bob: <ol> <li>Computes Rb = (Qa / Qb) b3</li> <li>Computes Rab = Rab3</li> <li>Checks whether Rab == (Pa / Pb)</li> <li>Sends Alice Rb</li> </ol></li> <li>Alice: <ol> <li>Computes Rab = Rba3</li> <li>Checks whether Rab == (Pa / Pb)</li> </ol></li> <li>If everything is done correctly, then Rab should hold the value of (Pa / Pb) times (g2a3b3)(x - y), which means that the test at the end of the protocol will only succeed if x == y. Further, since g2a3b3 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> This section describes the messages in the OTR protocol that are not base-64 encoded binary. <h4>OTR Query Messages</h4> 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: <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> For example: <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> 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. <h4>Tagged plaintext messages</h4> 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). 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: <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> 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. <h4>OTR Error Messages</h4> 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. <h3>Encoded messages</h3> 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 ".". For the Diffie-Hellman group computations, the group is the one defined in RFC 3526 with 1536-bit modulus (hex, big-endian): <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> 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. <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 len byte unsigned value, big-endian (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 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> OTR users have long-lived public keys that they use for authentication (but not encryption). The current version of the OTR protocol only supports DSA public keys, but there is a key type marker for future extensibility. <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) q (MPI) g (MPI) y (MPI) <ul class="note"><li>(p,q,g,y) are the DSA public key parameters</li></ul> </dd> </dl> OTR public keys are used to generate signatures; different types of keys produce signatures in different formats. The format for a signature made by a DSA public key is as follows: <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) len byte unsigned r, big-endian len byte unsigned s, big-endian</dd> </dl> OTR public keys have fingerprints, 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. <h4>Instance Tags</h4> 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. 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. 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. <h4>D-H Commit Message</h4> 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. <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 gx (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 gx 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 gx (DATA)</dt> <dd>This is the SHA256 hash of gxmpi.</dd> </dl> <h4>D-H Key Message</h4> This is the second message of the AKE. Alice sends it to Bob, and it simply consists of Alice's D-H encryption key. <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>gy (MPI)</dt> <dd>Choose a random value y (at least 320 bits), and calculate gy.</dd> </dl> <h4>Reveal Signature Message</h4> 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. <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 keyidB, 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 MB to be the SHA256-HMAC of the following data, using the key m1:<dl> <dt>gx (MPI)</dt> <dt>gy (MPI)</dt> <dt>pubB (PUBKEY)</dt> <dt>keyidB (INT)</dt> </dl></li> <li>Let XB be the following structure:<dl> <dt>pubB (PUBKEY)</dt> <dt>keyidB (INT)</dt> <dt>sigB(MB) (SIG)</dt> <dd>This is the signature, using the private part of the key pubB, of the 32-byte MB (which does not need to be hashed again to produce the signature).</dd> </dl></li> <li>Encrypt XB 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> This is the final message of the AKE. Alice sends it to Bob, authenticating herself and the channel parameters to him. <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 keyidA, 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 MA to be the SHA256-HMAC of the following data, using the key m1':<dl> <dt>gy (MPI)</dt> <dt>gx (MPI)</dt> <dt>pubA (PUBKEY)</dt> <dt>keyidA (INT)</dt> </dl></li> <li>Let XA be the following structure:<dl> <dt>pubA (PUBKEY)</dt> <dt>keyidA (INT)</dt> <dt>sigA(MA) (SIG)</dt> <dd>This is the signature, using the private part of the key pubA, of the 32-byte MA (which does not need to be hashed again to produce the signature).</dd> </dl></li> <li>Encrypt XA 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> This message is used to transmit a private message to the correspondent. It is also used to reveal old MAC keys. 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: <ul> <li>a single NUL (a BYTE with value 0x00), and</li> <li>zero or more TLV (type/length/value) records (with no padding between them)</li> </ul> Each TLV record is of the form: <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> Some TLV examples: <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> The currently defined TLV record types are: <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>Type 3: SMP Message 2</dt> <dd>The value represents the second message in an instance of SMP.</dd> <dt>Type 4: SMP Message 3</dt> <dd>The value represents the third message in an instance of SMP.</dd> <dt>Type 5: SMP Message 4</dt> <dd>The value represents the final message in an instance of SMP.</dd> <dt>Type 6: SMP Abort Message</dt> <dd>If the user cancels SMP prematurely or encounters an error in the protocol and cannot continue, you may send a message (possibly with empty human-readable part) with this TLV type to instruct the other party's client to abort the protocol. The associated length should be zero and the associated value should be empty. If you receive a TLV of this type, you should change the SMP state to SMP_EXPECT1 (see below).</dd> <dt>Type 7: SMP Message 1Q</dt> <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>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 not placed into the TLV; your buddy will compute it on his/her own. </dd> </dl> SMP Message TLVs (types 2-5) all carry data sharing the same general format: <dl> <dt>MPI count (INT)</dt> <dd>The number of MPIs contained in the remainder of the TLV.</dd> <dt>MPI 1 (MPI)</dt> <dd>The first MPI of the TLV, serialized into a byte array.</dd> <dt>MPI 2 (MPI)</dt> <dd>The second MPI of the TLV, serialized into a byte array.</dd> <dt>etc.</dt> </dl> There should be as many MPIs as declared in the MPI count field. For the exact MPIs passed for each SMP TLV, see the SMP state machine below. A message with an empty human-readable part (the plaintext is of zero length, or starts with a NUL) is a "heartbeat" packet, and should not be displayed to the user. (But it's still useful to effect key rotations.) Data Message format: <dl> <dt>Protocol version (SHORT)</dt> <dd>The version number of this protocol is 0x0003.</dd> <dt>Message type (BYTE)</dt> <dd>The Data Message has type 0x03.</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>Flags (BYTE)</dt> <dd>The bitwise-OR of the flags for this message. Usually you should set this to 0x00. The only currently defined flag is:<dl> <dt>IGNORE_UNREADABLE (0x01)</dt> <dd>If you receive a Data Message with this flag set, and you are unable to decrypt the message or verify the MAC (because, for example, you don't have the right keys), just ignore the message instead of producing some kind of error or notification to the user.</dd> </dl></dd> <dt>Sender keyid (INT)</dt> <dd>Must be strictly greater than 0, and increment by 1 with each key change</dd> <dt>Recipient keyid (INT)</dt> <dd>Must therefore be strictly greater than 0, as the receiver has no key with id 0. The sender and recipient keyids are those used to encrypt and MAC this message.</dd> <dt>DH y (MPI)</dt> <dd>The *next* [i.e. sender_keyid+1] public key for the sender</dd> <dt>Top half of counter init (CTR)</dt> <dd>This should monotonically increase (as a big-endian value) for each message sent with the same (sender keyid, recipient keyid) pair, and must not be all 0x00.</dd> <dt>Encrypted message (DATA)</dt> <dd>Using the appropriate encryption key (see below) derived from the sender's and recipient's DH public keys (with the keyids given in this message), perform AES128 counter-mode (CTR) encryption of the message. The initial counter is a 16-byte value whose first 8 bytes are the above "top half of counter init" value, and whose last 8 bytes are all 0x00. Note that counter mode does not change the length of the message, so no message padding needs to be done. If you *want* to do message padding (to disguise the length of your message), use the above TLV of type 0.</dd> <dt>Authenticator (MAC)</dt> <dd>The SHA1-HMAC, using the appropriate MAC key (see below) of everything from the Protocol version to the end of the encrypted message</dd> <dt>Old MAC keys to be revealed (DATA)</dt> <dd>See "Revealing MAC Keys", below.</dd> </dl> <h3>Socialist Millionaires' Protocol (SMP)</h3> The Socialist Millionaires' Protocol allows two parties with secret information x and y respectively to check whether (x==y) without revealing any additional information about the secrets. The protocol used by OTR is based on the work of Boudot, Schoenmakers and Traore (2001). A full justification for its use in OTR is made by Alexander and Goldberg, in a paper published in 2007. The following is a technical account of what is transmitted during the course of the protocol. <h4>Secret information</h4> The secret information x and y compared during this protocol contains not only information entered by the users, but also information unique to the conversation in which SMP takes place. Specifically, the format is: <dl> <dt>Version (BYTE)</dt> <dd>The version of SMP used. The version described here is 1.</dd> <dt>Initiator fingerprint (20 BYTEs)</dt> <dd>The fingerprint that the party initiating SMP is using in the current conversation.</dd> <dt>Responder fingerprint (20 BYTEs)</dt> <dd>The fingerprint that the party that did not initiate SMP is using in the current conversation.</dd> <dt>Secure Session ID</dt> <dd>The ssid described below.</dd> <dt>User-specified secret</dt> <dd>The input string given by the user at runtime.</dd> </dl> Then the SHA256 hash of the above is taken, and the digest becomes the actual secret (x or y) to be used in SMP. The additional fields insure that not only do both parties know the same secret input string, but no man-in-the-middle is capable of reading their communication either. <h3>The SMP state machine</h3> Whenever the OTR message state machine has MSGSTATE_ENCRYPTED set (see below), the SMP state machine may progress. If at any point MSGSTATE_ENCRYPTED becomes unset, SMP must abandon its state and return to its initial setup. The SMP state consists of one main variable, as well as information from the partial computations at each protocol step. <h4>Expected Message</h4> This main state variable for SMP controls what SMP-specific TLVs will be accepted. This variable has no effect on type 0 or type 1 TLVs, which are always allowed. smpstate can take one of four values: <dl> <dt>SMPSTATE_EXPECT1</dt> <dd>This state indicates that only type 2 (SMP message 1) and type 7 (SMP message 1Q) TLVs should be accepted. This is the default state when SMP has not yet begun. This state is also reached whenever an error occurs or SMP is aborted, and the protocol must be restarted from the beginning.</dd> <dt>SMPSTATE_EXPECT2</dt> <dd>This state indicates that only type 3 TLVs (SMP message 2) should be accepted.</dd> <dt>SMPSTATE_EXPECT3</dt> <dd>This state indicates that only type 4 TLVs (SMP message 3) should be accepted.</dd> <dt>SMPSTATE_EXPECT4</dt> <dd>This state indicates that only type 5 TLVs (SMP message 4) should be accepted.</dd> </dl> <h4>State Transitions</h4> There are 7 actions that an OTR client must handle: <ul> <li>Received TLVs: <ul> <li>SMP Message 1</li> <li>SMP Message 2</li> <li>SMP Message 3</li> <li>SMP Message 4</li> <li>SMP Abort Message</li> </ul></li> <li>User actions:</li> <ul> <li>User requests to begin SMP</li> <li>User requests to abort SMP</li> </ul></li> </ul> The following sections outline what is to be done in each case. They all assume that MSGSTATE_ENCRYPTED is set. For simplicity, they also assume that Alice has begun SMP, and Bob is responding to her. <h4>SMP Hash function</h4> In the following actions, there are many places where a SHA256 hash of an integer followed by one or two MPIs is taken. The input to this hash function is: <dl> <dt>Version (BYTE)</dt> <dd>This distinguishes calls to the hash function at different points in the protocol, to prevent Alice from replaying Bob's zero knowledge proofs or vice versa.</dd> <dt>First MPI (MPI)</dt> <dd>The first MPI given as input, serialized in the usual way.</dd> <dt>Second MPI (MPI)</dt> <dd>The second MPI given as input, if present, serialized in the usual way. If only one MPI is given as input, this field is simply omitted.</dd> </dl> <h4>Receiving a type 2 TLV (SMP message 1)</h4> SMP message 1 is sent by Alice to begin a DH exchange to determine two new generators, g2 and g3. It contains the following mpi values: <dl> <dt>g2a</dt> <dd>Alice's half of the DH exchange to determine g2.</dd> <dt>c2, D2</dt> <dd>A zero-knowledge proof that Alice knows the exponent associated with her transmitted value g2a.</dd> <dt>g3a</dt> <dd>Alice's half of the DH exchange to determine g3.</dd> <dt>c3, D3</dt> <dd>A zero-knowledge proof that Alice knows the exponent associated with her transmitted value g3a.</dd> </dl> A type 7 (SMP Message 1Q) TLV is the same as the above, but is preceded by a user-specified question, which is associated with the user-specified portion of the secret. When Bob receives this TLV he should do: <dl> <dt>If smpstate is not SMPSTATE_EXPECT1:</dt> <dd>Set smpstate to SMPSTATE_EXPECT1 and send a type 6 TLV (SMP abort) to Alice.</dd> <dt>If smpstate is SMPSTATE_EXPECT1:</dt> <dd>Verify Alice's zero-knowledge proofs for g2a and g3a: <ol> <li>Check that both g2a and g3a are >= 2 and <= modulus-2.</li> <li>Check that c2 = SHA256(1, g1D2 g2ac2).</li> <li>Check that c3 = SHA256(2, g1D3 g3ac3).</li> </ol> Create a type 3 TLV (SMP message 2) and send it to Alice: <ol> <li>Determine Bob's secret input y, which is to be compared to Alice's secret x.</li> <li>Pick random exponents b2 and b3. These will used during the DH exchange to pick generators.</li> <li>Pick random exponents r2, r3, r4, r5 and r6. These will be used to add a blinding factor to the final results, and to generate zero-knowledge proofs that this message was created honestly.</li> <li>Compute g2b = g1b2 and g3b = g1b3</li> <li>Generate a zero-knowledge proof that the exponent b2 is known by setting c2 = SHA256(3, g1r2) and D2 = r2 - b2 c2 mod q. In the zero-knowledge proofs the D values are calculated modulo q = (p - 1) / 2, where p is the same 1536-bit prime as elsewhere. The random exponents are 1536-bit numbers.</li> <li>Generate a zero-knowledge proof that the exponent b3 is known by setting c3 = SHA256(4, g1r3) and D3 = r3 - b3 c3 mod q.</li> <li>Compute g2 = g2ab2 and g3 = g3ab3</li> <li>Compute Pb = g3r4 and Qb = g1r4 g2y</li> <li>Generate a zero-knowledge proof that Pb and Qb were created according to the protocol by setting cP = SHA256(5, g3r5, g1r5 g2r6), D5 = r5 - r4 cP mod q and D6 = r6 - y cP mod q.</li> <li>Store the values of g3a, g2, g3, b3, Pb and Qb for use later in the protocol.</li> <li>Send Alice a type 3 TLV (SMP message 2) containing g2b, c2, D2, g3b, c3, D3, Pb, Qb, cP, D5 and D6, in that order.</li> </ol> Set smpstate to SMPSTATE_EXPECT3.</dd> </dl> <h4>Receiving a type 3 TLV (SMP message 2)</h4> SMP message 2 is sent by Bob to complete the DH exchange to determine the new generators, g2 and g3. It also begins the construction of the values used in the final comparison of the protocol. It contains the following mpi values: <dl> <dt>g2b</dt> <dd>Bob's half of the DH exchange to determine g2.</dd> <dt>c2, D2</dt> <dd>A zero-knowledge proof that Bob knows the exponent associated with his transmitted value g2b.</dd> <dt>g3b</dt> <dd>Bob's half of the DH exchange to determine g3.</dd> <dt>c3, D3</dt> <dd>A zero-knowledge proof that Bob knows the exponent associated with his transmitted value g3b.</dd> <dt>Pb, Qb</dt> <dd>These values are used in the final comparison to determine if Alice and Bob share the same secret.</dd> <dt>cP, D5, D6</dt> <dd>A zero-knowledge proof that Pb and Qb were created according to the protcol given above.</dd> </dl> When Alice receives this TLV she should do: <dl> <dt>If smpstate is not SMPSTATE_EXPECT2:</dt> <dd>Set smpstate to SMPSTATE_EXPECT1 and send a type 6 TLV (SMP abort) to Bob.</dd> <dt>If smpstate is SMPSTATE_EXPECT2:</dt> <dd>Verify Bob's zero-knowledge proofs for g2b, g3b, Pb and Qb: <ol> <li>Check that g2b, g3b, Pb and Qb are >= 2 and <= modulus-2.</li> <li>Check that c2 = SHA256(3, g1D2 g2bc2).</li> <li>Check that c3 = SHA256(4, g1D3 g3bc3).</li> <li>Check that cP = SHA256(5, g3D5 PbcP, g1D5 g2D6 QbcP).</li> </ol> Create a type 4 TLV (SMP message 3) and send it to Bob: <ol> <li>Pick random exponents r4, r5, r6 and r7. These will be used to add a blinding factor to the final results, and to generate zero-knowledge proofs that this message was created honestly.</li> <li>Compute g2 = g2ba2 and g3 = g3ba3</li> <li>Compute Pa = g3r4 and Qa = g1r4 g2x</li> <li>Generate a zero-knowledge proof that Pa and Qa were created according to the protocol by setting cP = SHA256(6, g3r5, g1r5 g2r6), D5 = r5 - r4 cP mod q and D6 = r6 - x cP mod q.</li> <li>Compute Ra = (Qa / Qb) a3</li> <li>Generate a zero-knowledge proof that Ra was created according to the protocol by setting cR = SHA256(7, g1r7, (Qa / Qb)r7) and D7 = r7 - a3 cR mod q.</li> <li>Store the values of g3b, (Pa / Pb), (Qa / Qb) and Ra for use later in the protocol.</li> <li>Send Bob a type 4 TLV (SMP message 3) containing Pa, Qa, cP, D5, D6, Ra, cR and D7 in that order.</li> </ol> Set smpstate to SMPSTATE_EXPECT4.</dd> </dl> <h4>Receiving a type 4 TLV (SMP message 3)</h4> SMP message 3 is Alice's final message in the SMP exchange. It has the last of the information required by Bob to determine if x = y. It contains the following mpi values: <dl> <dt>Pa, Qa</dt> <dd>These values are used in the final comparison to determine if Alice and Bob share the same secret.</dd> <dt>cP, D5, D6</dt> <dd>A zero-knowledge proof that Pa and Qa were created according to the protcol given above.</dd> <dt>Ra</dt> <dd>This value is used in the final comparison to determine if Alice and Bob share the same secret.</dd> <dt>cR, D7</dt> <dd>A zero-knowledge proof that Ra was created according to the protcol given above.</dd> <dt> </dl> When Bob receives this TLV he should do: <dl> <dt>If smpstate is not SMPSTATE_EXPECT3:</dt> <dd>Set smpstate to SMPSTATE_EXPECT1 and send a type 6 TLV (SMP abort) to Bob.</dd> <dt>If smpstate is SMPSTATE_EXPECT3:</dt> <dd>Verify Alice's zero-knowledge proofs for Pa, Qa and Ra: <ol> <li>Check that Pa, Qa and Ra are >= 2 and <= modulus-2.</li> <li>Check that cP = SHA256(6, g3D5 PacP, g1D5 g2D6 QacP).</li> <li>Check that cR = SHA256(7, g1D7 g3acR, (Qa / Qb)D7 RacR).</li> </ol> Create a type 5 TLV (SMP message 4) and send it to Alice: <ol> <li>Pick a random exponent r7. This will be used to generate Bob's final zero-knowledge proof that this message was created honestly.</li> <li>Compute Rb = (Qa / Qb) b3</li> <li>Generate a zero-knowledge proof that Rb was created according to the protocol by setting cR = SHA256(8, g1r7, (Qa / Qb)r7) and D7 = r7 - b3 cR mod q.</li> <li>Send Alice a type 5 TLV (SMP message 4) containing Rb, cR and D7 in that order.</li> </ol> Check whether the protocol was successful: <ol> <li>Compute Rab = Rab3.</li> <li>Determine if x = y by checking the equivalent condition that (Pa / Pb) = Rab.</li> </ol> Set smpstate to SMPSTATE_EXPECT1, as no more messages are expected from Alice.</dd> </dl> <h4>Receiving a type 5 TLV (SMP message 4)</h4> SMP message 4 is Bob's final message in the SMP exchange. It has the last of the information required by Alice to determine if x = y. It contains the following mpi values: <dl> <dt>Rb</dt> <dd>This value is used in the final comparison to determine if Alice and Bob share the same secret.</dd> <dt>cR, D7</dt> <dd>A zero-knowledge proof that Rb was created according to the protcol given above.</dd> <dt> </dl> When Alice receives this TLV she should do: <dl> <dt>If smpstate is not SMPSTATE_EXPECT4:</dt> <dd>Set smpstate to SMPSTATE_EXPECT1 and send a type 6 TLV (SMP abort) to Bob.</dd> <dt>If smpstate is SMPSTATE_EXPECT4:</dt> <dd>Verify Bob's zero-knowledge proof for Rb: <ol> <li>Check that Rb is >= 2 and <= modulus-2.</li> <li>Check that cR = SHA256(8, g1D7 g3bcR, (Qa / Qb)D7 RbcR).</li> </ol> Check whether the protocol was successful: <ol> <li>Compute Rab = Rba3.</li> <li>Determine if x = y by checking the equivalent condition that (Pa / Pb) = Rab.</li> </ol> Set smpstate to SMPSTATE_EXPECT1, as no more messages are expected from Bob.</dd> </dl> <h4>User requests to begin SMP</h4> <dl> <dt>If smpstate is not set to SMPSTATE_EXPECT1:</dt> <dd>SMP is already underway. If you wish to restart SMP, send a type 6 TLV (SMP abort) to the other party and then proceed as if smpstate was SMPSTATE_EXPECT1. Otherwise, you may simply continue the current SMP instance.</dd> <dt>If smpstate is set to SMPSTATE_EXPECT1:</dt> <dd>No current exchange is underway. In this case, Alice should create a valid type 2 TLV (SMP message 1) as follows: <ol> <li>Determine her secret input x, which is to be compared to Bob's secret y.</li> <li>Pick random values a2 and a3 (128 bits). These will be Alice's exponents for the DH exchange to pick generators.</li> <li>Pick random values r2 and r3 (128 bits). These will be used to generate zero-knowledge proofs that this message was created according to the protocol.</li> <li>Compute g2a = g1a2 and g3a = g1a3</li> <li>Generate a zero-knowledge proof that the exponent a2 is known by setting c2 = SHA256(1, g1r2) and D2 = r2 - a2 c2 mod q.</li> <li>Generate a zero-knowledge proof that the exponent a3 is known by setting c3 = SHA256(2, g1r3) and D3 = r3 - a3 c3 mod q.</li> <li>Store the values of x, a2 and a3 for use later in the protocol.</li> <li>Send Bob a type 2 TLV (SMP message 1) containing g2a, c2, D2, g3a, c3 and D3 in that order.</li> </ol> Set smpstate to SMPSTATE_EXPECT2.</dd> </dl> <h4>User requests to abort SMP</h4> In all cases, send a type 6 TLV (SMP abort) to the correspondent and set smpstate to SMPSTATE_EXPECT1. <h3>Key Management</h3> For each correspondent, keep track of: <dl> <dt>Your two most recent DH public/private key pairs</dt> <dd>our_dh[our_keyid] (most recent) and our_dh[our_keyid-1] (previous)</dd> <dt>His two most recent DH public keys</dt> <dd>their_y[their_keyid] (most recent) and their_y[their_keyid-1] (previous)</dd> </dl> When starting a private conversation with a correspondent, generate two DH key pairs for yourself, and set our_keyid = 2. Note that all DH key pairs sh