Debian Codegraph @

UPGRADING

raw
1 Table of Contents
2
3 1. Introduction
4 2. Major Additions
5 2.1. Instance Tags
6 2.2. Asynchronous Private Key Generation
7 2.3. Extra Symmetric Key
8 2.4. Convert Operations
9 2.5. SMP, Error, and Message Event Callbacks
10 2.6. Fragmentation Changes
11 3. Required Changes
12 3.1. OtrlMessageAppOps Callbacks
13 3.1.1. Removed Operations
14 3.1.2. Added Operations
15 3.2. Instance Tags
16 3.3. Fragmentation Changes
17 3.4. Asynchronous Private Key Generation
18 3.5. Library Initialization
19
20 1. Introduction
21
22 This file contains information about the changes between the 3.2.0 and
23 the 4.0.0 APIs for libotr. Note that applications compiled against
24 previous versions of OTR will not work with libotr 4.0.0.
25
26 2. Major Additions
27
28 This section describes the new features in OTR 4.0.0 along with a short
29 history or motivation for each.
30
31 2.1. Instance Tags
32
33 Clients generate instance tags that are intended to be persistent. If
34 the same client is logged into the same account from multiple locations,
35 the intention is that he or she will have different instance tags at
36 each location. OTR wire messages (fragmented and unfragmented) include
37 the source and destination instance tags. If a client receives a message
38 that lists a destination instance tag different from his own, the client
39 will discard it (and issue a callback notifying the application of the
40 event).
41
42 This avoids an issue on IM networks that always relay all messages to
43 all sessions of a client who is logged in multiple times. In this
44 situation, OTR clients can attempt to establish an OTR session
45 indefinitely if there are interleaving messages from each of the
46 sessions.
47
48 2.2. Asynchronous Private Key Generation
49
50 Key generation can happen in a separate thread without blocking an
51 application.
52
53 2.3. Extra Symmetric Key
54
55 An extra symmetric key is kept synchronized during a conversation with a
56 buddy. Either side can send a signal that they wish to use this key for
57 some external purpose (e.g. things like a file transfer, in some other
58 channel of communication).
59
60 2.4. Convert Operations
61
62 There is now a callback that is made immediately before a message is
63 encrypted and immediately after a message is decrypted. This callback
64 can tweak the plaintext message as needed. For example, this could allow
65 an application to convert formatting on a message if this would normally
66 be done on the plaintext by some other entity while the message is in
67 transit.
68
69 2.5. SMP, Error, and Message Event Callbacks
70
71 To avoid hard-coded English phrases in libotr, operations which used to
72 pass back strings are replaced by operations that pass back event codes.
73
74 2.6. Fragmentation Changes
75
76 In libotr version 3.2.0, you would need to call otrl_message_sending()
77 to create an encrypted message, and then call fragment_and_send() to get
78 libotr to fragment and inject that message. In libotr 4.0.0, the
79 functionality of fragment_and_send() has been integrated into
80 otrl_message_sending().
81
82 3. Required Changes
83
84 3.1. OtrlMessageAppOps Callbacks
85
86 3.1.1. Removed Operations
87
88 /* Display a notification message for a particular accountname /
89 * protocol / username conversation. */
90 void (*notify)(void *opdata, OtrlNotifyLevel level,
91 const char *accountname, const char *protocol,
92 const char *username, const char *title,
93 const char *primary, const char *secondary);
94
95 The notify() operation was removed since it was used to pass in
96 hardcoded English strings. This has been replaced by error and message
97 event callbacks, described below, which pass event codes rather than
98 hardcoded strings.
99
100
101 /* Display an OTR control message for a particular accountname /
102 * protocol / username conversation. Return 0 if you are able to
103 * successfully display it. If you return non-0 (or if this
104 * function is NULL), the control message will be displayed inline,
105 * as a received message, or else by using the above notify()
106 * callback. */
107 int (*display_otr_message)(void *opdata, const char *accountname,
108 const char *protocol, const char *username, const char *msg);
109
110 The display_otr_message() operation was removed for the same reasons as
111 above for the notify() operation.
112
113
114 /* Return a newly allocated string containing a human-friendly name
115 * for the given protocol id */
116 const char *(*protocol_name)(void *opdata, const char *protocol);
117
118 /* Deallocate a string allocated by protocol_name */
119 void (*protocol_name_free)(void *opdata, const char *protocol_name);
120
121 The above operations are no longer required, as they were used when
122 preparing messages shown to users.
123
124
125 /* Log a message. The passed message will end in "\n". */
126 void (*log_message)(void *opdata, const char *message);
127
128 The log_message() operation was also replaced by message event
129 callbacks.
130
131 3.1.2. Added Operations
132
133 /* We received a request from the buddy to use the current "extra"
134 * symmetric key. The key will be passed in symkey, of length
135 * OTRL_EXTRAKEY_BYTES. The requested use, as well as use-specific
136 * data will be passed so that the applications can communicate other
137 * information (some id for the data transfer, for example). */
138 void (*received_symkey)(void *opdata, ConnContext *context,
139 unsigned int use, const unsigned char *usedata,
140 size_t usedatalen, const unsigned char *symkey);
141
142 This is called when a remote buddy has specified a use for the current
143 symmetric key. If your application does not use the extra symmetric key
144 it does not need to provide an implementation for this operation.
145
146
147 /* Return a string according to the error event. This string will then
148 * be concatenated to an OTR header to produce an OTR protocol error
149 * message. The following are the possible error events:
150 * - OTRL_ERRCODE_ENCRYPTION_ERROR
151 * occured while encrypting a message
152 * - OTRL_ERRCODE_MSG_NOT_IN_PRIVATE
153 * sent encrypted message to somebody who is not in
154 * a mutual OTR session
155 * - OTRL_ERRCODE_MSG_UNREADABLE
156 * sent an unreadable encrypted message
157 * - OTRL_ERRCODE_MSG_MALFORMED
158 * message sent is malformed */
159 const char *(*otr_error_message)(void *opdata, ConnContext *context,
160 OtrlErrorCode err_code);
161
162 /* Deallocate a string returned by otr_error_message */
163 void (*otr_error_message_free)(void *opdata, const char *err_msg);
164
165 These methods are for producing human-readable error message that will
166 be sent to the remote buddy when one of these error conditions occurs.
167 They will be appended to the string "?OTR Error: ". Implementing this
168 operation is not required, but depending on your application it may be a
169 good idea.
170
171
172 /* Return a string that will be prefixed to any resent message. If this
173 * function is not provided by the application then the default prefix,
174 * "[resent]", will be used.
175 * */
176 const char *(*resent_msg_prefix)(void *opdata, ConnContext *context);
177
178 /* Deallocate a string returned by resent_msg_prefix */
179 void (*resent_msg_prefix_free)(void *opdata, const char *prefix);
180
181 These operations give the option of chosing an alternative to the
182 English string "[resent]", when a message is resent.
183
184
185 /* Update the authentication UI with respect to SMP events
186 * These are the possible events:
187 * - OTRL_SMPEVENT_ASK_FOR_SECRET
188 * prompt the user to enter a shared secret. The sender application
189 * should call otrl_message_initiate_smp, passing NULL as the question.
190 * When the receiver application resumes the SM protocol by calling
191 * otrl_message_respond_smp with the secret answer.
192 * - OTRL_SMPEVENT_ASK_FOR_ANSWER
193 * (same as OTRL_SMPEVENT_ASK_FOR_SECRET but sender calls
194 * otrl_message_initiate_smp_q instead)
195 * - OTRL_SMPEVENT_CHEATED
196 * abort the current auth and update the auth progress dialog
197 * with progress_percent. otrl_message_abort_smp should be called to
198 * stop the SM protocol.
199 * - OTRL_SMPEVENT_INPROGRESS and
200 * OTRL_SMPEVENT_SUCCESS and
201 * OTRL_SMPEVENT_FAILURE and
202 * OTRL_SMPEVENT_ABORT
203 * update the auth progress dialog with progress_percent
204 * - OTRL_SMPEVENT_ERROR
205 * (same as OTRL_SMPEVENT_CHEATED)
206 * */
207 void (*handle_smp_event)(void *opdata, OtrlSMPEvent smp_event,
208 ConnContext *context, unsigned short progress_percent,
209 char *question);
210
211 These SMP events are initiated by otrl_message_receiving() when it has
212 received an SMP TLV from a remote buddy. If you application is
213 implementing support for SMP authentication it should handle these
214 events appropriately.
215
216 Previously applications had to manually check, upon receiving messages,
217 whether the message contained any SMP TLVs that are relevant to the
218 current SMP state.
219
220 /* Handle and send the appropriate message(s) to the sender/recipient
221 * depending on the message events. All the events only require an opdata,
222 * the event, and the context. The message and err will be NULL except for
223 * some events (see below). The possible events are:
224 * - OTRL_MSGEVENT_ENCRYPTION_REQUIRED
225 * Our policy requires encryption but we are trying to send
226 * an unencrypted message out.
227 * - OTRL_MSGEVENT_ENCRYPTION_ERROR
228 * An error occured while encrypting a message and the message
229 * was not sent.
230 * - OTRL_MSGEVENT_CONNECTION_ENDED
231 * Message has not been sent because our buddy has ended the
232 * private conversation. We should either close the connection,
233 * or refresh it.
234 * - OTRL_MSGEVENT_SETUP_ERROR
235 * A private conversation could not be set up. A gcry_error_t
236 * will be passed.
237 * - OTRL_MSGEVENT_MSG_REFLECTED
238 * Received our own OTR messages.
239 * - OTRL_MSGEVENT_MSG_RESENT
240 * The previous message was resent.
241 * - OTRL_MSGEVENT_RCVDMSG_NOT_IN_PRIVATE
242 * Received an encrypted message but cannot read
243 * it because no private connection is established yet.
244 * - OTRL_MSGEVENT_RCVDMSG_UNREADABLE
245 * Cannot read the received message.
246 * - OTRL_MSGEVENT_RCVDMSG_MALFORMED
247 * The message received contains malformed data.
248 * - OTRL_MSGEVENT_LOG_HEARTBEAT_RCVD
249 * Received a heartbeat.
250 * - OTRL_MSGEVENT_LOG_HEARTBEAT_SENT
251 * Sent a heartbeat.
252 * - OTRL_MSGEVENT_RCVDMSG_GENERAL_ERR
253 * Received a general OTR error. The argument 'message' will
254 * also be passed and it will contain the OTR error message.
255 * - OTRL_MSGEVENT_RCVDMSG_UNENCRYPTED
256 * Received an unencrypted message. The argument 'smessage' will
257 * also be passed and it will contain the plaintext message.
258 * - OTRL_MSGEVENT_RCVDMSG_UNRECOGNIZED
259 * Cannot recognize the type of OTR message received.
260 * - OTRL_MSGEVENT_RCVDMSG_FOR_OTHER_INSTANCE
261 * Received and discarded a message intended for another instance. */
262 void (*handle_msg_event)(void *opdata, OtrlMessageEvent msg_event,
263 ConnContext *context, const char *message,
264 gcry_error_t err);
265
266 This operation is called when some type of exceptional event has occured
267 that your application may want to be aware of. Your application may want
268 to write an event to a log file, display a message to the user, or
269 ignore the event. While it is not required to implement this operation,
270 it is probably a good idea.
271
272
273 /* Create a instance tag for the given accountname/protocol if
274 * desired. */
275 void (*create_instag)(void *opdata, const char *accountname,
276 const char *protocol);
277
278 This is called when the library notices this account name and protocol
279 pair does not have an instance tag. Similar to create_privkey(), your
280 application may simply open a file handle and call:
281 gcry_error_t otrl_instag_generate_FILEp(OtrlUserState us, FILE *instf,
282 const char *accountname, const char *protocol)
283
284 If you don't provide an implementation for this operation, a new
285 non-persistent instance tag will be randomly generated. One benefit to
286 having a persisted instance tag is that if your application closes and
287 re-opens during a private conversation, further messages you receive
288 from this buddy will correctly raise the
289 OTRL_MSGEVENT_RCVDMSG_UNREADABLE event instead of raising
290 OTRL_MSGEVENT_RCVDMSG_FOR_OTHER_INSTANCE because destination instance
291 tag is now different from your own.
292
293
294 /* Called immediately before a data message is encrypted, and after a data
295 * message is decrypted. The OtrlConvertType parameter has the value
296 * OTRL_CONVERT_SENDING or OTRL_CONVERT_RECEIVING to differentiate these
297 * cases. */
298 void (*convert_msg)(void *opdata, ConnContext *context,
299 OtrlConvertType convert_type, char ** dest, const char *src);
300
301 /* Deallocate a string returned by convert_msg. */
302 void (*convert_free)(void *opdata, ConnContext *context, char *dest);
303
304 The convert_msg() operation is called immediately before a message is
305 encrypted and immediately after a message is decrypted. This callback
306 can tweak the plaintext message as needed. One use case would be for an
307 application to tweak formatting on the plaintext if, for example, this
308 is something that would normally be done on the plaintext by some other
309 entity while the message is in transit.
310
311 /* When timer_control is called, turn off any existing periodic
312 * timer.
313 *
314 * Additionally, if interval > 0, set a new periodic timer
315 * to go off every interval seconds. When that timer fires, you
316 * must call otrl_message_poll(userstate, uiops, uiopdata); from the
317 * main libotr thread.
318 *
319 * The timing does not have to be exact; this timer is used to
320 * provide forward secrecy by cleaning up stale private state that
321 * may otherwise stick around in memory. Note that the
322 * timer_control callback may be invoked from otrl_message_poll
323 * itself, possibly to indicate that interval == 0 (that is, that
324 * there's no more periodic work to be done at this time).
325 *
326 * If you set this callback to NULL, then you must ensure that your
327 * application calls otrl_message_poll(userstate, uiops, uiopdata);
328 * from the main libotr thread every definterval seconds (where
329 * definterval can be obtained by calling
330 * definterval = otrl_message_poll_get_default_interval(userstate);
331 * right after creating the userstate). The advantage of
332 * implementing the timer_control callback is that the timer can be
333 * turned on by libotr only when it's needed.
334 *
335 * It is not a problem (except for a minor performance hit) to call
336 * otrl_message_poll more often than requested, whether
337 * timer_control is implemented or not.
338 *
339 * If you fail to implement the timer_control callback, and also
340 * fail to periodically call otrl_message_poll, then you open your
341 * users to a possible forward secrecy violation: an attacker that
342 * compromises the user's computer may be able to decrypt a handful
343 * of long-past messages (the first messages of an OTR
344 * conversation).
345 */
346 void (*timer_control)(void *opdata, unsigned int interval);
347
348 In order to prevent a forward secrecy violation, applications using
349 libotr now need to be able to call otrl_message_poll on occasion. The
350 simplest thing to do is just to set up a local timer that calls that
351 function every definterval =
352 otrl_message_poll_get_default_interval(userstate) seconds. To avoid
353 unnecessary overhead, however, the timer_control callback is available.
354 If you set timer_control to non-NULL, it will be called with
355 instructions to turn on or off the periodic timer, and to what interval.
356
357 You must also be sure to turn off the timer before freeing your
358 userstate with otrl_userstate_free.
359
360 3.2. Instance Tags
361
362 If your application allows the same user to be logged in multiple times
363 from different locations, it should probably be aware of instance tags.
364 A user can maintain multiple concurrent OTR conversations with a buddy
365 who is logged in multiple times. Only one of the buddy's sessions can be
366 a client who is running OTR protocol version 2. When a user has a
367 conversation with a buddy who is running OTR protocol version 2, the
368 conversation is associated with a ConnContext that lists
369 "their_instance" as OTRL_INSTAG_MASTER (which has a value of 0). Each
370 version 3 conversation with the same buddy will have its own
371 ConnContext, which you can differentiate by the value in the
372 "their_instance" field.
373
374 In the linked list of ConnContexts, the master context for a buddy is
375 always listed immediately before its children. Fingerprints are only
376 stored with the master context. Given a ConnContext associated to a
377 conversation with a buddy, you can easily iterate over all the contexts
378 for that buddy by doing the following:
379
380 void example_something_happened(ConnContext * context) {
381 ConnContext * context_iter = context->m_context;
382
383 while (context_iter && context_iter->m_context == context->m_context) {
384 /* Something you wish to affect all contexts of a particular buddy */
385 context_iter = context_iter->next;
386 }
387
388 If a user has multiple OTR sessions with the same buddy, your
389 application will likely want to provide some way for the user to select
390 which instance to send outgoing messages to. You can detect when a user
391 has multiple OTR sessions with the same buddy by iterating over the
392 ConnContexts of a buddy when a conversation has gone secure and checking
393 whether more than one is not in plaintext state. You specify which
394 instance outgoing messages are directed to in otrl_message_sending:
395
396 gcry_error_t otrl_message_sending(OtrlUserState us,
397 const OtrlMessageAppOps *ops,
398 void *opdata, const char *accountname, const char *protocol,
399 const char *recipient, otrl_instag_t instag, const char *original_msg,
400 OtrlTLV *tlvs, char **messagep, OtrlFragmentPolicy fragPolicy,
401 ConnContext **contextp,
402 void (*add_appdata)(void *data, ConnContext *context),
403 void *data);
404
405 Instead of an actual instance tag, you can specify a meta instance tag
406 (e.g., if the user has not made an explicit selection). Here are the
407 list of meta instance tags, as defined in instag.h:
408
409 #define OTRL_INSTAG_BEST 1 /* Most secure, based on: conv status,
410 * then fingerprint status, then most recent. */
411 #define OTRL_INSTAG_RECENT 2 /* Most recent of the two meta instances below */
412 #define OTRL_INSTAG_RECENT_RECEIVED 3
413 #define OTRL_INSTAG_RECENT_SENT 4
414
415 OTRL_INSTAG_BEST choses the instance that has the best conv status, then
416 fingerprint status (in the event of a tie), then most recent (similarly
417 in the event of a tie). When calculating how recent an instance has been
418 active, OTRL_INSTAG_BEST is limited by a one second resolution.
419 OTRL_INSTAG_RECENT* does not have this limitation, but due to inherent
420 uncertainty in some networks, libotr's notion of the most recent may not
421 always agree with the remote network. It is important to understand
422 this limitation due to the issue noted in the next paragraph.
423
424 Note that instances do add some uncertainty when dealing with networks
425 that only deliver messages to the most recently active session for a
426 buddy who is logged in multiple times. If you have a particular instance
427 selected, and the IM network is simply not going to deliver to that
428 particular instance, there isn't too much libotr can do. In this case,
429 you may want your application to warn when a user has selected an
430 instance that is not the most recent.
431
432 To explicitly specify the destination instance of a protocol version 2
433 conversation with a particular buddy, the instag value is
434 OTRL_INSTAG_MASTER.
435
436 To look up a ConnContext associated with a particular instance (or meta-
437 instance), specify the instance in otrl_context_find():
438
439 ConnContext * otrl_context_find(OtrlUserState us, const char *user,
440 const char *accountname, const char *protocol,
441 otrl_instag_t their_instance, int add_if_missing, int *addedp,
442 void (*add_app_data)(void *data, ConnContext *context), void *data)
443
444 If your application persists instance tags, when it starts up, it should
445 call one the following functions to read the persisted instance tags:
446
447 gcry_error_t otrl_instag_read(OtrlUserState us, const char *filename);
448 gcry_error_t otrl_instag_read_FILEp(OtrlUserState us, FILE *instf);
449
450 It would make sense to do this immediately after your application has
451 read stored privkeys and fingerprints.
452
453 3.3. Fragmentation Changes
454
455 In libotr version 3.2.0, you would need to call otrl_message_sending()
456 to create an encrypted message, and then call fragment_and_send() to
457 get libotr to fragment and inject that message. In libotr 4.0.0, the
458 functionality of fragment_and_send() has been integrated into
459 otrl_message_sending(). Simply specify an OtrlFragmentPolicy to
460 otrl_message_sending(). The fragmentation policies are the same as
461 before, and an addition policy "OTRL_FRAGMENT_SEND_SKIP" has been added
462 for cases when fragmentation is not desired.
463
464 3.4. Asynchronous Private Key Generation
465
466 An application that wants to begin asynchronous key generation calls the
467 following method:
468
469 /* Begin a private key generation that will potentially take place in
470 * a background thread. This routine must be called from the main
471 * thread. It will set *newkeyp, which you can pass to
472 * otrl_privkey_generate_calculate in a background thread. If it
473 * returns gcry_error(GPG_ERR_EEXIST), then a privkey creation for
474 * this accountname/protocol is already in progress, and *newkeyp will
475 * be set to NULL. */
476 gcry_error_t otrl_privkey_generate_start(OtrlUserState us,
477 const char *accountname, const char *protocol, void **newkeyp)
478
479 A background thread can call the following method with the structure
480 that was passed into "newkeyp" above:
481
482 /* Do the private key generation calculation. You may call this from a
483 * background thread. When it completes, call
484 * otrl_privkey_generate_finish from the _main_ thread. */
485 gcry_error_t otrl_privkey_generate_calculate(void *newkey)
486
487
488 Upon completion the application would call:
489
490 /* Call this from the main thread only. It will write the newly created
491 * private key into the given file and store it in the OtrlUserState. */
492 gcry_error_t otrl_privkey_generate_finish(OtrlUserState us,
493 void *newkey, const char *filename)
494
495 If the privkey generation was cancelled, the application should call:
496
497 /* Call this from the main thread only, in the event that the background
498 * thread generating the key is cancelled. The newkey is deallocated,
499 * and must not be used further. */
500 void otrl_privkey_generate_cancelled(OtrlUserState us, void *newkey)
501
502
503 3.5. Library Initialization
504
505 If you currently initialize libotr with the recommended OTRL_INIT;
506 macro, you do not need to change anything.
507
508 If you call otrl_init(ver_major, ver_minor, ver_sub) directly, then know
509 that this function no longer returns void. Previously, if the
510 application requested version numbers incompatible with those of the
511 library, the library would exit(1). Now, the otrl_init call will return
512 a non-zero error code. You must check the return value of otrl_init (a
513 gcry_error_t), and if it is non-zero, your application's expected
514 API/ABI does not match the installed libotr, and libotr cannot be used.
515