| 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 |
|