Debian Codegraph @

README

raw
1 Off-the-Record Messaging Library and Toolkit
2 v4.1.1, 9 Mar 2016
3
4 This is a library and toolkit which implements Off-the-Record (OTR) Messaging.
5
6 OTR allows you to have private conversations over IM by providing:
7 - Encryption
8 - No one else can read your instant messages.
9 - Authentication
10 - You are assured the correspondent is who you think it is.
11 - Deniability
12 - The messages you send do _not_ have digital signatures that are
13 checkable by a third party. Anyone can forge messages after a
14 conversation to make them look like they came from you. However,
15 _during_ a conversation, your correspondent is assured the messages
16 he sees are authentic and unmodified.
17 - Perfect forward secrecy
18 - If you lose control of your private keys, no previous conversation
19 is compromised.
20
21 For more information on Off-the-Record Messaging, see
22 https://otr.cypherpunks.ca/
23
24 LIBRARY USAGE
25
26 1. Initialization
27
28 Before you call any other libotr routine, you need to initialize the
29 library. The easiest way to do that is to include proto.h, and use the
30 macro:
31
32 OTRL_INIT;
33
34 somewhere early in your program. This should be called only once.
35
36 You will also need an OtrlUserState. An OtrlUserState encapsulates the
37 list of known fingerprints and the list of private keys, so it should be
38 "one per user". Many OTR-enabled programs (such as IM clients) only have a
39 single user, so for them, you can just create a single one, and use it
40 throughout. Create an OtrlUserState as follows:
41
42 userstate = otrl_userstate_create();
43
44 If you need to free an OtrlUserState:
45
46 otrl_userstate_free(userstate);
47
48 To read stored private keys:
49
50 otrl_privkey_read(userstate, privkeyfilename);
51
52 To read stored instance tags:
53
54 otrl_instag_read(userstate, instagfilename);
55
56 To read stored fingerprints:
57
58 otrl_privkey_read_fingerprints(userstate, fingerprintfilename,
59 add_app_info, add_app_info_data);
60
61 add_app_info is a function that will be called in the event that a new
62 ConnContext is created. It will be passed the add_app_info_data that
63 you supplied, as well as a pointer to the new ConnContext. You can use
64 this to add application-specific information to the ConnContext using
65 the "context->app" field, for example. If you don't need to do this,
66 you can pass NULL for the last two arguments of
67 otrl_privkey_read_fingerprints.
68
69 2. Setting up the UI functions
70
71 You need to let the library know how to do any UI it might require
72 (error messages, confirming new fingerprints, etc.). To this end, you
73 need to define a number of UI functions, and collect them in a
74 OtrlMessageAppOps struct.
75
76 The first parameter of every UI function is "void *opdata". This is a
77 pointer you pass to the library, and it will pass back (opaquely) to the
78 UI functions when it calls them. You can use this to keep track of
79 state or any other information.
80
81 You will need to include proto.h and message.h, and you can find a list
82 of the UI functions in message.h.
83
84 3. Sending messages
85
86 When you have a message you're about to send, you'll need to know four
87 things: you account name, the protocol id, the name of the recipient,
88 their instance tag, and the message.
89
90 OTR protocol version 3 introduces the notion of "instance tags." A
91 client may be logged into the same account multiple times from different
92 locations. An instance tag is intended to differentiate these clients.
93 When sending a message, you may also specify a particular instance tag,
94 or use meta instance tags like OTRL_INSTAG_MOST_SECURE.
95
96 The protocol id is just a unique string that is used to distinguish
97 the user foo on AIM from the user foo on MSN, etc. It can be anything
98 you like, so long as you're consistent, but if you've got nothing better
99 to use, you may as well use the ids from gaim. (Programs that use the
100 same protocol ids can share fingerprint and private key files.) The
101 gaim protocol id for AIM/ICQ is "prpl-oscar".
102
103 Note that a name does not uniquely identify a user (as shown by the
104 "foo" example above). Even if you know both the name and the protocol,
105 it may not identify the user, since there may be multiple "foo" users on
106 IRC, on different servers. But the *three* items (your account name,
107 protocol id, their name) _must_ uniquely identify a user, so your
108 account name needs to include any network identifier, such as a server
109 name. Examples would be "[email protected]" or "[email protected]".
110 Protocols such as AIM that do not have separate networks can just use
111 "foo", of course.
112
113 To encrypt the message (if necessary; the library keeps track of which
114 users you have secure connections to, so you should *always* call this
115 next function), simply do this:
116
117 gcry_error_t err;
118 char *newmessage = NULL;
119
120 err = otrl_message_sending(userstate, &ui_ops, opdata, accountname,
121 protocolid, recipient_name, instag, message, tlvs,
122 &newmessage, fragPolicy, contextp, add_app_info,
123 add_app_info_data);
124
125 add_app_info and add_app_info_data are as above, and may be NULL.
126
127 tlvs should usually be NULL. If it's not, then it points to a chain of
128 OtrlTLVs which represent machine-readable data to send along with this
129 message.
130
131 If contextp is not NULL, it will be set to the context that was used
132 for sending the message.
133
134 If err is non-zero, then the library tried to encrypt the message,
135 but for some reason failed. DO NOT send the message in the clear in
136 that case.
137
138 If newmessage gets set by the call to something non-NULL, then you
139 should replace your message with the contents of newmessage, and
140 send that instead.
141
142 Once the message is encrypted, it may still be too large to send over
143 the network in a single piece. To check the maximum message size and
144 break your message into fragments if necessary, do this:
145
146 gcry_error_t err;
147 char *extrafragment = NULL;
148
149 err = otrl_message_fragment_and_send(&ui_ops, opdata, context,
150 message, fragmentPolicy, extrafragment);
151
152 fragmentPolicy determines which, if any, fragments to return instead
153 of sending them immediately. For example, you may wish to send all
154 fragments except the last one, which is handled differently. Valid
155 policies may be found in proto.h.
156
157 If err returns a nonzero value from fragment_and_send, the application
158 tried to break your message into fragments but failed for some reason.
159 You may still attempt to send the original message, but it might be
160 rejected if it too large.
161
162 When you're done with newmessage, you must call
163
164 otrl_message_free(newmessage)
165
166 4. Receiving messages
167
168 Receiving messages is similarly straightforward. Again, you need to
169 know four things: your account name, the protocol id, the sender's name,
170 and the message.
171
172 int ignore_message;
173 char *newmessage = NULL;
174
175 ignore_message = otrl_message_receiving(userstate, &ui_ops, opdata,
176 accountname, protocolid, sender_name, message, &newmessage,
177 &tlvs, contextp, add_app_info, add_app_info_data);
178
179 add_app_info and add_app_info_data are as above, and may be NULL.
180
181 If contextp is not NULL, it will be set to the context that was used
182 for receiving the message.
183
184 If otrl_message_receiving returns 1, then the message you received was
185 an internal protocol message, and no message should be delivered to the
186 user.
187
188 If it returns 0, then check if newmessage was set to non-NULL. If so,
189 replace the received message with the contents of newmessage, and
190 deliver that to the user instead. You must call
191 otrl_message_free(newmessage) when you're done with it.
192
193 If otrl_message_receiving returns 0 and newmessage is NULL, then this
194 was an ordinary, non-OTR message, which should just be delivered to the
195 user without modification.
196
197 If tlvs is set to non-NULL, then there is machine-readable data that was
198 sent along with this message. Call otrl_tlv_free(tlvs) when you're done
199 dealing with it (or ignoring it).
200
201 5. Socialist Millionaires' Protocol
202
203 The Socialist Millionaires' Protocol (SMP) is a way to detect
204 eavesdropping and man-in-the-middle attacks without requiring users to
205 work with fingerprints. This feature was added to OTR starting in
206 version 3.1.0. To learn how to modify your application to use SMP, read
207 the UPGRADING file.
208
209 TOOLKIT
210
211 Along with the library, this package comes with the OTR Messaging
212 Toolkit. This toolkit is useful for analyzing and/or forging OTR
213 messages. Why do we offer this? Primarily, to make absolutely sure
214 that transcripts of OTR conversations are really easy to forge after the
215 fact. [Note that *during* an OTR conversation, messages can't be forged
216 without real-time access to the secret keys on the participants'
217 computers, and in that case, all security has already been lost.]
218 Easily forgeable transcripts help us provide the "Deniability" property:
219 if someone claims you said something over OTR, they'll have no proof, as
220 anyone at all can modify a transcript to make it say whatever they like,
221 and still have all the verification come out correctly.
222
223 Here are the six programs in the toolkit:
224
225 - otr_parse
226 - Parse OTR messages given on stdin, showing the values of all the
227 fields in OTR protocol messages.
228
229 - otr_sesskeys our_privkey their_pubkey
230 - Shows our public key, the session id, two AES and two MAC keys
231 derived from the given Diffie-Hellman keys (one private, one public).
232
233 - otr_mackey aes_enc_key
234 - Shows the MAC key derived from the given AES key.
235
236 - otr_readforge aes_enc_key [newmsg]
237 - Decrypts an OTR Data message using the given AES key, and displays
238 the message, if the key was correct.
239 - If newmsg is given, replace the message with that one, encrypt
240 and MAC it properly, and output the resulting OTR Data Message.
241 This works even if the given key was not correct for the original
242 message, so as to enable complete forgeries.
243
244 - otr_modify mackey old_text new_text offset
245 - Even if you can't read the data because you don't know either
246 the AES key or the Diffie-Hellman private key, but you can make a
247 good guess that the substring "old_text" appears at the given
248 offset in the message, replace the old_text with the new_text
249 (which must be of the same length), recalculate the MAC with the
250 given mackey, and output the resulting Data message.
251 - Note that, even if you don't know any text in an existing message,
252 you can still forge messages of your choice using the otr_readforge
253 command, above.
254
255 - otr_remac mackey sender_instance receiver_instance flags keyid keyid
256 pubkey counter encdata revealed_mackeys
257 - Make a new OTR Data Message, with the given pieces (note that the
258 data part is already encrypted). MAC it with the given mackey.
259
260 NOTES
261
262 Please send your bug reports, comments, suggestions, patches, etc. to us
263 at the contact address below.
264
265 In otrl_message_sending, specifying an instance tag allows you to send a
266 message to a particular session of a buddy who is logged in multiple times
267 with an otr-enabled client. The OTRL_INSTAG_RECENT_RECEIVED meta-instance
268 relies on the time that libotr processed the most recent message. Meta-
269 instance tags resolve to actual instance tags before a message is sent. An
270 instant messaging network may not agree on which session of the remote party is
271 the most recent, e.g., due to underlying network race conditions. If the
272 behaviour of an instant messaging network is to only deliver to the most recent,
273 and libotr and the network disagree on which session is the most recent, the
274 other party will not process the given message. That is, the instant messaging
275 network will deliver the message to the session whose actual instance tag does
276 not match the addressed instance tag. Also note that OTRL_INSTAG_BEST also
277 prefers more recent instance tags in the case of multiple instances with the
278 same "best" status (most secure). In this case, the most recent has a
279 resolution of one second.
280
281 If otrl_message_sending is called with an original_msg that contains the text
282 "?OTR?", this is a signal to initiate or refresh an OTR session. There is
283 currently no way to indicate if this text was actually typed in by a user and
284 part of a conversation (e.g., someone communicating instructions on how to
285 refresh OTR). In the future, we may allow a policy to specify whether "?OTR?"
286 is a signal to start OTR, or just an ordinary message for encrypted and
287 unencrypted conversations.
288
289 MAILING LISTS
290
291 There are three mailing lists pertaining to Off-the-Record Messaging:
292
293 otr-announce:
294 https://lists.cypherpunks.ca/mailman/listinfo/otr-announce/
295 *** All users of OTR software should join this. *** It is used to
296 announce new versions of OTR software, and other important information.
297
298 otr-users:
299 https://lists.cypherpunks.ca/mailman/listinfo/otr-users/
300 Discussion of usage issues related to OTR Messaging software.
301
302 otr-dev:
303 https://lists.cypherpunks.ca/mailman/listinfo/otr-dev/
304 Discussion of OTR Messaging software development.
305
306 LICENSE
307
308 The Off-the-Record Messaging library (in the src directory) is
309 covered by the following (LGPL) license:
310
311 Off-the-Record Messaging library
312 Copyright (C) 2004-2016 Ian Goldberg, David Goulet, Rob Smits,
313 Chris Alexander, Willy Lew, Lisa Du,
314 Nikita Borisov
315 <[email protected]>
316
317 This library is free software; you can redistribute it and/or
318 modify it under the terms of version 2.1 of the GNU Lesser General
319 Public License as published by the Free Software Foundation.
320
321 This library is distributed in the hope that it will be useful,
322 but WITHOUT ANY WARRANTY; without even the implied warranty of
323 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
324 Lesser General Public License for more details.
325
326 There is a copy of the GNU Lesser General Public License in the
327 COPYING.LIB file packaged with this library; if you cannot find it,
328 write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
329 Floor, Boston, MA 02110-1301 USA
330
331 The library comes with a test suite (in the tests directory), which is
332 covered by the following (GPL) license:
333
334 Copyright (C) 2014 Julien Voisin <[email protected]>,
335 David Goulet <[email protected]>
336
337 This program is free software; you can redistribute it and/or modify it
338 under the terms of the GNU General Public License, version 2 only, as
339 published by the Free Software Foundation.
340
341 This program is distributed in the hope that it will be useful, but WITHOUT
342 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
343 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
344 more details.
345
346 You should have received a copy of the GNU General Public License along with
347 this program; if not, write to the Free Software Foundation, Inc., 51
348 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
349
350 The Off-the-Record Messaging Toolkit (in the toolkit directory) is covered
351 by the following (GPL) license:
352
353 Off-the-Record Messaging Toolkit
354 Copyright (C) 2004-2014 Ian Goldberg, David Goulet, Rob Smits,
355 Chris Alexander, Nikita Borisov
356 <[email protected]>
357
358 This program is free software; you can redistribute it and/or modify
359 it under the terms of version 2 of the GNU General Public License as
360 published by the Free Software Foundation.
361
362 This program is distributed in the hope that it will be useful,
363 but WITHOUT ANY WARRANTY; without even the implied warranty of
364 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
365 GNU General Public License for more details.
366
367 There is a copy of the GNU General Public License in the COPYING file
368 packaged with this toolkit; if you cannot find it, write to the Free
369 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
370 02110-1301 USA
371
372 CONTACT
373
374 To report problems, comments, suggestions, patches, etc., you can email
375 the authors:
376
377 Ian Goldberg, David Goulet, Rob Smits, Chris Alexander, Lisa Du,
378 Nikita Borisov
379 <[email protected]>
380
381 For more information on Off-the-Record Messaging, visit
382 https://otr.cypherpunks.ca/