~ubuntu-branches/ubuntu/oneiric/libotr/oneiric-security : revision 3

1

<!DOCTYPE html

2

PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

3

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

4

5

<title>Off-the-Record Messaging Protocol version 2 - DRAFT</title>

6

7

body { background: white; color: black }

8

h1 { text-align: center }

9

dd ul.note { list-style: none }

10

dl.doublespace dd { margin-bottom: 2ex }

11

</style>

12

</head><body>

13

<h1>Off-the-Record Messaging Protocol version 2</h1>

14

This document describes version 2 of the Off-the-Record Messaging

15

protocol. The main changes over version 1 include:

16

<ul>

17

<li>Resolving the identity-binding flaw identified by Di Raimondo,

18

Gennaro, and Krawczyk</li>

19

<li>Not revealing the users' public keys to passive eavesdroppers; this

20

could be useful if the application sending the OTR messages is also

21

privacy-preserving</li>

22

<li>Supporting fragmentation of OTR messages, to support IM networks

23

whose maximum message size is very small.</li>

24

<li>Better protocol version control, for future extensibility.</li>

25

</ul>

26

<h2>Very high level overview</h2>

27

OTR assumes a network model which provides in-order delivery of

28

messages, but that some messages may not get delivered at all

29

(for example, if the user disconnects). There may be

30

an active attacker, who is allowed to perform a Denial of

31

Service attack, but not to learn the contents of messages.

32

<ol>

33

<li>Alice signals to Bob that she would like (using an OTR Query Message)

34

or is willing (using a whitespace-tagged plaintext message) to use OTR

35

to communicate. Either mechanism should convey the version(s) of OTR

36

that Alice is willing to use.</li>

37

<li>Bob initiates the authenticated key exchange (AKE) with Alice.

38

Version 2 of OTR uses a variant of the SIGMA protocol as its AKE.</li>

39

<li>Alice and Bob exchange Data Messages to send information to each

40

other.</li>

41

</ol>

42

<h2>High level overview</h2>

43

<h3>Requesting an OTR conversation</h3>

44

There are two ways Alice can inform Bob that she is willing to use

45

the OTR protocol to speak with him: by sending him the OTR Query Message,

46

or by including a special "tag" consisting of whitespace characters in

47

one of her messages to him. Each method also includes a way for Alice

48

to communicate to Bob which versions of the OTR protocol she is willing

49

to speak with him.

50

The semantics of the OTR Query Message are that Alice is

51

requesting that Bob start an OTR conversation with her (if, of

52

course, he is willing and able to do so). On the other hand, the

53

semantics of the whitespace tag are that Alice is merely

54

indicating to Bob that she is willing and able to have an OTR

55

conversation with him. If Bob has a policy of "only use OTR when it's

56

explicitly requested", for example, then he would start an OTR

57

conversation upon receiving an OTR Query Message, but would not

58

upon receiving the whitespace tag.

59

<h3>Authenticated Key Exchange (AKE)</h3>

60

This section outlines the version of the SIGMA protocol used as the

61

AKE. All exponentiations are done modulo a particular 1536-bit prime,

62

and g is a generator of that group, as indicated in the detailed

63

description below. Alice and Bob's long-term authentication public keys

64

are pubA and pubB, respectively.

65

The general idea is that Alice and Bob do an unauthenticated

66

Diffie-Hellman (D-H) key exchange to set up an encrypted channel, and

67

then do mutual authentication inside that channel.

68

Bob will be initiating the AKE with Alice.

69

<ul>

70

<li>Bob:

71

<ol>

72

<li>Picks a random value r (128 bits)</li>

73

<li>Picks a random value x (at least 320 bits)</li>

74

<li>Sends Alice AESr(gx), HASH(gx)</li>

75

</ol></li>

76

<li>Alice:

77

<ol>

78

<li>Picks a random value y (at least 320 bits)</li>

79

<li>Sends Bob gy</li>

80

</ol></li>

81

<li>Bob:

82

<ol>

83

<li>Verifies that Alice's gy is a legal value (2 <=

84

gy <= modulus-2)</li>

85

<li>Computes s = (gy)x</li>

86

<li>Computes two AES keys c, c' and four MAC keys m1, m1', m2, m2' by

87

hashing s in various ways</li>

88

<li>Picks keyidB, a serial number for his D-H key

89

gx</li>

90

<li>Computes MB = MACm1(gx, gy,

91

pubB, keyidB)</li>

92

<li>Computes XB = pubB, keyidB,

93

sigB(MB)</li>

94

<li>Sends Alice r, AESc(XB),

95

MACm2(AESc(XB))</li>

96

</ol></li>

97

<li>Alice:

98

<ol>

99

<li>Uses r to decrypt the value of gx sent earlier</li>

100

<li>Verifies that HASH(gx) matches the value sent earlier</li>

101

<li>Verifies that Bob's gx is a legal value (2 <=

102

gx <= modulus-2)</li>

103

<li>Computes s = (gx)y (note that this will be the

104

same as the value of s Bob calculated)</li>

105

<li>Computes two AES keys c, c' and four MAC keys m1, m1', m2, m2' by

106

hashing s in various ways (the same as Bob)</li>

107

<li>Uses m2 to verify MACm2(AESc(XB))</li>

108

<li>Uses c to decrypt AESc(XB) to obtain

109

XB = pubB, keyidB,

110

sigB(MB)</li>

111

<li>Computes MB = MACm1(gx,

112

gy, pubB, keyidB)</li>

113

<li>Uses pubB to verify sigB(MB)</li>

114

115

<li>Picks keyidA, a serial number for her D-H key

116

gy</li>

117

<li>Computes MA = MACm1'(gy, gx,

118

pubA, keyidA)</li>

119

<li>Computes XA = pubA, keyidA,

120

sigA(MA)</li>

121

<li>Sends Bob AESc'(XA),

122

MACm2'(AESc'(XA))</li>

123

</ol></li>

124

<li>Bob:

125

<ol>

126

<li>Uses m2' to verify MACm2'(AESc'(XA))</li>

127

<li>Uses c' to decrypt AESc'(XA) to obtain

128

XA = pubA, keyidA,

129

sigA(MA)</li>

130

<li>Computes MA = MACm1'(gy,

131

gx, pubA, keyidA)</li>

132

<li>Uses pubA to verify sigA(MA)</li>

133

</ol></li>

134

<li>If all of the verifications succeeded, Alice and Bob now know each

135

other's Diffie-Hellman public keys, and share the value s. Alice is

136

assured that s is known by someone with access to the private key

137

corresponding to pubB, and similarly for Bob.</li>

138

</ul>

139

<h3>Exchanging data</h3>

140

This section outlines the method used to protect data being exchanged

141

between Alice and Bob. As above, all exponentiations are done modulo

142

a particular 1536-bit prime, and g is a generator of

143

that group, as indicated in the detailed description below.

144

Suppose Alice has a message (msg) to send to Bob.

145

<ul>

146

<li>Alice:

147

<ol>

148

<li>Picks the most recent of her own D-H encryption keys that Bob has

149

acknowledged receiving (by using it in a Data Message, or failing that,

150

in the AKE). Let keyA by that key, and let keyidA

151

be its serial number.</li>

152

<li>If the above key is Alice's most recent key, she generates a new D-H key

153

(next_dh), to get the serial number keyidA+1.</li>

154

<li>Picks the most recent of Bob's D-H encryption keys that she has

155

received from him (either in a Data Message or in the AKE). Let

156

keyB by that key, and let keyidB be its serial

157

number.</li>

158

<li>Uses Diffie-Hellman to compute a shared secret from the two keys

159

keyA and keyB, and generates the

160

sending AES key, ek, and the sending MAC key, mk, as detailed

161

below.</li>

162

<li>Collects any old MAC keys that were used in previous messages, but

163

will never again be used (because their associated D-H keys are no

164

longer the most recent ones) into a list, oldmackeys.</li>

165

<li>Picks a value of the counter, ctr, so that the triple

166

(keyA, keyB, ctr) is never the same for more

167

than one Data Message Alice sends to Bob.</li>

168

<li>Computes TA = (keyidA, keyidB, next_dh,

169

ctr, AES-CTRek,ctr(msg))</li>

170

<li>Sends Bob TA, MACmk(TA),

171

oldmackeys</li>

172

</ol></li>

173

<li>Bob:

174

<ol>

175

<li>Uses Diffie-Hellman to compute a shared secret from the two keys

176

labelled by keyidA and keyidB, and generates the

177

receiving AES key, ek, and the receiving MAC key, mk, as detailed

178

below. (These will be the same as the keys Alice generated, above.)</li>

179

<li>Uses mk to verify MACmk(TA).</li>

180

<li>Uses ek and ctr to decrypt

181

AES-CTRek,ctr(TA).</li>

182

</ol>

183

</li>

184

</ul>

185

<h2>Details of the protocol</h2>

186

<h3>Unencoded messages</h3>

187

This section describes the messages in the OTR protocol that are not

188

base-64 encoded binary.

189

<h4>OTR Query Messages</h4>

190

If Alice wishes to communicate to Bob that she would like to use OTR,

191

she sends a message containing the string "?OTR" followed by an

192

indication of what versions of OTR she is willing to use with Bob. The

193

version string is constructed as follows:

194

<ul>

195

<li>If she is willing to use OTR version 1, the version string must

196

start with "?".</li>

197

<li>If she is willing to use OTR versions other than 1, a "v" followed

198

by the byte identifiers for the versions in question, followed by "?".

199

The byte identifier for OTR version 2 is "2". The order of the

200

identifiers between the "v" and the "?" does not matter, but none should

201

be listed more than once.</li>

202

</ul>

203

For example:

204

<dl>

205

206

<dd>Version 1 only</dd>

207

208

<dd>Version 2 only</dd>

209

210

<dd>Versions 1 and 2</dd>

211

212

<dd>Version 2, and hypothetical future versions identified by "4" and

213

"x"</dd>

214

215

<dd>Versions 1, 2, and hypothetical future versions identified by "4" and

216

"x"</dd>

217

218

<dd>Also version 1 only</dd>

219

220

<dd>A bizarre claim that Alice would like to start an OTR conversation,

221

but is unwilling to speak any version of the protocol</dd>

222

</dl>

223

These strings may be hidden from the user (for example, in

224

an attribute of an HTML tag), and/or may be accompanied by an

225

explanitory message ("Alice has requested an Off-the-Record private

226

conversation."). If Bob is willing to use OTR with Alice (with a

227

protocol version that Alice has offered), he should start the AKE.

228

<h4>Tagged plaintext messages</h4>

229

If Alice wishes to communicate to Bob that she is willing to use OTR,

230

she can attach a special whitespace tag to any plaintext message she

231

sends him. This tag may occur anywhere in the message, and may be

232

hidden from the user (as in the Query Messages, above).

233

The tag consists of the following 16 bytes, followed by one or more

234

sets of 8 bytes indicating the version of OTR Alice is willing to

235

use:

236

<ul>

237

<li>Always send "\x20\x09\x20\x20\x09\x09\x09\x09"

238

"\x20\x09\x20\x09\x20\x09\x20\x20", followed by one or more of:</li>

239

<li>"\x20\x09\x20\x09\x20\x20\x09\x20" to indicate a willingness to use

240

OTR version 1 with Bob (note: this string must come before all other

241

whitespace version tags, if it is present, for backwards

242

compatibility)</li>

243

<li>"\x20\x20\x09\x09\x20\x20\x09\x20" to indicate a willingness to use

244

OTR version 2 with Bob</li>

245

</ul>

246

If Bob is willing to use OTR with Alice (with a protocol version that

247

Alice has offered), he should start the AKE. On the other hand, if

248

Alice receives a plaintext message from Bob (rather than an initiation

249

of the AKE), she should stop sending him the whitespace tag.

250

<h4>OTR Error Messages</h4>

251

Any message containing the string "?OTR Error:" is an OTR Error

252

Message. The following part of the message should contain

253

human-readable details of the error.

254

<h3>Encoded messages</h3>

255

This section describes the byte-level format of the base-64 encoded

256

binary OTR messages. The binary form of each of the messages is

257

described below. To transmit one of these messages, construct the ASCII

258

string consisting of the five bytes "?OTR:", followed by the base-64

259

encoding of the binary form of the message, followed by the byte

260

".".

261

For the Diffie-Hellman group computations, the group is the one

262

defined in RFC 3526 with 1536-bit modulus (hex, big-endian):

263

264

FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1

265

29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD

266

EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245

267

E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED

268

EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D

269

C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F

270

83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D

271

670C354E 4ABC9804 F1746C08 CA237327 FFFFFFFF FFFFFFFF

272

</pre></blockquote>

273

and a generator (g) of 2. Note that this means that whenever you see a

274

Diffie-Hellman exponentiation in this document, it always means that the

275

exponentiation is done modulo the above 1536-bit number.

276

<h4>Data types</h4>

277

<dl>

278

<dt>Bytes (BYTE):</dt>

279

<dd> 1 byte unsigned value</dd>

280

<dt>Shorts (SHORT):</dt>

281

<dd> 2 byte unsigned value, big-endian</dd>

282

283

<dd> 4 byte unsigned value, big-endian</dd>

284

<dt>Multi-precision integers (MPI):</dt>

285

<dd> 4 byte unsigned len, big-endian

286

len byte unsigned value, big-endian

287

(MPIs must use the minimum-length encoding; i.e. no leading 0x00

288

bytes. This is important when calculating public key

289

fingerprints.)</dd>

290

<dt>Opaque variable-length data (DATA):</dt>

291

<dd> 4 byte unsigned len, big-endian

292

len byte data</dd>

293

<dt>Initial CTR-mode counter value (CTR):</dt>

294

<dd> 8 bytes data</dd>

295

<dt>Message Authentication Code (MAC):</dt>

296

<dd> 20 bytes MAC data</dd>

297

</dl>

298

<h4>Public keys, signatures, and fingerprints</h4>

299

OTR users have long-lived public keys that they use for

300

authentication (but not encryption). The current version of

301

the OTR protocol only supports DSA public keys, but there is a key type

302

marker for future extensibility.

303

<dl>

304

<dt>OTR public authentication DSA key (PUBKEY):</dt>

305

<dd>Pubkey type (SHORT)

306

<ul class="note"><li>DSA public keys have type 0x0000</li></ul>

307

p (MPI)

308

q (MPI)

309

g (MPI)

310

y (MPI)

311

<ul class="note"><li>(p,q,g,y) are the DSA public key parameters</li></ul>

312

</dd>

313

</dl>

314

OTR public keys are used to generate signatures; different

315

types of keys produce signatures in different formats. The format for a

316

signature made by a DSA public key is as follows:

317

<dl>

318

<dt>DSA signature (SIG):</dt>

319

<dd> (len is the length of the DSA public parameter q)

320

len byte unsigned r, big-endian

321

len byte unsigned s, big-endian</dd>

322

</dl>

323

OTR public keys have fingerprints, which are hex strings that

324

serve as identifiers for the public key. The fingerprint is calculated

325

by taking the SHA-1 hash of the byte-level representation of the public

326

key. However, there is an exception for backwards compatibility: if the

327

pubkey type is 0x0000, those two leading 0x00 bytes are omitted from the

328

data to be hashed. The encoding assures that, assuming the hash

329

function itself has no useful collisions, and DSA keys have length less

330

than 524281 bits (500 times larger than most DSA keys), no two public

331

keys will have the same fingerprint.

332

<h4>D-H Commit Message</h4>

333

This is the first message of the AKE. Bob sends it to Alice to

334

commit to a choice of D-H encryption key (but the key itself is not yet

335

revealed). This allows the secure session id to be much shorter than in

336

OTR version 1, while still preventing a man-in-the-middle attack on

337

it.

338

<dl>

339

<dt>Protocol version (SHORT)</dt>

340

<dd>The version number of this protocol is 0x0002.</dd>

341

<dt>Message type (BYTE)</dt>

342

<dd>The D-H Commit Message has type 0x02.</dd>

343

<dt>Encrypted gx (DATA)</dt>

344

<dd>Produce this field as follows:

345

<ul>

346

<li>Choose a random value r (128 bits)</li>

347

<li>Choose a random value x (at least 320 bits)</li>

348

<li>Serialize gx as an MPI, gxmpi. [gxmpi will probably be

349

196 bytes long, starting with "\x00\x00\x00\xc0".]</li>

350

<li>Encrypt gxmpi using AES128-CTR, with key r and initial counter value

351

0. The result will be the same length as gxmpi.</li>

352

<li>Encode this encrypted value as the DATA field.</li>

353

</ul></dd>

354

<dt>Hashed gx (DATA)</dt>

355

<dd>This is the SHA-256 hash of gxmpi.</dd>

356

</dl>

357

<h4>D-H Key Message</h4>

358

This is the second message of the AKE. Alice sends it to Bob, and it

359

simply consists of Alice's D-H encryption key.

360

<dl>

361

<dt>Protocol version (SHORT)</dt>

362

<dd>The version number of this protocol is 0x0002.</dd>

363

<dt>Message type (BYTE)</dt>

364

<dd>The D-H Key Message has type 0x0a.</dd>

365

366

<dd>Choose a random value y (at least 320 bits), and calculate

367

gy.</dd>

368

</dl>

369

<h4>Reveal Signature Message</h4>

370

This is the third message of the AKE. Bob sends it to Alice,

371

revealing his D-H encryption key (and thus opening an encrypted

372

channel), and also authenticating himself (and the parameters of the

373

channel, preventing a man-in-the-middle attack on the channel itself) to

374

Alice.

375

<dl>

376

<dt>Protocol version (SHORT)</dt>

377

<dd>The version number of this protocol is 0x0002.</dd>

378

<dt>Message type (BYTE)</dt>

379

<dd>The Reveal Signature Message has type 0x11.</dd>

380

<dt>Revealed key (DATA)</dt>

381

<dd>This is the value r picked earlier.</dd>

382

<dt>Encrypted signature (DATA)</dt>

383

<dd>This field is calculated as follows:

384

<ul>

385

<li>Compute the Diffie-Hellman shared secret s.</li>

386

<li>Use s to compute an AES key c and two MAC keys m1 and m2, as specified below.</li>

387

<li>Select keyidB, a serial number for the D-H key computed

388

earlier. It is an INT, and must be greater than 0.</li>

389

<li>Compute the 32-byte value MB to be the SHA256-HMAC of the

390

following data, using the key m1:<dl>

391

392

393

<dt>pubB (PUBKEY)</dt>

394

<dt>keyidB (INT)</dt>

395

</dl></li>

396

<li>Let XB be the following structure:<dl>

397

<dt>pubB (PUBKEY)</dt>

398

<dt>keyidB (INT)</dt>

399

400

<dd>This is the signature, using the private part of the key

401

pubB, of the 32-byte MB (which does not need to be

402

hashed again to produce the signature).</dd>

403

</dl></li>

404

<li>Encrypt XB using AES128-CTR with key c and initial

405

counter value 0.</li>

406

<li>Encode this encrypted value as the DATA field.</li>

407

</ul></dd>

408

<dt>MAC'd signature (MAC)</dt>

409

<dd>This is the SHA256-HMAC-160 (that is, the first 160 bits of the

410

SHA256-HMAC) of the encrypted signature field (including the four-byte

411

length), using the key m2.</dd>

412

</dl>

413

<h4>Signature Message</h4>

414

This is the final message of the AKE. Alice sends it to Bob,

415

authenticating herself and the channel parameters to him.

416

<dl>

417

<dt>Protocol version (SHORT)</dt>

418

<dd>The version number of this protocol is 0x0002.</dd>

419

<dt>Message type (BYTE)</dt>

420

<dd>The Signature Message has type 0x12.</dd>

421

<dt>Encrypted signature (DATA)</dt>

422

<dd>This field is calculated as follows:

423

<ul>

424

<li>Compute the Diffie-Hellman shared secret s.</li>

425

<li>Use s to compute an AES key c' and two MAC keys m1' and m2', as specified below.</li>

426

<li>Select keyidA, a serial number for the D-H key computed

427

earlier. It is an INT, and must be greater than 0.</li>

428

<li>Compute the 32-byte value MA to be the SHA256-HMAC of the

429

following data, using the key m1':<dl>

430

431

432

<dt>pubA (PUBKEY)</dt>

433

<dt>keyidA (INT)</dt>

434

</dl></li>

435

<li>Let XA be the following structure:<dl>

436

<dt>pubA (PUBKEY)</dt>

437

<dt>keyidA (INT)</dt>

438

439

<dd>This is the signature, using the private part of the key

440

pubA, of the 32-byte MA (which does not need to be

441

hashed again to produce the signature).</dd>

442

</dl></li>

443

<li>Encrypt XA using AES128-CTR with key c' and initial

444

counter value 0.</li>

445

<li>Encode this encrypted value as the DATA field.</li>

446

</ul></dd>

447

<dt>MAC'd signature (MAC)</dt>

448

<dd>This is the SHA256-HMAC-160 (that is, the first 160 bits of the

449

SHA256-HMAC) of the encrypted signature field (including the four-byte

450

length), using the key m2'.</dd>

451

</dl>

452

<h4>Data Message</h4>

453

This message is used to transmit a private message to the

454

correspondent. It is also used to reveal old MAC keys.

455

The plaintext message (either before encryption, or after decryption)

456

consists of a human-readable message (encoded in UTF-8, optionally with

457

HTML markup), optionally followed by:

458

<ul>

459

<li>a single NUL (a BYTE with value 0x00), and</li>

460

<li>zero or more TLV (type/length/value) records (with no padding

461

between them)</li>

462

</ul>

463

Each TLV record is of the form:

464

<dl>

465

<dt>Type (SHORT)</dt>

466

<dd>The type of this record. Records with unrecognized types should be

467

ignored.</dd>

468

<dt>Length (SHORT)</dt>

469

<dd>The length of the following field</dd>

470

<dt>Value (len BYTEs) [where len is the value of the Length field]</dt>

471

<dd>Any pertinent data for the record type.</dd>

472

</dl>

473

Some TLV examples:

474

<dl>

475

476

<dd>A TLV of type 1, containing no data</dd>

477

478

<dd>A TLV of type 0, containing the value "hello"</dd>

479

</dl>

480

The currently defined TLV record types are:

481

<dl>

482

<dt>Type 0: Padding</dt>

483

<dd>The value may be an arbitrary amount of data, which should be

484

ignored. This type can be used to disguise the length of the plaintext

485

message.</dd>

486

<dt>Type 1: Disconnected</dt>

487

<dd>If the user requests to close the private connection, you may send a

488

message (possibly with empty human-readable part) containing a record

489

with this TLV type just before you discard the session keys, and

490

transition to MSGSTATE_PLAINTEXT (see below). If you receive a TLV

491

record of this type, you should transition to MSGSTATE_FINISHED (see

492

below), and inform the user that his correspondent has closed his end of

493

the private connection, and the user should do the same.</dd>

494

</dl>

495

A message with an empty human-readable part (the plaintext is of zero

496

length, or starts with a NUL) is a "heartbeat" packet, and should not

497

be displayed to the user. (But it's still useful to effect key

498

rotations.)

499

Data Message format:

500

<dl>

501

<dt>Protocol version (SHORT)</dt>

502

<dd>The version number of this protocol is 0x0002.</dd>

503

<dt>Message type (BYTE)</dt>

504

<dd>The Data Message has type 0x03.</dd>

505

<dt>Flags (BYTE)</dt>

506

<dd>The bitwise-OR of the flags for this message. Usually you should

507

set this to 0x00. The only currently defined flag is:<dl>

508

<dt>IGNORE_UNREADABLE (0x01)</dt>

509

<dd>If you receive a Data Message with this flag set, and you are unable

510

to decrypt the message or verify the MAC (because, for example, you

511

don't have the right keys), just ignore the message instead of producing

512

some kind of error or notification to the user.</dd>

513

</dl></dd>

514

<dt>Sender keyid (INT)</dt>

515

<dd>Must be strictly greater than 0, and increment by 1 with each key

516

change</dd>

517

<dt>Recipient keyid (INT)</dt>

518

<dd>Must therefore be strictly greater than 0, as the receiver has no

519

key with id 0.

520

The sender and recipient keyids are those used to encrypt and MAC

521

this message.</dd>

522

523

<dd>The *next* [i.e. sender_keyid+1] public key for the sender</dd>

524

<dt>Top half of counter init (CTR)</dt>

525

<dd>This should monotonically increase (as a big-endian value) for

526

each message sent with the same (sender keyid, recipient keyid)

527

pair, and must not be all 0x00.</dd>

528

<dt>Encrypted message (DATA)</dt>

529

<dd>Using the appropriate encryption key (see below) derived from the

530

sender's and recipient's DH public keys (with the keyids given in

531

this message), perform AES128 counter-mode (CTR) encryption of the

532

message. The initial counter is a 16-byte value whose first 8

533

bytes are the above "top half of counter init" value, and whose

534

last 8 bytes are all 0x00. Note that counter mode does not change

535

the length of the message, so no message padding needs to be done.

536

If you *want* to do message padding (to disguise the length of

537

your message), use the above TLV of type 0.</dd>

538

<dt>Authenticator (MAC)</dt>

539

<dd>The SHA1-HMAC, using the appropriate MAC key (see below) of everything

540

from the Protocol version to the end of the encrypted message</dd>

541

<dt>Old MAC keys to be revealed (DATA)</dt>

542

<dd>See "Revealing MAC Keys", below.</dd>

543

</dl>

544

<h4>Key Management</h4>

545

For each correspondent, keep track of:

546

<dl>

547

<dt>Your two most recent DH public/private key pairs</dt>

548

<dd>our_dh[our_keyid] (most recent) and our_dh[our_keyid-1] (previous)</dd>

549

<dt>His two most recent DH public keys</dt>

550

<dd>their_y[their_keyid] (most recent) and their_y[their_keyid-1]

551

(previous)</dd>

552

</dl>

553

554

When starting a private conversation with a correspondent, generate

555

two DH key pairs for yourself, and set our_keyid = 2. Note that all DH

556

key pairs should have a private part that is at least 320 bits long.

557

558

559

<dt>When you send AKE messages:</dt>

560

<dd>Send the public part of our_dh[our_keyid-1], with the keyid field,

561

of course, set to (our_keyid-1).</dd>

562

563

<dt>Upon completing the AKE:</dt>

564

<dd>If the specified keyid equals either their_keyid or their_keyid-1,

565

and the DH pubkey contained in the AKE messages matches the

566

one you've stored for that keyid, that's great. Otherwise, forget

567

all values of their_y[], and of their_keyid, and set their_keyid to

568

the keyid value given in the AKE messages, and

569

their_y[their_keyid] to the DH pubkey value given in the AKE

570

messages. their_y[their_keyid-1] should be set to NULL.</dd>

571

572

<dt>When you send a Data Message:</dt>

573

<dd>Set the sender keyid to (our_keyid-1), and the recipient keyid to

574

(their_keyid). Set the DH pubkey in the Data message to the public

575

part of our_dh[our_keyid]. Use our_dh[our_keyid-1] and

576

their_y[their_keyid] to calculate session keys, as outlined below.

577

Use the "sending AES key" to encrypt the message, and the "sending

578

MAC key" to calculate its MAC.</dd>

579

580

<dt>When you receive a Data Message:</dt>

581

<dd>Use the keyids in the message to select which of your DH key pairs

582

and which of his DH pubkeys to use to verify the MAC. If the keyids

583

do not represent either the most recent key or the previous key (for

584

either the sender or receiver), reject the message. Also reject the

585

message if the sender keyid is their_keyid-1, but

586

their_y[their_keyid-1] is NULL.

587

588

Otherwise, calculate the session keys as outlined below. Use the

589

"receiving MAC key" to verify the MAC on the message. If it does not

590

verify, reject the message.

591

592

Check that the counter in the Data message is strictly larger than the

593

last counter you saw using this pair of keys. If not, reject the

594

message.

595

596

If the MAC verifies, decrypt the message using the "receiving AES

597

key".

598

599

Finally, check if keys need rotation:

600

<ul>

601

<li>If the "recipient keyid" in the Data message equals our_keyid, then

602

he's seen the public part of our most recent DH key pair, so you

603

must securely forget our_dh[our_keyid-1], increment our_keyid, and set

604

our_dh[our_keyid] to a new DH key pair which you generate.</li>

605

<li>If the "sender keyid" in the Data message equals their_keyid,

606

increment their_keyid, and set their_y[their_keyid] to the new DH

607

pubkey specified in the Data message.</li>

608

</ul></dd>

609

</dl>

610

611

<h4>Computing AES keys, MAC keys, and the secure session id</h4>

612

OTR uses Diffie-Hellman to calculate shared secrets in the usual way:

613

if Bob knows x, and tells Alice gx, and Alice knows y, and

614

tells Bob gy, then they each can calculate s =

615

gxy: Alice calculates (gx)y, and Bob

616

calculates (gy)x.

617

During the AKE, Alice and Bob each calculate s in this way, and then

618

they each compute seven values based on s:

619

<ul>

620

<li>A 64-bit secure session id, ssid</li>

621

<li>Two 128-bit AES encryption keys, c and c'</li>

622

623

</ul>

624

This is done in the following way:

625

<ul>

626

<li>Write the value of s as a minimum-length MPI, as specified above

627

(4-byte big-endian len, len-byte big-endian value). Let this

628

(4+len)-byte value be "secbytes".</li>

629

<li>For a given byte b, define h2(b) to be the 256-bit output of the

630

SHA256 hash of the (5+len) bytes consisting of the byte b, followed by

631

secbytes.</li>

632

<li>Let ssid be the first 64 bits of h2(0x00).</li>

633

<li>Let c be the first 128 bits of h2(0x01), and let c' be the second

634

128 bits of h2(0x01).</li>

635

636

637

638

639

</ul>

640

c, m1, and m2 are used to create and verify the Reveal Signature

641

Message; c', m1', and m2' are used to create and verify the Signature

642

message.

643

If the user requests to see the secure session id, it should be

644

displayed as two 32-bit bigendian unsigned values, in C "%08x" format.

645

If the user transmitted the Reveal Signature message during the AKE that

646

produced this ssid, then display the first 32 bits in bold, and the

647

second 32 bits in non-bold. If the user transmitted the Signature

648

message instead, display the first 32 bits in non-bold, and the

649

second 32 bits in bold. This session id can be used by the parties to

650

verify (say, over the telephone, assuming the parties recognize each

651

others' voices) that there is no man-in-the-middle by having each side

652

read his bold part to the other. [Note that this only needs to be done

653

in the event that the users do not trust that their long-term signature

654

keys have not been compromised.]

655

During the exchange of Data Messages, Alice and Bob use the keyids

656

listed in the Data Message to select Diffie-Hellman keys to use to

657

compute s, and the (4+len)-byte value of secbytes, as above.

658

From this, they calculate four values:

659

<ul>

660

<li>Two 128-bit AES encryption keys, the "sending AES key", and the

661

"receiving AES key"</li>

662

<li>Two 160-bit SHA1-HMAC keys, the "sending MAC key", and the

663

"receiving MAC key"</li>

664

</ul>

665

These keys are calculated as follows:

666

<ul>

667

<li>Alice (and similarly for Bob) determines if she is the "low" end

668

or the "high" end of this Data Message. If Alice's public key is

669

numerically greater than Bob's public key, then she

670

is the "high" end. Otherwise, she is the "low" end. Note that who is the

671

"low" end and who is the "high" end can change every time a new D-H

672

public key is exchanged in a Data Message.</li>

673

<li>She sets the values of "sendbyte" and "recvbyte" according to

674

whether she is the the "low" or the "high" end of the Data Message:

675

<ul>

676

<li>If she is the "high" end, she sets "sendbyte" to 0x01 and "recvbyte"

677

to 0x02.</li>

678

<li>If she is the "low" end, she sets "sendbyte" to 0x02 and "recvbyte"

679

to 0x01.</li>

680

</ul></li>

681

<li>For a given byte b, define h1(b) to be the 160-bit output of the

682

SHA-1 hash of the (5+len) bytes consisting of the byte b, followed by

683

secbytes.</li>

684

<li>The "sending AES key" is the first 16 bytes of h1(sendbyte).</li>

685

<li>The "sending MAC key" is the 20-byte SHA-1 hash of the 16-byte

686

sending AES key.</li>

687

<li>The "receiving AES key" is the first 16 bytes of h1(recvbyte).</li>

688

<li>The "receiving MAC key" is the 20-byte SHA-1 hash of the 16-byte

689

receiving AES key.</li>

690

</ul>

691

<h4>Revealing MAC keys</h4>

692

Whenever you are about to forget either one of your old D-H key pairs, or

693

one of your correspondent's old D-H public keys, take all of the MAC keys

694

that were generated by that key (note that there are up to four: the

695

sending and receiving MAC keys produced by the pairings of that key with

696

each of two of the other side's keys; but note that you only need to

697

take MAC keys that were actually used to either create a MAC on a

698

message, or verify a MAC on a message), and put them (as a set of

699

concatenated 20-byte values) into the "Old MAC keys to be revealed"

700

section of the next Data Message you send. This in done to allow the

701

forgeability of OTR transcripts: once the MAC keys are revealed, anyone

702

can modify an OTR message and still have it appear valid. But since we

703

don't reveal the MAC keys until their corresponding pubkeys are being

704

discarded, there is no danger of accepting a message as valid which

705

uses a MAC key which has already been revealed.

706

<h4>Fragmentation</h4>

707

Some networks may have a maximum message size that is too small to

708

contain an encoded OTR message. In that event, the sender may choose

709

to split the message into a number of fragments. This section

710

describes the format of the fragments. All OTR version 2 clients must

711

be able to assemble received fragments, but performing fragmentation on

712

outgoing messages is optional.

713

714

715

<dt>Transmitting Fragments</dt>

716

<dd>If you have information about the maximum size of message you are

717

able to send (the different IM networks have different limits), you

718

can fragment an encoded OTR message as follows:

719

<ul>

720

<li>Start with the OTR message as you would normally transmit it. For

721

example, a Data Message would start with "?OTR:AAED" and end

722

with ".".</li>

723

<li>Break it up into sufficiently small pieces. Let the number of

724

pieces be (n), and the pieces be

725

piece[1],piece[2],...,piece[n].</li>

726

<li>Transmit (n) messages with the following (printf-like) structure

727

(as k runs from 1 to n inclusive):

728

729

"?OTR,%hu,%hu,%s," , k , n , piece[k]</li>

730

731

<li>Note that k and n are unsigned short ints (2 bytes), and each has

732

a maximum value of 65535. Also, each piece[k] must be

733

non-empty.</li>

734

</ul></dd>

735

736

<dt>Receiving Fragments:</dt>

737

738

<dd>If you receive a message containing "?OTR," (note that you'll need

739

to check for this _before_ checking for any of the other "?OTR:"

740

markers):

741

742

<ul>

743

<li>Parse it as the printf statement above into k, n, and

744

piece.</li>

745

<li>Let (K,N) be your currently stored fragment number, and F be your

746

currently stored fragment. [If you have no currently stored

747

fragment, then K = N = 0 and F = "".]</li>

748

749

<li>If k == 0 or n == 0 or k > n, discard this (illegal)

750

fragment.</li>

751

752

<li>If k == 1:

753

<ul>

754

<li>Forget any stored fragment you may have</li>

755

<li>Store (piece) as F.</li>

756

<li>Store (k,n) as (K,N).</li>

757

</ul></li>

758

759

<li>If n == N and k == K+1:

760

<ul>

761

<li>Append (piece) to F.</li>

762

<li>Store (k,n) as (K,N).</li>

763

</ul></li>

764

765

<li>Otherwise:

766

<ul>

767

<li>Forget any stored fragment you may have</li>

768

<li>Store "" as F.</li>

769

<li>Store (0,0) as (K,N).</li>

770

</ul></li>

771

</ul>

772

773

After this, if N > 0 and K == N, treat F as the received

774

message.

775

776

If you receive a non-OTR message, or an unfragmented message,

777

forget any stored fragment you may have, store "" as F and store

778

(0,0) as (K,N).</dd>

779

</dl>

780

781

For example, here is a Data Message we would like to transmit over a

782

network with an unreasonably small maximum message size:

783

784

785

?OTR:AAEDAAAAAQAAAAEAAADAVf3Ei72ZgFeKqWvLMnuVPVCwxktsOZ1Qdje

786

Lp6jn62mCVtlY9nS6sRkecpjuLYHRxyTdRu2iEVtSsjZqK55ovZ35SfkOPHe

787

FYa9BIuxWi9djHMVKQ8KOVGAVLibjZ6P8LreDSKtWDv9YQjIEnkwFVGCPfpB

788

q2SX4VTQfJAQXHggR8izKxPvluXUdG9rIPh4cac98++VLdIuFMiEXjUIoTX2

789

rEzunaCLMy0VIfowlRsgsKGrwhCCv7hBWyglbzwz+AAAAAAAAAAQAAAF2SOr

790

JvPUerB9mtf4bqQDFthfoz/XepysnYuReHHEXKe+BFkaEoMNGiBl4TCLZx72

791

DvmZwKCewWRH1+W66ggrXKw2VdVl+vLsmzxNyWChGLfBTL5/3SUF09BfmCEl

792

03Ckk7htAgyAQcBf90RJznZndv7HwVAi3syupi0sQDdOKNPyObR5FRtqyqud

793

ttWmSdmGCGFcZ/fZqxQNsHB8QuYaBiGL7CDusES+wwfn8Q7BGtoJzOPDDx6K

794

yIyox/flPx2DZDJIZrMz9b0V70a9kqKLo/wcGhvHO6coCyMxenBAacLJ1DiI

795

NLKoYOoJTM7zcxsGnvCxaDZCvsmjx3j8Yc5r3i3ylllCQH2/lpr/xCvXFarG

796

tG7+wts+UqstS9SThLBQ9Ojq4oPsX7HBHKvq19XU3/ChIgWMy+bczc5gpkC/

797

eLAIGfJ0D5DJsl68vMXSmCoFK0HTwzzNa7lnZK4IutYPBNBCv0pWORQqDpsk

798

Ez96YOGyB8+gtpFgCrkuV1bSB9SRVmEBfDtKPQFhKowAAAAA=.

799

</pre></blockquote>

800

801

We could fragment this message into (for example) three

802

pieces:

803

804

805

?OTR,1,3,?OTR:AAEDAAAAAQAAAAEAAADAVf3Ei72ZgFeKqWvLMnuVPVCwxk

806

tsOZ1QdjeLp6jn62mCVtlY9nS6sRkecpjuLYHRxyTdRu2iEVtSsjZqK55ovZ

807

35SfkOPHeFYa9BIuxWi9djHMVKQ8KOVGAVLibjZ6P8LreDSKtWDv9YQjIEnk

808

wFVGCPfpBq2SX4VTQfJAQXHggR8izKxPvluXUdG9rIPh4cac98++VLdIuFMi

809

EXjUIoTX2rEzunaCLMy0VIfowlRsgsKGrwhCCv7hBWyglbzwz+AAAAAAAAAA

810

QAAAF2SOr,

811

</pre></blockquote>

812

813

814

?OTR,2,3,JvPUerB9mtf4bqQDFthfoz/XepysnYuReHHEXKe+BFkaEoMNGiB

815

l4TCLZx72DvmZwKCewWRH1+W66ggrXKw2VdVl+vLsmzxNyWChGLfBTL5/3SU

816

F09BfmCEl03Ckk7htAgyAQcBf90RJznZndv7HwVAi3syupi0sQDdOKNPyObR

817

5FRtqyqudttWmSdmGCGFcZ/fZqxQNsHB8QuYaBiGL7CDusES+wwfn8Q7BGto

818

JzOPDDx6KyIyox/flPx2DZDJIZrMz9b0V70a9kqKLo/wcGhvHO6coCyMxenB

819

AacLJ1DiI,

820

</pre></blockquote>

821

822

823

?OTR,3,3,NLKoYOoJTM7zcxsGnvCxaDZCvsmjx3j8Yc5r3i3ylllCQH2/lpr

824

/xCvXFarGtG7+wts+UqstS9SThLBQ9Ojq4oPsX7HBHKvq19XU3/ChIgWMy+b

825

czc5gpkC/eLAIGfJ0D5DJsl68vMXSmCoFK0HTwzzNa7lnZK4IutYPBNBCv0p

826

WORQqDpskEz96YOGyB8+gtpFgCrkuV1bSB9SRVmEBfDtKPQFhKowAAAAA=.,

827

</pre></blockquote>

828

<h3>The protocol state machine</h3>

829

An OTR client maintains separate state for every correspondent. For

830

example, Alice may have an active OTR conversation with Bob, while

831

having an unprotected conversation with Charlie. This state consists of

832

two main state variables, as well as some other information (such as

833

encryption keys). The two main state variables are:

834

<h4>Message state</h4>

835

The message state variable, msgstate, controls what happens to

836

outgoing messages typed by the user. It can take one of three

837

values:

838

<dl>

839

<dt>MSGSTATE_PLAINTEXT</dt>

840

<dd>This state indicates that outgoing messages are sent without

841

encryption. This is the state that is used before an OTR conversation

842

is initiated. This is the initial state, and the only way to

843

subsequently enter this state is for the user to explicitly request to

844

do so via some UI operation.</dd>

845

<dt>MSGSTATE_ENCRYPTED</dt>

846

<dd>This state indicates that outgoing messages are sent encrypted.

847

This is the state that is used during an OTR conversation. The only way

848

to enter this state is for the authentication state machine (below) to

849

successfully complete.</dd>

850

<dt>MSGSTATE_FINISHED</dt>

851

<dd>This state indicates that outgoing messages are not delivered at

852

all. This state is entered only when the other party indicates he has

853

terminated his side of the OTR conversation. For example, if Alice and

854

Bob are having an OTR conversation, and Bob instructs his OTR client to

855

end its private session with Alice (for example, by logging out), Alice

856

will be notified of this, and her client will switch to

857

MSGSTATE_FINISHED mode. This prevents Alice from accidentally sending a

858

message to Bob in plaintext. (Consider what happens if Alice was in the

859

middle of typing a private message to Bob when he suddenly logs out,

860

just as Alice hits Enter.)</dd>

861

</dl>

862

<h4>Authentication state</h4>

863

The authentication state variable, authstate, can take one of four

864

values (plus one extra for OTR version 1 compatibility):

865

<dl>

866

<dt>AUTHSTATE_NONE</dt>

867

<dd>This state indicates that the authentication protocol is not

868

currently in progress. This is the initial state.</dd>

869

<dt>AUTHSTATE_AWAITING_DHKEY</dt>

870

<dd>After Bob initiates the authentication protocol by sending Alice

871

the D-H Commit Message, he enters this state to await Alice's reply.</dd>

872

<dt>AUTHSTATE_AWAITING_REVEALSIG</dt>

873

<dd>After Alice receives Bob's D-H Commit Message, and replies with her

874

own D-H Key Message, she enters this state to await Bob's reply.</dd>

875

<dt>AUTHSTATE_AWAITING_SIG</dt>

876

<dd>After Bob receives Alice's D-H Key Message, and replies with his own

877

Reveal Signature Message, he enters this state to await Alice's reply.</dd>

878

<dt>AUTHSTATE_V1_SETUP</dt>

879

<dd>For OTR version 1 compatibility, if Bob sends a version 1 Key

880

Exchange Message to Alice, he enters this state to await Alice's

881

reply.</dd>

882

</dl>

883

After:

884

<ul>

885

<li>Alice (in AUTHSTATE_AWAITING_REVEALSIG) receives Bob's Reveal

886

Signature Message (and replies with her own Signature Message),</li>

887

<li>Alice (in AUTHSTATE_NONE) receives Bob's Version 1 Key Exchange

888

Message (and replies with her own Key Exchange Message),</li>

889

<li>Bob (in AUTHSTATE_AWAITING_SIG) receives Alice's Signature Message,

890

or</li>

891

<li>Bob (in AUTHSTATE_V1_SETUP) receives Alice's Version 1 Key Exchange

892

Message,</li>

893

</ul>

894

then,

895

assuming the signature verifications succeed, the msgstate

896

variable is transitioned to MSGSTATE_ENCRYPTED. Regardless of whether

897

the signature verifications succeed, the authstate variable is

898

transitioned to AUTHSTATE_NONE.

899

<h4>Policies</h4>

900

OTR clients can set different policies for different

901

correspondents. For example, Alice could set up her client so that it

902

speaks only OTR version 2, except with Charlie, who she knows has only

903

an old client; so that it will opportunistically start an OTR conversation

904

whenever it detects the correspondent supports it; or so that it refuses

905

to send non-encrypted messages to Bob, ever.

906

The policies that can be set (on a global or per-correspondent basis)

907

are any combination of the following boolean flags:

908

<dl>

909

<dt>ALLOW_V1</dt>

910

<dd>Allow version 1 of the OTR protocol to be used.</dd>

911

<dt>ALLOW_V2</dt>

912

<dd>Allow version 2 of the OTR protocol to be used.</dd>

913

<dt>REQUIRE_ENCRYPTION</dt>

914

<dd>Refuse to send unencrypted messages.</dd>

915

<dt>SEND_WHITESPACE_TAG</dt>

916

<dd>Advertise your support of OTR using the whitespace tag.</dd>

917

<dt>WHITESPACE_START_AKE</dt>

918

<dd>Start the OTR AKE when you receive a whitespace tag.</dd>

919

<dt>ERROR_START_AKE</dt>

920

<dd>Start the OTR AKE when you receive an OTR Error Message.</dd>

921

</dl>

922

The four old version 1 policies correspond to the following

923

combinations of flags (adding an allowance for version 2 of the

924

protocol):

925

<dl>

926

<dt>NEVER</dt>

927

<dd>No flags set</dd>

928

<dt>MANUAL</dt>

929

<dd>ALLOW_V1 | ALLOW_V2</dd>

930

<dt>OPPORTUNISTIC</dt>

931

<dd>ALLOW_V1 | ALLOW_V2 | SEND_WHITESPACE_TAG | WHITESPACE_START_AKE |

932

ERROR_START_AKE</dd>

933

<dt>ALWAYS</dt>

934

<dd>ALLOW_V1 | ALLOW_V2 | REQUIRE_ENCRYPTION | WHITESPACE_START_AKE |

935

ERROR_START_AKE</dd>

936

</dl>

937

Note that it is possible for UIs simply to offer the old

938

"combinations" of options, and not ask about each one separately.

939

<h4>State transitions</h4>

940

There are thirteen actions an OTR client must handle:

941

<ul>

942

<li>Received messages:

943

<ul>

944

<li>Plaintext without the whitespace tag</li>

945

<li>Plaintext with the whitespace tag</li>

946

<li>Query Message</li>

947

<li>Error Message</li>

948

<li>D-H Commit Message</li>

949

<li>D-H Key Message</li>

950

<li>Reveal Signature Message</li>

951

<li>Signature Message</li>

952

<li>Version 1 Key Exchange Message</li>

953

<li>Data Message</li>

954

</ul></li>

955

<li>User actions:

956

<ul>

957

<li>User requests to start an OTR conversation</li>

958

<li>User requests to end an OTR conversation</li>

959

<li>User types a message to be sent</li>

960

</ul></li>

961

</ul>

962

The following sections will outline what actions to take in each

963

case. They all assume that at least one of ALLOW_V1 or ALLOW_V2 is set;

964

if not, then OTR is completely disabled, and no special handling of

965

messages should be done at all.

966

<h4>Receiving plaintext without the whitespace tag</h4>

967

<dl>

968

<dt>If msgstate is MSGSTATE_PLAINTEXT:</dt>

969

<dd>Simply display the message to the user. If REQUIRE_ENCRYPTION is

970

set, warn him that the message was received unencrypted.</dd>

971

<dt>If msgstate is MSGSTATE_ENCRYPTED or MSGSTATE_FINISHED:</dt>

972

<dd>Display the message to the user, but warn him that the message was

973

received unencrypted.</dd>

974

</dl>

975

<h4>Receiving plaintext with the whitespace tag</h4>

976

<dl>

977

<dt>If msgstate is MSGSTATE_PLAINTEXT:</dt>

978

<dd>Remove the whitespace tag and display the message to the user. If

979

REQUIRE_ENCRYPTION is set, warn him that the message was received

980

unencrypted.</dd>

981

<dt>If msgstate is MSGSTATE_ENCRYPTED or MSGSTATE_FINISHED:</dt>

982

<dd>Remove the whitespace tag and display the message to the user, but

983

warn him that the message was received unencrypted.</dd>

984

</dl>

985

In any event, if WHITESPACE_START_AKE is set:

986

<dl>

987

<dt>If the tag offers OTR version 2 and ALLOW_V2 is set:</dt>

988

<dd>Send a D-H Commit Message, and transition authstate to

989

AUTHSTATE_AWAITING_DHKEY.</dd>

990

<dt>Otherwise, if the tag offers OTR version 1 and ALLOW_V1 is set:</dt>

991

<dd>Send a Version 1 Key Exchange Message, and transition authstate to

992

AUTHSTATE_V1_SETUP.</dd>

993

</dl>

994

<h4>Receiving a Query Message</h4>

995

<dl>

996

<dt>If the Query Message offers OTR version 2 and ALLOW_V2 is set:</dt>

997

<dd>Send a D-H Commit Message, and transition authstate to

998

AUTHSTATE_AWAITING_DHKEY.</dd>

999

<dt>Otherwise, if the message offers OTR version 1 and ALLOW_V1 is set:</dt>

1000

<dd>Send a Version 1 Key Exchange Message, and transition authstate to

1001

AUTHSTATE_V1_SETUP.</dd>

1002

</dl>

1003

<h4>Receiving an Error Message</h4>

1004

Display the message to the user. If ERROR_START_AKE is set, reply

1005

with a Query Message.

1006

<h4>User requests to start an OTR conversation</h4>

1007

Send an OTR Query Message to the correspondent.

1008

<h4>Receiving a D-H Commit Message</h4>

1009

If ALLOW_V2 is not set, ignore this message. Otherwise:

1010

<dl>

1011

<dt>If authstate is AUTHSTATE_NONE:</dt>

1012

<dd>Reply with a D-H Key Message, and transition authstate to

1013

AUTHSTATE_AWAITING_REVEALSIG.</dd>

1014

<dt>If authstate is AUTHSTATE_AWAITING_DHKEY:</dt>

1015

<dd>This is the trickiest transition in the whole protocol. It

1016

indicates that you have already sent a D-H Commit message to your

1017

correspondent, but that he either didn't receive it, or just didn't

1018

receive it yet, and has sent you one as well. The symmetry

1019

will be broken by comparing the hashed gx you sent in your

1020

D-H Commit Message with the one you received, considered as 32-byte

1021

unsigned big-endian values.

1022

<dl>

1023

<dt>If yours is the higher hash value:</dt>

1024

<dd>Ignore the incoming D-H Commit message, but resend your D-H

1025

Commit message.</dd>

1026

<dt>Otherwise:</dt>

1027

<dd>Forget your old gx value that you sent (encrypted)

1028

earlier, and pretend you're in AUTHSTATE_NONE; i.e. reply with a D-H Key

1029

Message, and transition authstate to AUTHSTATE_AWAITING_REVEALSIG.</dd>

1030

</dl></dd>

1031

<dt>If authstate is AUTHSTATE_AWAITING_REVEALSIG:</dt>

1032

<dd>Retransmit your D-H Key Message (the same

1033

one as you sent when you entered AUTHSTATE_AWAITING_REVEALSIG). Forget

1034

the old D-H Commit message, and use this new one instead. There

1035

are a number of reasons this might happen, including:

1036

<ul>

1037

<li>Your correspondent simply started a new AKE.</li>

1038

<li>Your correspondent resent his D-H Commit message, as specified

1039

above.</li>

1040

<li>On some networks, like AIM, if your correspondent is logged in

1041

multiple times, each of his clients will send a D-H Commit Message in

1042

response to a Query Message; resending the same D-H Key Message in

1043

response to each of those messages will prevent compounded confusion,

1044

since each of his clients will see each of the D-H Key Messages you

1045

send. [And the problem gets even worse if you are each logged

1046

in multiple times.]</li>

1047

</ul></dd>

1048

<dt>If authstate is AUTHSTATE_AWAITING_SIG or AUTHSTATE_V1_SETUP:</dt>

1049

<dd>Reply with a new D-H Key message, and transition authstate to

1050

AUTHSTATE_AWAITING_REVEALSIG.</dd>

1051

</dl>

1052

<h4>Receiving a D-H Key Message</h4>

1053

If ALLOW_V2 is not set, ignore this message. Otherwise:

1054

<dl>

1055

<dt>If authstate is AUTHSTATE_AWAITING_DHKEY:</dt>

1056

<dd>Reply with a Reveal Signature Message and transition authstate to

1057

AUTHSTATE_AWAITING_SIG.</dd>

1058

<dt>If authstate is AUTHSTATE_AWAITING_SIG:</dt>

1059

<dd>

1060

<dl>

1061

<dt>If this D-H Key message is the same the one you received earlier

1062

(when you entered AUTHSTATE_AWAITING_SIG):</dt>

1063

<dd>Retransmit your Reveal Signature Message.</dd>

1064

<dt>Otherwise:</dt>

1065

<dd>Ignore the message.</dd>

1066

</dl></dd>

1067

<dt>If authstate is AUTHSTATE_NONE, AUTHSTATE_AWAITING_REVEALSIG, or

1068

AUTHSTATE_V1_SETUP:</dt>

1069

<dd>Ignore the message.</dd>

1070

</dl>

1071

<h4>Receiving a Reveal Signature Message</h4>

1072

If ALLOW_V2 is not set, ignore this message. Otherwise:

1073

<dl>

1074

<dt>If authstate is AUTHSTATE_AWAITING_REVEALSIG:</dt>

1075

<dd>Use the received value of r to decrypt the value of gx

1076

received in the D-H Commit Message, and verify the hash therein.

1077

Decrypt the encrypted signature, and verify the signature and the MACs.

1078

If everything checks out:

1079

<ul>

1080

<li>Reply with a Signature Message.</li>

1081

<li>Transition authstate to AUTHSTATE_NONE.</li>

1082

<li>Transition msgstate to MSGSTATE_ENCRYPTED.</li>

1083

<li>If there is a recent stored message, encrypt it and send it as a

1084

Data Message.</li>

1085

</ul>

1086

Otherwise, ignore the message.</dd>

1087

<dt>If authstate is AUTHSTATE_NONE, AUTHSTATE_AWAITING_DHKEY,

1088

AUTHSTATE_AWAITING_SIG, or AUTHSTATE_V1_SETUP:</dt>

1089

<dd>Ignore the message.</dd>

1090

</dl>

1091

<h4>Receiving a Signature Message</h4>

1092

If ALLOW_V2 is not set, ignore this message. Otherwise:

1093

<dl>

1094

<dt>If authstate is AUTHSTATE_AWAITING_SIG:</dt>

1095

<dd>Decrypt the encrypted signature, and verify the signature and the MACs.

1096

If everything checks out:

1097

<ul>

1098

<li>Transition authstate to AUTHSTATE_NONE.</li>

1099

<li>Transition msgstate to MSGSTATE_ENCRYPTED.</li>

1100

<li>If there is a recent stored message, encrypt it and send it as a

1101

Data Message.</li>

1102

</ul>

1103

Otherwise, ignore the message.</dd>

1104

<dt>If authstate is AUTHSTATE_NONE, AUTHSTATE_AWAITING_DHKEY,

1105

AUTHSTATE_AWAITING_REVEALSIG, or AUTHSTATE_V1_SETUP:</dt>

1106

<dd>Ignore the message.</dd>

1107

</dl>

1108

<h4>Receiving a Version 1 Key Exchange Message</h4>

1109

If ALLOW_V1 is not set, ignore this message. Otherwise:

1110

<dl>

1111

<dt>If authstate is AUTHSTATE_NONE, AUTHSTATE_AWAITING_DHKEY,

1112

AUTHSTATE_AWAITING_REVEALSIG, or AUTHSTATE_AWAITING_SIG:</dt>

1113

<dd><dl><dt>If the reply field is not set to 0x01:</dt>

1114

<dd>Verify the information in the Key Exchange Message. If the

1115

verification succeeds:

1116

<ul>

1117

<li>Reply with a Key Exchange Message with the reply field set to

1118

0x01.</li>

1119

<li>Transition authstate to AUTHSTATE_NONE.</li>

1120

<li>Transition msgstate to MSGSTATE_ENCRYPTED.</li>

1121

<li>If there is a recent stored message, encrypt it and send it as a

1122

Data Message.</li>

1123

</ul>

1124

Otherwise, ignore the message.</dd>

1125

<dt>Otherwise, ignore the message.</dt></dl></dd>

1126

<dt>If authstate is AUTHSTATE_V1_SETUP:</dt>

1127

<dd>Verify the information in the Key Exchange Message. If the

1128

verification succeeds:

1129

<ul>

1130

<li>If the received Key Exchange Message did not have the reply field

1131

set to 0x01, reply with a Key Exchange Message with the reply field set

1132

to 0x01.</li>

1133

<li>Transition authstate to AUTHSTATE_NONE.</li>

1134

<li>Transition msgstate to MSGSTATE_ENCRYPTED.</li>

1135

<li>If there is a recent stored message, encrypt it and send it as a

1136

Data Message.</li>

1137

</ul>

1138

Otherwise, ignore the message.</dd>

1139

</dl>

1140

<h4>User types a message to be sent</h4>

1141

<dl>

1142

<dt>If msgstate is MSGSTATE_PLAINTEXT:</dt>

1143

<dd><dl><dt>If REQUIRE_ENCRYPTION is set:</dt>

1144

<dd>Store the plaintext message for possible retransmission, and send a

1145

Query Message.</dd>

1146

<dt>Otherwise:</dt>

1147

<dd>If SEND_WHITESPACE_TAG is set, and you have not received a plaintext

1148

message from this correspondent since last entering MSGSTATE_PLAINTEXT,

1149

attach the whitespace tag to the message. Send the (possibly modified)

1150

message as plaintext.</dd></dl></dd>

1151

<dt>If msgstate is MSGSTATE_ENCRYPTED:</dt>

1152

<dd>Encrypt the message, and send it as a Data Message. Store the

1153

plaintext message for possible retransmission.</dd>

1154

<dt>If msgstate is MSGSTATE_FINISHED:</dt>

1155

<dd>Inform the user that the message cannot be sent at this time. Store

1156

the plaintext message for possible retransmission.</dd>

1157

</dl>

1158

<h4>Receiving a Data Message</h4>

1159

<dl>

1160

<dt>If msgstate is MSGSTATE_ENCRYPTED:</dt>

1161

<dd>Verify the information (MAC, keyids, ctr value, etc.) in the

1162

message.

1163

<dl>

1164

<dt>If the verification succeeds:</dt>

1165

<dd>

1166

<ul>

1167

<li>Decrypt the message and display the human-readable part (if

1168

non-empty) to the user.</li>

1169

<li>Update the D-H encryption keys, if necessary.</li>

1170

<li>If you have not sent a message to this correspondent in some

1171

(configurable) time, send a "heartbeat" message, consisting of a Data

1172

Message encoding an empty plaintext. The heartbeat message should have

1173

the IGNORE_UNREADABLE flag set.</li>

1174

<li>If the received message contains a TLV type 1, forget all encryption

1175

keys for this correspondent, and transition msgstate to

1176

MSGSTATE_FINISHED.</li>

1177

</ul>

1178

</dd>

1179

<dt>Otherwise, inform the user that an unreadable encrypted message was

1180

received, and reply with an Error Message.</dt>

1181

</dl></dd>

1182

<dt>If msgstate is MSGSTATE_PLAINTEXT or MSGSTATE_FINISHED:</dt>

1183

<dd>Inform the user that an unreadable encrypted message was received,

1184

and reply with an Error Message.</dd>

1185

</dl>

1186

<h4>User requests to end an OTR conversation</h4>

1187

<dl>

1188

<dt>If msgstate is MSGSTATE_PLAINTEXT:</dt>

1189

<dd>Do nothing.</dd>

1190

<dt>If msgstate is MSGSTATE_ENCRYPTED:</dt>

1191

<dd>Send a Data Message, encoding a message with an empty human-readable

1192

part, and TLV type 1. Transition msgstate to MSGSTATE_PLAINTEXT.</dd>

1193

<dt>If msgstate is MSGSTATE_FINISHED:</dt>

1194

<dd>Transition msgstate to MSGSTATE_PLAINTEXT.</dd>

1195

</dl>

1196

</body></html>