« back to all changes in this revision
Viewing changes to Protocol
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Thibaut VARENE
- Date: 2006-01-02 19:52:18 UTC
- mfrom: (2.1.1 dapper)
- Revision ID: james.westby@ubuntu.com-20060102195218-wb8803196y9mycx6
Tags: 3.0.0-2
Fix typo: "malformed messahes" (Closes: #345400)
- files added:
- Protocol-v2.html
- files removed:
- Protocol
- files modified:
- ChangeLog
added
removed
Protocol
1
Off-The-Record Wire Protocol Documentation
2
------------------------------------------
3
4
Nikita Borisov and Ian Goldberg
5
<otr@cypherpunks.ca>
6
7
Definitions
8
-----------
9
10
Data encodings:
11
12
Bytes (BYTE):
13
1 byte unsigned value
14
Shorts (SHORT):
15
2 byte unsigned value, big-endian
16
Ints (INT):
17
4 byte unsigned value, big-endian
18
Multi-precision integers (MPI):
19
4 byte unsigned len, big-endian
20
len byte unsigned value, big-endian
21
(MPIs must use the minimum-length encoding; i.e. no leading 0x00
22
bytes. This is important when calculating public key fingerprints.)
23
Opaque variable-length data (DATA):
24
4 byte unsigned len, big-endian
25
len byte data
26
DSA signature (DSASIG):
27
(len is the length of the DSA public parameter q)
28
len byte unsigned r, big-endian
29
len byte unsigned s, big-endian
30
Initial CTR-mode counter value (CTR):
31
8 bytes data
32
Message Authentication Code (MAC):
33
20 bytes MAC data
34
35
Policies:
36
37
Clients can set one of four OTR policies. This can be done either
38
on a per-correspondent basis, or globally, or both. The policies
39
are:
40
41
NEVER:
42
Never perform OTR with this correspondent.
43
MANUAL:
44
Only start OTR if one of you specifically requests it.
45
OPPORTUNISTIC:
46
Start OTR if there's any indication the correspondent supports it.
47
ALWAYS:
48
Only use OTR with this correspondent; it is an error to send an
49
unencrypted message to him.
50
51
The default setting should be OPPORTUNISTIC.
52
53
Whitespace Tag:
54
55
There is an OTR_MESSAGE_TAG, which is a 24-byte string of whitespace
56
that clients can optionally append to (or insert in) messages to
57
unobtrusively indicate that they understand the OTR protocol. The
58
string is as follows (in C notation):
59
60
\x20\x09\x20\x20\x09\x09\x09\x09
61
\x20\x09\x20\x09\x20\x09\x20\x20
62
\x20\x09\x20\x09\x20\x20\x09\x20
63
64
[This is the bit pattern of the string "OTR" as expressed in spaces and
65
tabs.]
66
67
Protocol
68
--------
69
70
An OTR client maintains a separate state with each of its
71
correspondents. Initially, all correspondents start in the UNCONNECTED
72
state.
73
74
This is the state machine for the default (OPPORTUNISTIC) policy. The
75
modifications for other policies are below.
76
77
In the UNCONNECTED state:
78
79
- It may, at the user's instigation or otherwise (for example, if the
80
correspondent's AIM Capability list indicates he supports OTR), send
81
an OTR Query message, and remain in the UNCONNECTED state.
82
83
- If it receives an OTR Query message, it replies with an OTR Key
84
Exchange message, and moves to the SETUP state.
85
86
- If it receives an OTR Key Exchange message, it:
87
- verifies the information in the Key Exchange message
88
- If the verification fails, send an OTR Error message, and remain
89
in the UNCONNECTED state.
90
- If the verification succeeds, reply with an OTR Key Exchange
91
message with the Reply field set to 0x01 (_even if_ the received
92
Key Exchange message itself had the Reply field set), inform the
93
user that private communication has been established, and move to
94
the CONNECTED state.
95
96
- If it receives an OTR Data message, it replies with an OTR Error
97
message, sends a Key Exchange message (with Reply set to 0x00), and
98
moves to the SETUP state.
99
100
- If it receives an OTR Error message, it should display the message to
101
the user, send a Key Exchange message (with Reply set to 0x00), and
102
move to the SETUP state.
103
104
- If it receives an non-OTR message:
105
- If the message contains the OTR_MESSAGE_TAG, it should reply with
106
an OTR Key Exchange message, strip the OTR_MESSAGE_TAG from the
107
message, display the message to the user, and move to the SETUP state.
108
- Otherwise, it should display the message to the user, and remain in
109
the UNCONNECTED state.
110
111
In the SETUP state:
112
113
- The user, through a UI action, may elect to reset the connection
114
to the UNCONNECTED state.
115
116
- If it receives an OTR Query message, it replies with an OTR Key
117
Exchange message, and remains in the SETUP state.
118
119
- If it receives an OTR Key Exchange message, it:
120
- verifies the information in the Key Exchange message
121
- If the verification fails, send an OTR Error message, display a
122
notice of the error to the user, and remain in the SETUP state.
123
- If the verification succeeds:
124
- If the received Key Exchange message did not have the Reply field
125
set to 0x01, reply with an OTR Key Exchange (with the Reply field
126
set to 0x01).
127
- In any event, inform the user that private communication has
128
been established, and move to the CONNECTED state.
129
130
- If it receives an OTR Data message, it replies with an OTR Error
131
message, sends a Key Exchange message (with Reply set to 0x00), and
132
remains in the SETUP state.
133
134
- If it receives an OTR Error message, it should display the message to
135
the user, send a Key Exchange message (with Reply set to 0x00), and
136
remain in the SETUP state.
137
138
- If it receives an non-OTR message:
139
- If the message contains the OTR_MESSAGE_TAG, it should reply with
140
an OTR Key Exchange message, and strip the OTR_MESSAGE_TAG from the
141
message, display the message to the user, and remain to the SETUP state.
142
- Otherwise, it should display the message to the user, and remain
143
in the SETUP state.
144
145
In the CONNECTED state:
146
147
- The user, through a UI action, may elect to reset the connection
148
to the UNCONNECTED state.
149
150
- If it receives an OTR Query message, it replies with an OTR Key
151
Exchange message, and remains in the CONNECTED state.
152
153
- If it receives an OTR Key Exchange message, it:
154
- verifies the information in the Key Exchange message
155
- If the verification fails, send an OTR Error message, display a
156
notice of the error to the user, and remain in the CONNECTED
157
state.
158
- If the verification succeeds:
159
- If the received Key Exchange message did not have the Reply field
160
set to 0x01, reply with an OTR Key Exchange (with the Reply field
161
set to 0x01).
162
- In any event, remain in the CONNECTED state.
163
164
- If it receives an OTR Data message, it:
165
- verifies the information in the Data message
166
- If the verification fails, send an OTR Error message, display a
167
notice of the error to the user, and remain in the CONNECTED
168
state.
169
- If the verification succeeds, display the (decrypted) message to
170
the user, and remain in the CONNECTED state.
171
172
- If it receives an OTR Error message, it should display the message to
173
the user, and remain in the CONNECTED state.
174
175
- If it receives an non-OTR message, it should reply with an OTR Error
176
message, and remain in the CONNECTED state.
177
178
Other policies:
179
180
The above decribes what to do in the default (OPPORTUNISTIC) policy.
181
182
If the policy is NEVER: behave as if OTR is not enabled at all.
183
Pass all received messages to the user, and send all of the user's
184
messages out untouched.
185
186
If the policy is MANUAL: never send the OTR_MESSAGE_TAG in messages,
187
and never respond to one you receive. Don't send a Key Exchange
188
Message (or change state) in response to receiving a Data or Error
189
Message in the UNCONNECTED or SETUP states.
190
191
If the policy is ALWAYS: never send an unencrypted message. Either
192
report an error to the user, or else hold on to the message, send an
193
OTR Query Message instead, and once you enter the CONNECTED state,
194
send the original message. Warn the user if you receive an
195
unencrypted message.
196
197
Protocol messages
198
-----------------
199
200
There are four types of messages in the OTR protocol:
201
- OTR Query
202
- OTR Key Exchange
203
- OTR Data
204
- OTR Error
205
206
OTR Query
207
---------
208
209
This message is sent to inquire if the correspondent supports the OTR
210
protocol.
211
212
Format:
213
214
Any message containing the string "?OTR?" is considered an OTR Query.
215
216
Since this message will be visible to the correspondent in the event
217
that he does not support the OTR protocol, it may also contain
218
human-readable information after this initial string.
219
220
Example:
221
222
?OTR?\nYour client does not support the OTR Private Messaging
223
Protocol.\nSee http://www.cypherpunks.ca/otr/ for more information.
224
225
OTR Key Exchange
226
----------------
227
228
This message is sent to inform the correspondent of your public
229
signature key, and your current DH encryption key.
230
231
Format:
232
233
The message must contain the five bytes "?OTR:". After that is the
234
base-64 encoding of the following, followed by the byte ".":
235
236
- Protocol version (SHORT)
237
- The version number of this protocol is 0x0001.
238
- Message type (BYTE)
239
- OTR Key Exchange has message type 0x0a.
240
- Reply (BYTE)
241
- 0x01 if this Key Exchange message is being sent in reply to a Key
242
Exchange message that was just received. 0x00 otherwise.
243
- DSA p (MPI)
244
- DSA q (MPI)
245
- DSA g (MPI)
246
- DSA e (MPI)
247
- The DSA public key (p,q,g,e).
248
[The parameter 'e' is usually called 'y', but that name's taken by
249
the DH public key, below.]
250
- Sender keyid (INT)
251
- The keyid for this initial key. Must be greater than 0.
252
- DH y (MPI)
253
- The initial DH public encryption key. The DH group is the one
254
defined in RFC 3526 with 1536-bit modulus (hex, big-endian):
255
FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1
256
29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD
257
EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245
258
E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED
259
EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE45B3D
260
C2007CB8 A163BF05 98DA4836 1C55D39A 69163FA8 FD24CF5F
261
83655D23 DCA3AD96 1C62F356 208552BB 9ED52907 7096966D
262
670C354E 4ABC9804 F1746C08 CA237327 FFFFFFFF FFFFFFFF
263
and generator 2.
264
- Signature (DSASIG)
265
- A signature with the private DSA key corresponding to (p,q,g,e).
266
Take a SHA-1 hash of everything from the protocol version to the
267
end of the value of y, and sign that value.
268
269
The DSA key given in this message has a "Fingerprint", which is the
270
SHA-1 hash of the portion of the message from the beginning of the "p"
271
field (including the MPI length) to the end of the "e" field. This
272
fingerprint should be displayed to the recipient so that he may verify
273
the sender's key.
274
275
OTR Data
276
--------
277
278
This message is used to transmit a private message to the correspondent.
279
It is also used to reveal old MAC keys.
280
281
The plaintext message (either before encryption, or after decryption)
282
consists of a human-readable message, optionally followed by:
283
- a single NUL (a BYTE with value 0x00)
284
AND
285
- zero or more TLV (type/length/value) records (with no padding
286
between them)
287
288
Each TLV record is of the form:
289
- Type (SHORT)
290
- The type of this record. Records with unrecognized types should
291
be ignored.
292
- Length (SHORT)
293
- The length of the following field
294
- Value (len BYTEs) [where len is the value of the Length field]
295
- Any pertinent data for the record type.
296
297
Some TLV examples:
298
299
\x00\x01\x00\x00
300
A TLV of type 1, containing no data
301
302
\x00\x00\x00\x05\x68\x65\x6c\x6c\x6f
303
A TLV of type 0, containing the value "hello"
304
305
The currently defined TLV record types are:
306
307
Type 0: Padding
308
The value may be an arbitrary amount of data, which should be
309
ignored. This type can be used to disguise the length of the
310
plaintext message.
311
312
Type 1: Disconnected
313
If the user requests to close the private connection, you may
314
send a message (possibly with empty human-readable part)
315
containing a record with this TLV type just before you discard
316
the session keys. If you receive a TLV record of this type,
317
you may inform the user that his correspondent has closed his
318
end of the private connection, and the user should do the same.
319
320
Format:
321
322
The message must contain the five bytes "?OTR:". After that is the
323
base-64 encoding of the following, followed by the byte ".":
324
325
- Protocol version (SHORT)
326
- The version number of this protocol is 0x0001.
327
- Message type (BYTE)
328
- OTR Data has message type 0x03.
329
- Sender keyid (INT)
330
- Must be strictly greater than 0, and increment by 1 with each key
331
change
332
- Recipient keyid (INT)
333
- Must therefore be strictly greater than 0, as the receiver has no
334
key with id 0
335
- The sender and recipient keyids are those used to encrypt and MAC
336
this message.
337
- DH y (MPI)
338
- The *next* [i.e. sender_keyid+1] public key for the sender
339
- Top half of counter init (CTR)
340
- This should monotonically increase (as a big-endian value) for
341
each message sent with the same (sender keyid, recipient keyid)
342
pair , and must not be all 0x00.
343
- Encrypted message (DATA)
344
- Using the appropriate encryption key (see below) derived from the
345
sender's and recipient's DH public keys (with the keyids given in
346
this message), perform AES128 counter-mode (CTR) encryption of the
347
message. The initial counter is a 16-byte value whose first 8
348
bytes are the above "top half of counter init" value, and whose
349
last 8 bytes are all 0x00. Note that counter mode does not change
350
the length of the message, so no message padding needs to be done.
351
If you *want* to do message padding (to disguise the length of
352
your message), pad with NULs (bytes of 0x00). Upon receiving
353
and successfully decrypting an OTR Data Message, the decrypted
354
payload should be truncated just before the first NUL (if any).
355
- SHA1-HMAC, using the appropriate MAC key (see below) of everything
356
from the Protocol version to the end of the encrypted message (MAC)
357
- Old MAC keys to be revealed (DATA)
358
- See "Revealing MAC Keys", below.
359
360
OTR Error
361
---------
362
363
This message is sent when a problem has occurred in the protocol.
364
365
Format:
366
367
Any message containing "?OTR Error:" is an OTR Error message. The
368
following part of the message should contain human-readable details of
369
the error.
370
371
Key Management
372
--------------
373
374
For each correspondent, keep track of:
375
- My two most recent DH public/private key pairs
376
- our_dh[our_keyid] (most recent) and our_dh[our_keyid-1] (previous)
377
- His two most recent DH public keys
378
- their_y[their_keyid] (most recent) and their_y[their_keyid-1] (previous)
379
380
When starting a private conversation with a correspondent, generate
381
two DH key pairs for yourself, and set our_keyid = 2. Note that all DH
382
key pairs should have a private part that is at least 320 bits long.
383
384
When you send an OTR Key Exchange message:
385
Send the public part of our_dh[our_keyid-1], with the keyid field,
386
of course, set to (our_keyid-1).
387
388
When you receive an OTR Key Exchange message:
389
If the specified keyid equals either their_keyid or their_keyid-1,
390
and the DH pubkey contained in the Key Exchange message matches the
391
one we've stored for that keyid, that's great. Otherwise, forget
392
all values of their_y[], and of their_keyid, and set their_keyid to
393
the keyid value given in the Key Exchange message, and
394
their_y[their_keyid] to the DH pubkey value given in the Key
395
Exchange message. their_y[their_keyid-1] should be set to NULL.
396
397
In any event, if the Reply field of the Key Exchange message was set
398
to 0x00, send a Key Exchange message with the Reply field set to
399
0x01.
400
401
When you send an OTR Data message:
402
Set the sender keyid to (our_keyid-1), and the recipient keyid to
403
(their_keyid). Set the DH pubkey in the Data message to the public
404
part of our_dh[our_keyid]. Use our_dh[our_keyid-1] and
405
their_y[their_keyid] to calculate session keys, as outlined below.
406
Use the "sending AES key" to encrypt the message, and the "sending
407
MAC key" to calculate its MAC.
408
409
When you receive an OTR Data message:
410
Use the keyids in the message to select which of your DH key pairs
411
and which of his DH pubkeys to use to verify the MAC. If the keyids
412
do not represent either the most recent key or the previous key (for
413
either the sender or receiver), reject the message. Also reject the
414
message if the sender keyid is their_keyid-1, but
415
their_y[their_keyid-1] is NULL.
416
417
Otherwise, calculate the session keys as outlined below. Use the
418
"receiving MAC key" to verify the MAC on the message. If it does not
419
verify, reject the message.
420
421
Check that the counter in the Data message is strictly larger than the
422
last counter we saw using this pair of keys. If not, reject the
423
message.
424
425
If the MAC verifies, decrypt the message using the "receiving AES key".
426
427
Finally, check if keys need rotation:
428
- If the "recipient keyid" in the Data message equals our_keyid, then
429
he's seen the public part of our most recent DH key pair, so we
430
securely forget our_dh[our_keyid-1], increment our_keyid, and set
431
our_dh[our_keyid] to a new DH key pair which we generate.
432
- If the "sender keyid" in the Data message equals their_keyid,
433
increment their_keyid, and set their_y[their_keyid] to the new DH
434
pubkey specified in the Data message.
435
436
If the message you get after decryption is of zero length, this is a
437
"heartbeat" packet. Don't display it to the user. (But it's still
438
useful to effect key rotations.)
439
440
Calculating session keys:
441
Given one of our DH key pairs, and one of his DH pubkeys, we
442
calculate a session id, two AES keys, and two MAC keys as follows:
443
444
Let (our_x, our_y) be the private and public parts of our DH
445
key pair. Let their_y be his DH pubkey.
446
447
First, calculate the shared secret:
448
secret = their_y ^ our_x mod DH_MODULUS
449
(^ denotes exponentiation, and DH_MODULUS is the 1536-bit DH modulus
450
from RFC 3526, as specified above).
451
452
Write the value of secret as a minimum-length MPI, as specific above
453
(4-byte big-endian len, len-byte big-endian value). Let this
454
(4+len)-byte value be "secbytes".
455
456
Next, determine if we are the "low" end or the "high" end of this
457
key exchange. If our_y > their_y, then we are the "high" end.
458
Otherwise, we are the "low" end. Note that who is the "low" end and
459
who is the "high" end can change every time a new DH pubkey is
460
exchanged.
461
462
Calculate the session id as the SHA-1 hash of the (5+len)-byte value
463
composed of the byte 0x00, followed by the (4+len) bytes of
464
secbytes. When a new private connection is established, display
465
these 8 bytes to the user as two 4-byte (big-endian) values, in C
466
"%08x" format. If we are the "low" end of the key exchange, display
467
the first 10 bytes in bold, and the second 10 bytes in non-bold. If
468
we are the "high" end of the key exchange, display the first 10 bytes
469
in non-bold, and the second 10 bytes in bold. This session id can be
470
used by the parties to verify (say, over the telephone, assuming the
471
parties recognize each others' voices) that there is no
472
man-in-the-middle by having each side read his bold part to the
473
other.
474
475
Now set the values of "sendbyte" and "recvbyte" according to whether
476
we are the "low" or the "high" end of the key exchange:
477
- If we are the "high" end, set "sendbyte" to 0x01 and "recvbyte"
478
to 0x02.
479
- If we are the "low" end, set "sendbyte" to 0x02 and "recvbyte"
480
to 0x01.
481
482
Calculate the "sending AES key" to be the first 16 bytes of the
483
SHA-1 hash of the (5+len)-byte value composed of the byte
484
(sendbyte), followed by the (4+len) bytes of secbytes.
485
486
Calculate the "sending MAC key" to be all 20 bytes of the SHA-1 hash
487
of the 16-byte sending AES key.
488
489
Calculate the "receiving AES key" to be the first 16 bytes of the
490
SHA-1 hash of the (5+len)-byte value composed of the byte
491
(recvbyte), followed by the (4+len) bytes of secbytes.
492
493
Calculate the "receiving MAC key" to be all 20 bytes of the SHA-1 hash
494
of the 16-byte receiving AES key.
495
496
Revealing MAC keys
497
------------------
498
499
Whenever you are about to forget either one of your old DH key pairs, or
500
one of your correspondent's old DH pubkeys, take all of the MAC keys
501
that were generated by that key (note that there are up to four: the
502
sending and receiving MAC keys produced by the pairings of that key with
503
each of two of the other side's keys; but note that you only need to
504
take MAC keys that were actually used to either create a MAC on a
505
message, or verify a MAC on a message), and put them (as a set of
506
concatenated 20-byte values) into the "Old MAC keys to be revealed"
507
section of the next Data message you send. We do this to allow the
508
forgeability of OTR transcripts: once the MAC keys are revealed, anyone
509
can modify an OTR message and still have it appear valid. But since we
510
don't reveal the MAC keys until their corresponding pubkeys are being
511
discarded, there is no danger of us accepting a message as valid which
512
uses a MAC key which has already been revealed.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1