1 Off-the-Record Messaging plugin for pidgin 2 v4.0.2, 9 Mar 2016 3 4This is a pidgin plugin which implements Off-the-Record (OTR) Messaging. 5It is known to work (at least) under the Linux and Windows versions of 6pidgin (2.x). 7 8OTR allows you to have private conversations over IM by providing: 9 - Encryption 10 - No one else can read your instant messages. 11 - Authentication 12 - You are assured the correspondent is who you think it is. 13 - Deniability 14 - The messages you send do _not_ have digital signatures that are 15 checkable by a third party. Anyone can forge messages after a 16 conversation to make them look like they came from you. However, 17 _during_ a conversation, your correspondent is assured the messages 18 he sees are authentic and unmodified. 19 - Perfect forward secrecy 20 - If you lose control of your private keys, no previous conversation 21 is compromised. 22 23For more information on Off-the-Record Messaging, see 24https://otr.cypherpunks.ca/ 25 26USAGE 27 28Run pidgin, and open the Plugins panel. (If you had a copy of pidgin 29running before you installed pidgin-otr, you will need to restart it.) 30Find the Off-the-Record Messaging plugin, and enable it by selecting the 31checkbox next to it. That should be all you need to do. 32 33CONFIGURATION 34 35Click "Configure Plugin" to bring up the OTR UI. The UI has two 36"pages": "Config" and "Known fingerprints". 37 38The "Config" page allows you generate private keys, and to set OTR 39settings and options. 40 41 Private keys are used to authenticate you to your buddies. OTR will 42 automatically generate private keys when needed, but you can also 43 generate them manually if you wish by using the "Generate" button 44 here. Choose one of your accounts from the menu, click "Generate" 45 and wait until it's finished. You'll see a sequence of letters and 46 number appear above the "Generate" button. This is the 47 "fingerprint" for that account; it is unique to that account. If 48 you have multiple IM accounts, you can generate private keys for 49 each one separately. 50 51 The OTR settings determine when private messaging is enabled. The 52 checkboxes on this page control the default settings; you can edit 53 the per-buddy settings by right-clicking on your buddy in the buddy 54 list, and choosing "OTR Settings" from the menu. 55 56 The settings are: 57 [X] Enable private messaging 58 [X] Automatically initiate private messaging 59 [ ] Require private messaging 60 [ ] Don't log OTR conversations 61 62 If the "enable private messaging" box is unchecked, private messages 63 will be disabled completely (and the other two boxes will be greyed 64 out, as they're irrelevant). 65 66 If the first box is checked, but "automatically initiate private 67 messaging" is unchecked, private messaging will be enabled, but only 68 if either you or your buddy explicitly requests to start a private 69 conversation (and the third box will be greyed out, as it's 70 irrelevant). 71 72 If the first two boxes are checked, but "require private messaging" 73 is unchecked, OTR will attempt to detect whether your buddy can 74 understand OTR private messages, and if so, automatically start a 75 private conversation. 76 77 If the first three boxes are checked, messages will not be sent to your 78 buddy unless you are in a private conversation. 79 80 If the fourth box is checked, OTR-protected conversations will not 81 be logged, even if logging of instant messages is turned on in 82 pidgin. 83 84 The OTR UI Options control the appearance of OTR in your conversation 85 window. At present, the only option is: 86 [X] Show OTR button in toolbar 87 88 This option controls whether an extra button will appear in your 89 toolbar. This button will allow you to quickly see the OTR status 90 of your conversation, to manually start or stop an OTR conversation, 91 or to authenticate your buddy. All of these abilities are already 92 available in the OTR menu, but some people prefer a butter closer to 93 where they type their messages. 94 95The "Known fingerprints" page allows you to see the fingerprints of any 96buddies you have previously communicated with privately. 97 98 The "Status" will indicate the current OTR status of any 99 conversation using each fingerprint. The possibilities are 100 "Private", which means you're having a private conversation, 101 "Unverified", which means you have not yet verified your buddy's 102 fingerprint, "Not private", which means you're just chatting in IM 103 the usual (non-OTR) way, and "Finished", which means your buddy has 104 selected "End private conversation"; at this point, you will be 105 unable to send messages to him at all, until you either also choose 106 "End private conversation" (in which case further messages will be 107 sent unencrypted), or else choose "Refresh private conversation" (in 108 which case further messages will be sent privately). 109 110 The table also indicates whether or not you have verified this 111 fingerprint by authenticating your buddy. 112 113 By selecting one of your buddies from the list, you'll be able to do 114 one or more of the following things by clicking the buttons below 115 the list: 116 - "Start private conversation": if the status is "Not private" or 117 "Finished", this will attempt to start a private conversation. 118 - "End private conversation": if the status is "Unverified", 119 "Private", or "Finished", you can force an end to your private 120 conversation by clicking this button. There's not usually a good 121 reason to do this, though. 122 - "Verify fingerprint": this will open a window where you can 123 verify the value of your buddies' fingerprint. If you do not 124 wish to work with fingerprints directly, you should instead 125 authenticate used the OTR button from within a conversation. 126 - "Forget fingerprint": this will remove your buddy's fingerprint 127 from the list. You'll have to re-authenticate him the next time 128 you start a private conversation with him. Note that you can't 129 forget a fingerprint that's currently in use in a private 130 conversation. 131 132You can close the configuration panel (but make sure not to disable the 133OTR plugin). 134 135IM as normal with your buddies. If you want to start a private 136conversation with one of them, bring up the OTR menu (either from the 137menubar or by clicking the OTR button, if you have enabled it). From 138the OTR menu, select "Start private conversation". 139 140If your buddy does not have the OTR plugin, a private conversation will 141(of course) not be started. [But he or she will get some information 142about OTR instead.] 143 144If your buddy does have the OTR plugin (and it's enabled), a private 145conversation will be initiated. 146 147If both you and your buddy have OTR software, and your OTR settings set 148to automatically initiate private messaging, your clients may recognize 149each other and automatically start a private conversation. 150 151The first time you have a private conversation with one of your buddies, 152a message will appear in your conversation telling you to authenticate 153them. You may authenticate by selecting "Authenticate Buddy" on the 154OTR menu. This is described later on. 155 156At this point, the label on the OTR button in the conversation window 157will change to "OTR: Unverified". This means that, although you are 158sending encrypted messages, you have not yet authenticated your buddy, 159and so it is not certain that the person who can decrypt these messages 160is actually your buddy (it may be an attacker). This situation will 161remain until either you or your buddy choose "Authenticate Buddy" from 162the OTR button menu (described next). 163 164The OTR menu contains the following choices: 165 166Start / Refresh private conversation 167 168 Choosing this menu option will attempt to start (or refresh, if 169 you're already in one) a private conversation with this buddy. 170 171End private conversation 172 173 If you wish to end the private conversation, and go back to 174 communicating without privacy protection, you can select this 175 option. Note that if you have "Automatically initiate private 176 messaging" set, it is likely that a new private conversation will 177 automatically begin immediately. 178 179Authenticate Buddy 180 181 For more information on authentication, see 182 https://otr-help.cypherpunks.ca/3.2.0/authenticate.php 183 184 OTR provides three ways to authenticate your buddy: 185 186 1) Question and answer 187 2) Shared secret 188 3) Manual fingerprint verification 189 190 To start the authentication process, you need to first be 191 communicating with your buddy in the "Unverified" or "Private" 192 states. [Although the "Private" state indicates that you have 193 already successfully authenticated your buddy, and it is not 194 necessary to do it again.] Choose "Authenticate buddy" from the OTR 195 menu. The Authenticate Buddy dialog will pop up. Use the combo box 196 to select which of the three authentication methods you would like 197 to use. 198 199 Once you have authenticated your buddy, your OTR status will change 200 to "Private". OTR will also remember that you successfully 201 authenticated, and during future private conversations with the same 202 buddy, you will no longer get the warning message when you start 203 chatting. This will continue until your buddy switches to a 204 computer or an IM account he or she hasn't used before, at which 205 point OTR will not recognize him or her and you will be asked to 206 authenticate again. 207 208 Question and answer 209 ------------------- 210 211 To authenticate using a question, pick a question whose answer is 212 known only to you and your buddy. Enter this question and this 213 answer, then wait for your buddy to enter the answer too. If the 214 answers don't match, then you may be talking to an imposter. 215 216 If your buddy answers correctly, then you have successfully 217 authenticated him or her, and the OTR status of this conversation 218 will change to "Private". 219 220 Your buddy will probably also want to ask you a question as well in 221 order for him or her to authenticate you back. 222 223 Note that this method first appeared in pidgin-otr 3.2.0; if your 224 buddy is using an older version, this will not work. 225 226 Shared secret 227 ------------- 228 229 To authenticate someone with the shared secret method, you and your 230 buddy should decide on a secret word or phrase in advance. This can 231 be done however you like, but you shouldn't type the phrase directly 232 into your conversation. 233 234 Enter the shared secret into the field provided in the Authenticate 235 Buddy dialog box. Once you enter the secret and hit OK, your buddy 236 will be asked to do exactly the same thing. If you both enter the 237 same text, then OTR will accept that you are really talking to your 238 buddy. Otherwise, OTR reports that authentication has failed. This 239 either means that your buddy made a mistake typing in the text, or 240 it may mean that someone is intercepting your communication. 241 242 Note that this method first appeared in pidgin-otr 3.1.0; if your 243 buddy is using an older version, this will not work. 244 245 Manual fingerprint verification 246 ------------------------------- 247 248 If your buddy is using a version of pidgin-otr before 3.1.0, or a 249 different OTR client that does not support the other authentication 250 methods, you will need to use manual fingerprint verification. 251 252 You will need some other authenticated communication channel (such 253 as speaking to your buddy on the telephone, or sending gpg-signed 254 messages). You should tell each other your own fingerprints. If 255 the fingerprint your buddy tells you matches the one listed as his 256 or her "purported fingerprint", pull down the selection that says "I 257 have not" (verified that this is in fact the correct fingerprint), 258 and change it to "I have". 259 260 Once you do this, the OTR status will change to "Private". Note 261 that you only need to do this once per buddy (or once per 262 fingerprint, if your buddy has more than one fingerprint). 263 pidgin-otr will remember which fingerprints you have marked as 264 verified. 265 266What's this? 267 268 This will open a web browser to get online help. 269 270 271 272NOTES 273 274Please send your bug reports, comments, suggestions, patches, etc. to us 275at the contact address below. 276 277This plugin only attempts to protect instant messages, not multi-party 278chats, file transfers, etc. 279 280MAILING LISTS 281 282There are three mailing lists pertaining to Off-the-Record Messaging: 283 284otr-announce: 285 https://lists.cypherpunks.ca/mailman/listinfo/otr-announce/ 286 *** All users of OTR software should join this. *** It is used to 287 announce new versions of OTR software, and other important information. 288 289otr-users: 290 https://lists.cypherpunks.ca/mailman/listinfo/otr-users/ 291 Discussion of usage issues related to OTR Messaging software. 292 293otr-dev: 294 https://lists.cypherpunks.ca/mailman/listinfo/otr-dev/ 295 Discussion of OTR Messaging software development. 296 297LICENSE 298 299The Off-the-Record Messaging plugin for pidgin is covered by the following 300(GPL) license: 301 302 Off-the-Record Messaging plugin for pidgin 303 Copyright (C) 2004-2016 Ian Goldberg, Rob Smits, 304 Chris Alexander, Willy Lew, 305 Lisa Du, Nikita Borisov 306 <otr@cypherpunks.ca> 307 308 309 This program is free software; you can redistribute it and/or modify 310 it under the terms of version 2 of the GNU General Public License as 311 published by the Free Software Foundation. 312 313 This program is distributed in the hope that it will be useful, 314 but WITHOUT ANY WARRANTY; without even the implied warranty of 315 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 316 GNU General Public License for more details. 317 318 There is a copy of the GNU General Public License in the COPYING file 319 packaged with this plugin; if you cannot find it, write to the Free 320 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 321 02110-1301 USA 322 323CONTACT 324 325To report problems, comments, suggestions, patches, etc., you can email 326the authors: 327 328Ian Goldberg, Rob Smits, Chris Alexander, Willy Lew, Lisa Du, Nikita Borisov 329<otr@cypherpunks.ca> 330 331For more information on Off-the-Record Messaging, visit 332https://otr.cypherpunks.ca/ 333