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