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