initial commit with v0.8.6.1

git-svn-id: http://mirotr.googlecode.com/svn/trunk@2 eced67a3-f377-a0ae-92ae-d6de1850b05a

1 files changed, 337 insertions, 0 deletions

diff --git a/libotr-3.2.0/UPGRADING b/libotr-3.2.0/UPGRADING
new file mode 100644
index 0000000..6ca2134
--- /dev/null
+++ b/libotr-3.2.0/UPGRADING
@@ -0,0 +1,337 @@
+Table of Contents
+
+1. Introduction
+2. Major Additions
+2.1. Fragmentation
+2.2. Socialist Millionaires' Protocol
+3. Required Changes
+3.1. OtrlMessageAppOps Callbacks
+3.1.1. Max Message Size
+3.1.2. Account Name
+3.2. Using Fragmentation
+3.3. Using SMP
+3.3.1. Initiating
+3.3.2. Responding
+3.3.3. Aborting
+3.3.4. Control Flow and Errors
+3.4. Miscellaneous
+
+1. Introduction
+
+This file contains information about the changes between the 3.0.0 and
+the 3.2.0 APIs for libotr.  Note that, as a minor release, applications
+compiled against 3.0.0 will continue to work with 3.2.0.  This document
+explains how to add the new functionality in 3.2.0.
+
+2. Major Additions
+
+This section describes the new features in OTR 3.2.0 along with a short
+history or motivation for each.
+
+2.1. Fragmentation  [Added in 3.1.0]
+
+Most IM networks supported by Pidgin have fixed maximum message sizes
+(MMS) of approximately 1-3 kB.  The longer messages in the initial key
+exchange and the new socialist millionaires' protocol may exceed these
+common MMS values.  To allow these protocols to work properly even over
+networks with low MMS values, support for fragmentation was added.
+
+OTR version 3.0.0 added support for recombining message fragments to
+recover the original message.  Now that users may be assumed to be able to
+handle message fragments, support for fragmenting and sending large
+messages has been added to OTR 3.2.0.
+
+2.2. Socialist Millionaires' Protocol  [Added in 3.1.0, revised in 3.2.0]
+
+In version 3.0.0, the only method available to authenticate a buddy was
+fingerprint verification.  However, many users who are unfamiliar with
+cryptography do not understand what a fingerprint is or how it is useful.
+Also, the verification itself relied on the user obtaining an authentic
+copy of the other party's fingerprint somehow.  The simplest way to do so
+may be to relay the displayed hexadecimal values during a phone call,
+but this is a large enough hassle that many users omit fingerprint
+verification altogether.
+
+To allow for a method of authentication that is both easier to understand
+and easier to use, OTR version 3.2.0 includes the Socialist Millionaires'
+Protocol (SMP).  SMP runs as follows: each user inputs a secret string,
+say "x" and "y".  They then exchange a series of messages which reveal
+the value of (x==y), but no additional information about the inputs.
+This allows users to determine whether they hold the same secret
+information with no danger of revealing that secret to an attacker.
+
+To see how this is useful for authentication in OTR, assume that Alice
+and Bob are chatting over OTR for the first time, though they know each
+other well in real life.  Alice may send Bob the following message:
+"Let's make our shared secret the name of that restaurant we both like
+in Ottawa."
+
+Now Alice and Bob run SMP.  If Alice is actually talking to Bob directly,
+then they will both type in the same restaurant name and SMP will return
+success (x==y).  However, if an attacker is impersonating Bob or trying
+to eavesdrop on the conversation, they will have no idea which restaurant
+Alice has in mind, and will type in an incorrect value, causing SMP to
+fail.  Note that for security reasons, the values compared in the SMP
+are actually hashes of several pieces of data, including both parties'
+fingerprints, along with their respective secrets.  The users, however,
+are never exposed to this additional data.
+
+Thus, SMP turns the problem of obtaining an authentic copy of a
+fingerprint into the much simpler problem of obtaining any shared secret,
+or simply of drawing on shared experiences to generate one.
+
+For detailed information on how SMP works, see the paper by Boudot,
+Schoenmakers and Traore titled "A Fair and Efficient Solution to the
+Socialist Millionaires Problem" (2001), on which our solution is based.
+
+3. Required Changes  [Added in 3.1.0]
+
+3.1. OtrlMessageAppOps Callbacks
+
+Three new callbacks have been added to the end of OtrlMessageAppOps.  If
+the version number passed to otrl_init is less than 3.1.0 then libotr will
+not call any of the new callbacks.  As well, you may disable individual
+callbacks by setting them to NULL.  In either case, libotr will revert to
+the standard behaviour of version 3.0.0.
+
+3.1.1. Max Message Size
+
+The first new callback has the following signature:
+
+    int (*max_message_size)(void *opdata, ConnContext *context);
+
+This method is called whenever a message is about to be sent with
+fragmentation enabled.  The return value is checked against the size of
+the message to be sent to determine whether fragmentation is necessary.
+
+Although the maximum message size depends on a number of factors, we
+found experimentally that the following rough values based solely on the
+(pidgin) protocol name work well:
+    "prpl-msn",   1409
+    "prpl-icq",   2346
+    "prpl-aim",   2343
+    "prpl-yahoo", 832
+    "prpl-gg",    1999
+    "prpl-irc",   417
+    "prpl-oscar", 2343
+
+Setting max_message_size to NULL will disable the fragmentation of all
+sent messages; returning 0 from this callback will disable fragmentation
+of a particular message.  The latter is useful, for example, for
+protocols like XMPP (Jabber) that do not require fragmentation at all.
+
+3.1.2. Account Name
+
+The other two new callbacks have the following signatures: 
+
+    const char *(*account_name)(void *opdata, const char *account,
+	    const char *protocol);
+    void (*account_name_free)(void *opdata, const char *account_name);
+
+Normally, if an error message needs to be sent from Alice to Bob,
+containing Alice's account name, the value of ConnContext->accountname
+will be used.  However, if this default name is unsuitable for your
+application, you can use the above methods to provide replacement values
+for displayed account names.
+
+account_name is called when libotr requires a human-readable version of
+an account name.  account_name_free is called once the name has
+been used, and the memory allocated by account_name (if any) must be
+released.
+
+Setting account_name to NULL will cause libotr to use
+ConnContext->accountname as the displayed name for an account.
+
+3.2. Using Fragmentation  [Added in 3.1.0]
+
+To make use of fragmentation, first make sure that the max_message_size
+callback described in 3.1.1. has been implemented.  Then, whenever you
+would normally send a message through your IM client, call
+otrl_message_fragment_and_send instead:
+
+gcry_error_t otrl_message_fragment_and_send(const OtrlMessageAppOps *ops,
+	void *opdata, ConnContext *context, const char *message,
+	OtrlFragmentPolicy fragPolicy, char **returnFragment);
+
+Here, message is the original, encrypted, unfragmented message.
+This method will break the message into fragments and send either all of
+them or almost all of them according to the OtrlFragmentPolicy:
+
+OTRL_FRAGMENT_SEND_ALL            sends all fragments at once
+OTRL_FRAGMENT_SEND_ALL_BUT_FIRST  sends all but the first fragment
+OTRL_FRAGMENT_SEND_ALL_BUT_LAST   sends all but the last fragment
+
+You may wish to use one of the latter two options if you still wish to
+pass a message through your IM client.  In this case, the unsent
+fragment will be returned in returnFragment and should be sent as a
+regular message.  In order to reassemble the fragments, however, they
+must be received in order, so at most one of the latter two options
+will result in readable messages.
+
+3.3. Using SMP  [Added in 3.1.0, revised in 3.2.0]
+
+Recall from section 2.2. above that SMP takes one input string from each
+user and outputs either failure or success.
+
+3.3.1. Initiating
+
+If you wish to initiate SMP for a user named Alice, you would use
+otrl_message_initiate_smp.
+
+void otrl_message_initiate_smp(OtrlUserState us, const OtrlMessageAppOps *ops,
+	void *opdata, ConnContext *context, const unsigned char *secret,
+	size_t secretlen);
+
+Here, secret and secretlen describe the secret text as entered by Alice,
+for example, ("kitten", 6).  The other parameters are common to many
+otrl_message functions.  This method will cause a message to be sent
+containing an appropriate OTRL_TLV_SMP1 (see below).
+
+3.3.2. Responding
+
+If you wish to continue SMP by supplying the secret for a second user
+named Bob, you would use otrl_message_respond_smp:
+
+void otrl_message_respond_smp(OtrlUserState us, const OtrlMessageAppOps *ops,
+	void *opdata, ConnContext *context, const unsigned char *secret,
+	size_t secretlen);
+
+The arguments for this method are the same as otrl_message_initiate_smp.
+This method will send a message with an appropriate OTRL_TLV_SMP2
+(see below).
+
+3.3.3. Aborting
+
+If you wish to abort SMP for any reason, including errors occuring
+during the protocol, you should use otrl_message_abort_smp:
+
+void otrl_message_abort_smp(OtrlUserState us, const OtrlMessageAppOps *ops,
+	void *opdata, ConnContext *context);
+
+This method will cause the other user to abandon the current state of
+SMP by sending an appropriate OTRL_TLV_SMP_ABORT (see below).
+
+3.3.4. Control Flow and Errors
+ 
+The protocol itself consists of 4 messages passed between the two users,
+say Alice and Bob.  These messages are identified through their TLVs:
+
+OTRL_TLV_SMP1       The initial message, containing a commitment to
+                      Alice's secret
+OTRL_TLV_SMP1Q      Like OTRL_TLV_SMP1, but also containing a question
+                      to display to Bob
+OTRL_TLV_SMP2       A response containing a commitment to Bob's secret
+OTRL_TLV_SMP3       The next message in the chain, from Alice to Bob
+OTRL_TLV_SMP4       The final message in the chain, from Bob to Alice
+OTRL_TLV_SMP_ABORT  Indicates an error has occurred. Will reset SMP state
+
+To determine whether the protocol is proceeding correctly, additional
+information has been added to ConnContext.  You may access
+context->smstate->nextExpected to find out which TLV should come next,
+so you can compare this to what was actually received and take an
+appropriate action.  The value is of type NextExpectedSMP and could be
+any of:
+
+OTRL_SMP_EXPECT1   Next SMP TLV should be OTRL_TLV_SMP1
+OTRL_SMP_EXPECT2   Next SMP TLV should be OTRL_TLV_SMP2
+OTRL_SMP_EXPECT3   Next SMP TLV should be OTRL_TLV_SMP3
+OTRL_SMP_EXPECT4   Next SMP TLV should be OTRL_TLV_SMP4
+
+If at any point, an SMP TLV of an unexpected type is received, the
+protocol should abort.  Also, if the correct TLV type is received, then
+the state should be updated accordingly.  A typical control flow looks
+like this:
+
+    OtrlTLV *tlvs = NULL;
+    OtrlTLV *tlv = NULL;
+    [Initialize tlvs to the list of tlvs.  This can be done
+     as part of otrl_message_receiving.]
+
+    ConnContext *context = [correct context];
+    NextExpectedSMP nextMsg = context->smstate->nextExpected;
+
+    if (context->smstate->sm_prog_state == OTRL_SMP_PROG_CHEATED) {
+	otrg_plugin_abort_smp(context);
+	otrg_dialog_update_smp(context, 0.0);
+	context->smstate->nextExpected = OTRL_SMP_EXPECT1;
+	context->smstate->sm_prog_state = OTRL_SMP_PROG_OK;
+    } else {
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP1Q);
+	if (tlv) {
+	    if (nextMsg != OTRL_SMP_EXPECT1)
+		[abort SMP];
+	    else {
+		char *question = (char *)tlv->data;
+		char *eoq = memchr(question, '\0', tlv->len);
+		if (eoq) {
+		    [prompt the user with question, get the response,
+			and continue SMP];
+		}
+	    }
+	}
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP1);
+	if (tlv) {
+	    if (nextMsg != OTRL_SMP_EXPECT1)
+		[abort SMP];
+	    else {
+		[get secret from user and continue SMP];
+	    }
+	}
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP2);
+	if (tlv) {
+	    if (nextMsg != OTRL_SMP_EXPECT2)
+		[abort SMP];
+	    else {
+		// If we received TLV2, we will send TLV3 and expect TLV4
+		context->smstate->nextExpected = OTRL_SMP_EXPECT4;
+	    }
+	}
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP3);
+	if (tlv) {
+	    if (nextMsg != OTRL_SMP_EXPECT3)
+		[abort SMP];
+	    else {
+		// If we received TLV3, we will send TLV4
+		// We will not expect more messages, so prepare for next SMP
+		context->smstate->nextExpected = OTRL_SMP_EXPECT1;
+		// Report result to user
+	    }
+	}
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP4);
+	if (tlv) {
+	    if (nextMsg != OTRL_SMP_EXPECT4)
+		[abort SMP];
+	    else {
+		// We will not expect more messages, so prepare for next SMP
+		context->smstate->nextExpected = OTRL_SMP_EXPECT1;
+		// Report result to user
+	    }
+	}
+	tlv = otrl_tlv_find(tlvs, OTRL_TLV_SMP_ABORT);
+	if (tlv) {
+	    // The message we are waiting for will not arrive, so reset
+	    // and prepare for the next SMP
+	    context->smstate->nextExpected = OTRL_SMP_EXPECT1;
+	}
+    }
+
+To report the result to the user after receiving OTRL_TLV_SMP3 or
+OTRL_TLV_SMP4, check whether context->active_fingerprint->trust is a
+non-empty string.  (That is, check that it's not NULL, and that its
+first character is not '\0'.)  If that is the case, then the SMP
+completed successfully.  Otherwise, the parties entered different secrets.
+
+3.4 Miscellaneous
+
+b64.h underwent a minor change in OTR 3.1.0.  It was purely a
+housekeeping change and should not require any changes to dependent code.
+
+The arguments to otrl_base64_encode and otrl_base64_decode did not agree
+in terms of which were of type char* and which were unsigned char*
+instead.  This has been corrected.  The new method signatures are:
+
+size_t otrl_base64_encode(char *base64data, const unsigned char *data,
+	size_t datalen);
+size_t otrl_base64_decode(unsigned char *data, const char *base64data,
+	size_t base64len);
+