Commit 6d754cc0 authored by Jurre van Bergen's avatar Jurre van Bergen

Added new files to mimic site of otr.cypherpunks.ca

parent 4bbe82fb
Off-the-Record Messaging Library and Toolkit
v4.1.1, 9 Mar 2016
This is a library and toolkit which implements Off-the-Record (OTR) Messaging.
OTR allows you to have private conversations over IM by providing:
- Encryption
- No one else can read your instant messages.
- Authentication
- You are assured the correspondent is who you think it is.
- Deniability
- The messages you send do _not_ have digital signatures that are
checkable by a third party. Anyone can forge messages after a
conversation to make them look like they came from you. However,
_during_ a conversation, your correspondent is assured the messages
he sees are authentic and unmodified.
- Perfect forward secrecy
- If you lose control of your private keys, no previous conversation
is compromised.
For more information on Off-the-Record Messaging, see
https://otr.cypherpunks.ca/
LIBRARY USAGE
1. Initialization
Before you call any other libotr routine, you need to initialize the
library. The easiest way to do that is to include proto.h, and use the
macro:
OTRL_INIT;
somewhere early in your program. This should be called only once.
You will also need an OtrlUserState. An OtrlUserState encapsulates the
list of known fingerprints and the list of private keys, so it should be
"one per user". Many OTR-enabled programs (such as IM clients) only have a
single user, so for them, you can just create a single one, and use it
throughout. Create an OtrlUserState as follows:
userstate = otrl_userstate_create();
If you need to free an OtrlUserState:
otrl_userstate_free(userstate);
To read stored private keys:
otrl_privkey_read(userstate, privkeyfilename);
To read stored instance tags:
otrl_instag_read(userstate, instagfilename);
To read stored fingerprints:
otrl_privkey_read_fingerprints(userstate, fingerprintfilename,
add_app_info, add_app_info_data);
add_app_info is a function that will be called in the event that a new
ConnContext is created. It will be passed the add_app_info_data that
you supplied, as well as a pointer to the new ConnContext. You can use
this to add application-specific information to the ConnContext using
the "context->app" field, for example. If you don't need to do this,
you can pass NULL for the last two arguments of
otrl_privkey_read_fingerprints.
2. Setting up the UI functions
You need to let the library know how to do any UI it might require
(error messages, confirming new fingerprints, etc.). To this end, you
need to define a number of UI functions, and collect them in a
OtrlMessageAppOps struct.
The first parameter of every UI function is "void *opdata". This is a
pointer you pass to the library, and it will pass back (opaquely) to the
UI functions when it calls them. You can use this to keep track of
state or any other information.
You will need to include proto.h and message.h, and you can find a list
of the UI functions in message.h.
3. Sending messages
When you have a message you're about to send, you'll need to know four
things: you account name, the protocol id, the name of the recipient,
their instance tag, and the message.
OTR protocol version 3 introduces the notion of "instance tags." A
client may be logged into the same account multiple times from different
locations. An instance tag is intended to differentiate these clients.
When sending a message, you may also specify a particular instance tag,
or use meta instance tags like OTRL_INSTAG_MOST_SECURE.
The protocol id is just a unique string that is used to distinguish
the user foo on AIM from the user foo on MSN, etc. It can be anything
you like, so long as you're consistent, but if you've got nothing better
to use, you may as well use the ids from gaim. (Programs that use the
same protocol ids can share fingerprint and private key files.) The
gaim protocol id for AIM/ICQ is "prpl-oscar".
Note that a name does not uniquely identify a user (as shown by the
"foo" example above). Even if you know both the name and the protocol,
it may not identify the user, since there may be multiple "foo" users on
IRC, on different servers. But the *three* items (your account name,
protocol id, their name) _must_ uniquely identify a user, so your
account name needs to include any network identifier, such as a server
name. Examples would be "foo@irc.freenode.net" or "foo@jabber.org".
Protocols such as AIM that do not have separate networks can just use
"foo", of course.
To encrypt the message (if necessary; the library keeps track of which
users you have secure connections to, so you should *always* call this
next function), simply do this:
gcry_error_t err;
char *newmessage = NULL;
err = otrl_message_sending(userstate, &ui_ops, opdata, accountname,
protocolid, recipient_name, instag, message, tlvs,
&newmessage, fragPolicy, contextp, add_app_info,
add_app_info_data);
add_app_info and add_app_info_data are as above, and may be NULL.
tlvs should usually be NULL. If it's not, then it points to a chain of
OtrlTLVs which represent machine-readable data to send along with this
message.
If contextp is not NULL, it will be set to the context that was used
for sending the message.
If err is non-zero, then the library tried to encrypt the message,
but for some reason failed. DO NOT send the message in the clear in
that case.
If newmessage gets set by the call to something non-NULL, then you
should replace your message with the contents of newmessage, and
send that instead.
Once the message is encrypted, it may still be too large to send over
the network in a single piece. To check the maximum message size and
break your message into fragments if necessary, do this:
gcry_error_t err;
char *extrafragment = NULL;
err = otrl_message_fragment_and_send(&ui_ops, opdata, context,
message, fragmentPolicy, extrafragment);
fragmentPolicy determines which, if any, fragments to return instead
of sending them immediately. For example, you may wish to send all
fragments except the last one, which is handled differently. Valid
policies may be found in proto.h.
If err returns a nonzero value from fragment_and_send, the application
tried to break your message into fragments but failed for some reason.
You may still attempt to send the original message, but it might be
rejected if it too large.
When you're done with newmessage, you must call
otrl_message_free(newmessage)
4. Receiving messages
Receiving messages is similarly straightforward. Again, you need to
know four things: your account name, the protocol id, the sender's name,
and the message.
int ignore_message;
char *newmessage = NULL;
ignore_message = otrl_message_receiving(userstate, &ui_ops, opdata,
accountname, protocolid, sender_name, message, &newmessage,
&tlvs, contextp, add_app_info, add_app_info_data);
add_app_info and add_app_info_data are as above, and may be NULL.
If contextp is not NULL, it will be set to the context that was used
for receiving the message.
If otrl_message_receiving returns 1, then the message you received was
an internal protocol message, and no message should be delivered to the
user.
If it returns 0, then check if newmessage was set to non-NULL. If so,
replace the received message with the contents of newmessage, and
deliver that to the user instead. You must call
otrl_message_free(newmessage) when you're done with it.
If otrl_message_receiving returns 0 and newmessage is NULL, then this
was an ordinary, non-OTR message, which should just be delivered to the
user without modification.
If tlvs is set to non-NULL, then there is machine-readable data that was
sent along with this message. Call otrl_tlv_free(tlvs) when you're done
dealing with it (or ignoring it).
5. Socialist Millionaires' Protocol
The Socialist Millionaires' Protocol (SMP) is a way to detect
eavesdropping and man-in-the-middle attacks without requiring users to
work with fingerprints. This feature was added to OTR starting in
version 3.1.0. To learn how to modify your application to use SMP, read
the UPGRADING file.
TOOLKIT
Along with the library, this package comes with the OTR Messaging
Toolkit. This toolkit is useful for analyzing and/or forging OTR
messages. Why do we offer this? Primarily, to make absolutely sure
that transcripts of OTR conversations are really easy to forge after the
fact. [Note that *during* an OTR conversation, messages can't be forged
without real-time access to the secret keys on the participants'
computers, and in that case, all security has already been lost.]
Easily forgeable transcripts help us provide the "Deniability" property:
if someone claims you said something over OTR, they'll have no proof, as
anyone at all can modify a transcript to make it say whatever they like,
and still have all the verification come out correctly.
Here are the six programs in the toolkit:
- otr_parse
- Parse OTR messages given on stdin, showing the values of all the
fields in OTR protocol messages.
- otr_sesskeys our_privkey their_pubkey
- Shows our public key, the session id, two AES and two MAC keys
derived from the given Diffie-Hellman keys (one private, one public).
- otr_mackey aes_enc_key
- Shows the MAC key derived from the given AES key.
- otr_readforge aes_enc_key [newmsg]
- Decrypts an OTR Data message using the given AES key, and displays
the message, if the key was correct.
- If newmsg is given, replace the message with that one, encrypt
and MAC it properly, and output the resulting OTR Data Message.
This works even if the given key was not correct for the original
message, so as to enable complete forgeries.
- otr_modify mackey old_text new_text offset
- Even if you can't read the data because you don't know either
the AES key or the Diffie-Hellman private key, but you can make a
good guess that the substring "old_text" appears at the given
offset in the message, replace the old_text with the new_text
(which must be of the same length), recalculate the MAC with the
given mackey, and output the resulting Data message.
- Note that, even if you don't know any text in an existing message,
you can still forge messages of your choice using the otr_readforge
command, above.
- otr_remac mackey sender_instance receiver_instance flags keyid keyid
pubkey counter encdata revealed_mackeys
- Make a new OTR Data Message, with the given pieces (note that the
data part is already encrypted). MAC it with the given mackey.
NOTES
Please send your bug reports, comments, suggestions, patches, etc. to us
at the contact address below.
In otrl_message_sending, specifying an instance tag allows you to send a
message to a particular session of a buddy who is logged in multiple times
with an otr-enabled client. The OTRL_INSTAG_RECENT_RECEIVED meta-instance
relies on the time that libotr processed the most recent message. Meta-
instance tags resolve to actual instance tags before a message is sent. An
instant messaging network may not agree on which session of the remote party is
the most recent, e.g., due to underlying network race conditions. If the
behaviour of an instant messaging network is to only deliver to the most recent,
and libotr and the network disagree on which session is the most recent, the
other party will not process the given message. That is, the instant messaging
network will deliver the message to the session whose actual instance tag does
not match the addressed instance tag. Also note that OTRL_INSTAG_BEST also
prefers more recent instance tags in the case of multiple instances with the
same "best" status (most secure). In this case, the most recent has a
resolution of one second.
If otrl_message_sending is called with an original_msg that contains the text
"?OTR?", this is a signal to initiate or refresh an OTR session. There is
currently no way to indicate if this text was actually typed in by a user and
part of a conversation (e.g., someone communicating instructions on how to
refresh OTR). In the future, we may allow a policy to specify whether "?OTR?"
is a signal to start OTR, or just an ordinary message for encrypted and
unencrypted conversations.
MAILING LISTS
There are three mailing lists pertaining to Off-the-Record Messaging:
otr-announce:
https://lists.cypherpunks.ca/mailman/listinfo/otr-announce/
*** All users of OTR software should join this. *** It is used to
announce new versions of OTR software, and other important information.
otr-users:
https://lists.cypherpunks.ca/mailman/listinfo/otr-users/
Discussion of usage issues related to OTR Messaging software.
otr-dev:
https://lists.cypherpunks.ca/mailman/listinfo/otr-dev/
Discussion of OTR Messaging software development.
LICENSE
The Off-the-Record Messaging library (in the src directory) is
covered by the following (LGPL) license:
Off-the-Record Messaging library
Copyright (C) 2004-2016 Ian Goldberg, David Goulet, Rob Smits,
Chris Alexander, Willy Lew, Lisa Du,
Nikita Borisov
<otr@cypherpunks.ca>
This library is free software; you can redistribute it and/or
modify it under the terms of version 2.1 of the GNU Lesser General
Public License as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
There is a copy of the GNU Lesser General Public License in the
COPYING.LIB file packaged with this library; if you cannot find it,
write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
Floor, Boston, MA 02110-1301 USA
The library comes with a test suite (in the tests directory), which is
covered by the following (GPL) license:
Copyright (C) 2014 Julien Voisin <julien.voisin@dustri.org>,
David Goulet <dgoulet@ev0ke.net>
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License, version 2 only, as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
The Off-the-Record Messaging Toolkit (in the toolkit directory) is covered
by the following (GPL) license:
Off-the-Record Messaging Toolkit
Copyright (C) 2004-2014 Ian Goldberg, David Goulet, Rob Smits,
Chris Alexander, Nikita Borisov
<otr@cypherpunks.ca>
This program is free software; you can redistribute it and/or modify
it under the terms of version 2 of the GNU General Public License as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
There is a copy of the GNU General Public License in the COPYING file
packaged with this toolkit; if you cannot find it, write to the Free
Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA
CONTACT
To report problems, comments, suggestions, patches, etc., you can email
the authors:
Ian Goldberg, David Goulet, Rob Smits, Chris Alexander, Lisa Du,
Nikita Borisov
<otr@cypherpunks.ca>
For more information on Off-the-Record Messaging, visit
https://otr.cypherpunks.ca/
This diff is collapsed.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIVAwUAVt4CX/JN4I9CwqutAQL7MQ/5AQlshdD3HMkpV3wNpf9f6NelVPA/eQ9h
kElKLdHxvtk4AxaFckMYGKCvcz+zJ3LBG80kynx/uZeuI/4JvZOiclW29BO6q2u0
gGWPXNzWkKQs+thV+zLsw1ANglAumHJvvwAI5jqGf7xe1PWk8xsCCesq8mI57BG4
IXjGFDK12ez7ZsIC6r/s8UY1fZ/vsrSOEUwm/t9A+XfTedB/6OdH1ik7m8RXzolW
hoELP/8OrtHHbBiNT/riWMv9JHBZCbxum+RNv/U7W7QQ2pwuTIWYSy+Zet8rxInR
9Xyo+Kt6+yMmejW9EWKMfGn9DINkjOV87o8CRjMUydZ6NKf0MF8/bhIdAKZ9VAYJ
0ROoT5qyHx/PzYpqNqo9GZaDZFgzfot5Bctu4n+dZX083YY8JtGLOvZUgiQ0YlCC
ZVnutkQ8jKzL2G3TPAsvzfcunFJUzINvH3hlzcOC8s/+10VtoABlcdJx+4KWksKk
Ubdhof09tisFosWpXpV/MxJgMYo4jOTM7bhBXZN5VYCTduIJboNKAjRLtAnKiurr
56vvNlh5FAhamfmmkHkhsHqE1p+P991No874wxr6lROJmKhUNDRxVRbQe1r8Qvdm
O4iq7YEBpOYwGbvmnVrzQbkn4fJbkfxwRsCUkq0/8Nsu6b5lrzbgn1hWBkjVu3Cc
QXwnCHotd4g=
=LacL
-----END PGP SIGNATURE-----
Off-the-Record Messaging plugin for pidgin
v4.0.2, 9 Mar 2016
This is a pidgin plugin which implements Off-the-Record (OTR) Messaging.
It is known to work (at least) under the Linux and Windows versions of
pidgin (2.x).
OTR allows you to have private conversations over IM by providing:
- Encryption
- No one else can read your instant messages.
- Authentication
- You are assured the correspondent is who you think it is.
- Deniability
- The messages you send do _not_ have digital signatures that are
checkable by a third party. Anyone can forge messages after a
conversation to make them look like they came from you. However,
_during_ a conversation, your correspondent is assured the messages
he sees are authentic and unmodified.
- Perfect forward secrecy
- If you lose control of your private keys, no previous conversation
is compromised.
For more information on Off-the-Record Messaging, see
https://otr.cypherpunks.ca/
USAGE
Run pidgin, and open the Plugins panel. (If you had a copy of pidgin
running before you installed pidgin-otr, you will need to restart it.)
Find the Off-the-Record Messaging plugin, and enable it by selecting the
checkbox next to it. That should be all you need to do.
CONFIGURATION
Click "Configure Plugin" to bring up the OTR UI. The UI has two
"pages": "Config" and "Known fingerprints".
The "Config" page allows you generate private keys, and to set OTR
settings and options.
Private keys are used to authenticate you to your buddies. OTR will
automatically generate private keys when needed, but you can also
generate them manually if you wish by using the "Generate" button
here. Choose one of your accounts from the menu, click "Generate"
and wait until it's finished. You'll see a sequence of letters and
number appear above the "Generate" button. This is the
"fingerprint" for that account; it is unique to that account. If
you have multiple IM accounts, you can generate private keys for
each one separately.
The OTR settings determine when private messaging is enabled. The
checkboxes on this page control the default settings; you can edit
the per-buddy settings by right-clicking on your buddy in the buddy
list, and choosing "OTR Settings" from the menu.
The settings are:
[X] Enable private messaging
[X] Automatically initiate private messaging
[ ] Require private messaging
[ ] Don't log OTR conversations
If the "enable private messaging" box is unchecked, private messages
will be disabled completely (and the other two boxes will be greyed
out, as they're irrelevant).
If the first box is checked, but "automatically initiate private
messaging" is unchecked, private messaging will be enabled, but only
if either you or your buddy explicitly requests to start a private
conversation (and the third box will be greyed out, as it's
irrelevant).
If the first two boxes are checked, but "require private messaging"
is unchecked, OTR will attempt to detect whether your buddy can
understand OTR private messages, and if so, automatically start a
private conversation.
If the first three boxes are checked, messages will not be sent to your
buddy unless you are in a private conversation.
If the fourth box is checked, OTR-protected conversations will not
be logged, even if logging of instant messages is turned on in
pidgin.
The OTR UI Options control the appearance of OTR in your conversation
window. At present, the only option is:
[X] Show OTR button in toolbar
This option controls whether an extra button will appear in your
toolbar. This button will allow you to quickly see the OTR status
of your conversation, to manually start or stop an OTR conversation,
or to authenticate your buddy. All of these abilities are already
available in the OTR menu, but some people prefer a butter closer to
where they type their messages.
The "Known fingerprints" page allows you to see the fingerprints of any
buddies you have previously communicated with privately.
The "Status" will indicate the current OTR status of any
conversation using each fingerprint. The possibilities are
"Private", which means you're having a private conversation,
"Unverified", which means you have not yet verified your buddy's
fingerprint, "Not private", which means you're just chatting in IM
the usual (non-OTR) way, and "Finished", which means your buddy has
selected "End private conversation"; at this point, you will be
unable to send messages to him at all, until you either also choose
"End private conversation" (in which case further messages will be
sent unencrypted), or else choose "Refresh private conversation" (in
which case further messages will be sent privately).
The table also indicates whether or not you have verified this
fingerprint by authenticating your buddy.
By selecting one of your buddies from the list, you'll be able to do
one or more of the following things by clicking the buttons below
the list:
- "Start private conversation": if the status is "Not private" or
"Finished", this will attempt to start a private conversation.
- "End private conversation": if the status is "Unverified",
"Private", or "Finished", you can force an end to your private
conversation by clicking this button. There's not usually a good
reason to do this, though.
- "Verify fingerprint": this will open a window where you can
verify the value of your buddies' fingerprint. If you do not
wish to work with fingerprints directly, you should instead
authenticate used the OTR button from within a conversation.
- "Forget fingerprint": this will remove your buddy's fingerprint
from the list. You'll have to re-authenticate him the next time
you start a private conversation with him. Note that you can't
forget a fingerprint that's currently in use in a private
conversation.
You can close the configuration panel (but make sure not to disable the
OTR plugin).
IM as normal with your buddies. If you want to start a private
conversation with one of them, bring up the OTR menu (either from the
menubar or by clicking the OTR button, if you have enabled it). From
the OTR menu, select "Start private conversation".
If your buddy does not have the OTR plugin, a private conversation will
(of course) not be started. [But he or she will get some information
about OTR instead.]
If your buddy does have the OTR plugin (and it's enabled), a private
conversation will be initiated.
If both you and your buddy have OTR software, and your OTR settings set
to automatically initiate private messaging, your clients may recognize
each other and automatically start a private conversation.
The first time you have a private conversation with one of your buddies,
a message will appear in your conversation telling you to authenticate
them. You may authenticate by selecting "Authenticate Buddy" on the
OTR menu. This is described later on.
At this point, the label on the OTR button in the conversation window
will change to "OTR: Unverified". This means that, although you are
sending encrypted messages, you have not yet authenticated your buddy,
and so it is not certain that the person who can decrypt these messages
is actually your buddy (it may be an attacker). This situation will
remain until either you or your buddy choose "Authenticate Buddy" from
the OTR button menu (described next).
The OTR menu contains the following choices:
Start / Refresh private conversation
Choosing this menu option will attempt to start (or refresh, if
you're already in one) a private conversation with this buddy.
End private conversation
If you wish to end the private conversation, and go back to
communicating without privacy protection, you can select this
option. Note that if you have "Automatically initiate private
messaging" set, it is likely that a new private conversation will
automatically begin immediately.
Authenticate Buddy
For more information on authentication, see
https://otr-help.cypherpunks.ca/3.2.0/authenticate.php
OTR provides three ways to authenticate your buddy:
1) Question and answer
2) Shared secret
3) Manual fingerprint verification
To start the authentication process, you need to first be
communicating with your buddy in the "Unverified" or "Private"
states. [Although the "Private" state indicates that you have
already successfully authenticated your buddy, and it is not
necessary to do it again.] Choose "Authenticate buddy" from the OTR
menu. The Authenticate Buddy dialog will pop up. Use the combo box
to select which of the three authentication methods you would like
to use.
Once you have authenticated your buddy, your OTR status will change
to "Private". OTR will also remember that you successfully
authenticated, and during future private conversations with the same
buddy, you will no longer get the warning message when you start
chatting. This will continue until your buddy switches to a
computer or an IM account he or she hasn't used before, at which
point OTR will not recognize him or her and you will be asked to
authenticate again.
Question and answer
-------------------
To authenticate using a question, pick a question whose answer is
known only to you and your buddy. Enter this question and this
answer, then wait for your buddy to enter the answer too. If the
answers don't match, then you may be talking to an imposter.
If your buddy answers correctly, then you have successfully
authenticated him or her, and the OTR status of this conversation
will change to "Private".
Your buddy will probably also want to ask you a question as well in
order for him or her to authenticate you back.