Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 382 insertions, 0 deletions

diff --git a/comm/third_party/libotr/README b/comm/third_party/libotr/README
new file mode 100644
index 0000000000..aa34e08e4f
--- /dev/null
+++ b/comm/third_party/libotr/README
@@ -0,0 +1,382 @@
+	      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/