[OTR-dev] Re: Requirements for libotr4

[Uli M]

Hi,

On 2008-06-18, Willy Lew
<willylew at gmail.com> wrote:
> ------=_Part_3121_10507133.1213753314536
> Content-Type: text/plain; charset=ISO-8859-1
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> Hello fellow IM devs,
>
> As some of you may already know, we are revamping the libotr API (the
> messaging part in particular) to address several issues that were brought up
> recently. The four major changes are:

I'd like to mention some things I wished for when implementing
irssi-otr (irssi is an IRC client often used in conjunction with the
IM-to-IRC-gateway bitlbee). I believe all those points are also
interesting for other IM-clients.

1. Asynchronous key generation. On some systems key generation can
take more than one hour. I don't know how other IM-clients do it but I
had to create a seperate process (not thread) for key generation which
is really not ideal since inter-thread communication is a lot simpler.
Also key generation will just finish at some random point in time and
update the keys file. What I would like to have is one thread safe
function that generates a key (some opaque struct I don't care about)
which I can later on(in my main thread) give to libotr for inclusion.

2. No hardcoded strings at all. I don't know if your point about error
codes covers the case "The following message ... was not encrypted:
[...]". Here one would need an error code plus the message that was
received.

3. [resent] messages. They should be handled in the same way as the
msgs I mentioned in 2., OTR shouldnt change messages at all and most
certainly not inject a hardcoded "[resent]" string.

4. The 3 line spanning OTR announce message, ironically also called
"better message" in the code. This is again a hardcoded string I would
like to see disappear. The really really bad thing about it is that it
is a 3 line message and in IRC we don't have newlines. So in order to
eat this message up and not present it to the user I had to hardcode
the second and third line in irssi-otr. Bad!

5. "?OTR?" restarts OTR. Again a hardcoded string I would like to see
disappear. Because of it, it is impossible to transfer OTR
conversations over OTR...and also complicated to talk about OTR in an
OTR session...I always find myself writing "if you wanna restart OTR
write <question mark>OTR....". A function otr_restart would be the
right thing here I believe.

6. SMP handling. Ian said this would be reworked but it's missing in
the 4 points below. E.g. applications really shouldnt mess around with
variables that libotr touches as well (smstate->nextExpected).

7. Maximum message size handshake. Currently, each end uses its own
MMS. This is a bad thing if you use something like jabber transports
because the jabber end will likely have a too large MMS for the other
end (ICQ,...). For irssi-otr it's always a problem in conjunction with
bitlbee since IRC has a limit of about 500 and the other end might be
playing with 2k. The only reason why this currently works at all is
because OTR messages (except the 'better' msg under 4.) start with
"?OTR:" and end with "." so irssi-otr can reconstruct them for libotr.
The solution is simple: Each end advertises its own MSS during the
initial handshake and both use the minimum of the two.

Thanks,

Uli

>
> *** 1. Hardcoded strings ***
> No more hardcoded HTML error strings! We are adding a new function in
> OtrlMessageAppOps to let the IM handle the error according to an error code.
> For instance, OtrlMessageAppOps will look like this:
>
> typedef struct s_OtrlMessageAppOps {
>     OtrlPolicy (*policy)(void *opdata, ConnContext *context);
>     ...
>     void (*account_name_free)(void *opdata, const char *account_name);
>
>     /* Handles an error given the error code */
>     void (*handle_error)(void *opdata, ConnContext *context, OtrlErrorCode
> error_code);
> } OtrlMessageAppOps;
>
>
> Tentatively, we will provide a convenient errorcode-to-errorstring lookup
> function that will look like this:
>
> const char * otrl_message_errstr_en(OtrlErrorCode error_code);
>
>
> *** 2. Custom message stripping function ***
> otrl_message_sending and otrl_message_receiving will be having an extra
> optional argument (a callback function) to give the IMs the flexibility to
> strip/convert the messages that are sent/received. For example, the
> conversion function could strip the HTML tags out of the original message in
> order to be guaranteed an HTML-free message.
>
> gcry_error_t otrl_message_sending(OtrlUserState us,
>     const OtrlMessageAppOps *ops,
>     void *opdata, const char *accountname, const char *protocol,
>     const char *recipient, const char *message, OtrlTLV *tlvs,
>     char **messagep,
>     void (*add_appdata)(void *data, ConnContext *context),
>     void *data,
>     void (*convert_msg)(void *convertdata, char *source, char **target),
>     void *convertdata);
>
> int otrl_message_receiving(OtrlUserState us, const OtrlMessageAppOps *ops,
>     void *opdata, const char *accountname, const char *protocol,
>     const char *sender, const char *message, char **newmessagep,
>     OtrlTLV **tlvsp,
>     void (*add_appdata)(void *data, ConnContext *context),
>     void *data,
>     void (*convert_msg)(void *convertdata, char *source, char **target),
>     void *convertdata);
>
> *** 3. Fragmentation ***
> We are adding a new argument (OtrlFragmentPolicy) to otrl_message_sending so
> that the fragmentation task is done without manually calling
> otrl_message_fragment_and_send. If the original messaging behaviour is
> preferred, the OtrlFragmentPolicy can be OTRL_FRAGMENT_DONTFRAGMENT. The new
> signature for otrl_message_sending (including the conversion function as
> described above) will look like this:
>
>
> gcry_error_t otrl_message_sending(OtrlUserState us,
>     const OtrlMessageAppOps *ops,
>     void *opdata, const char *accountname, const char *protocol,
>     const char *recipient, const char *message, OtrlTLV *tlvs,
>     char **messagep,
>     void (*add_appdata)(void *data, ConnContext *context),
>     void *data,
>     void (*convert_msg)(void *convertdata, char *source, char **target),
>     void *convertdata,
>     OtrlFragmentPolicy fragPolicy);
>
>
> Since we will not need to call otrl_message_fragment_and_send anymore, we
> are planning to remove that function from the public API.
>
> *** 4. Stripping ConnContext ***
> We are stripping down ConnContext so that it only exposes the members that
> are meant to be public. It will look like this:
>
> typedef struct context {
>     char * username;
>     char * accountname;
>     char * protocol;
>     OtrlMessageState msgstate;
>     OtrlAuthInfo auth;
>     Fingerprint fingerprint_root;
>     Fingerprint *active_fingerprint;
>     unsigned int protocol_version;
>     void *app_data;
>     void (*app_data_free)(void *);
>     OtrlSMState *smstate;
>
>     ConnContextInternal *internal_context;
> } ConnContext;
>
>
>
> At the end of this email you will find a list of APIs that will be kept
> public. I have made that list by going through the code of a few IMs that
> use OTR and by recording their respective otrl_* calls. If I have missed
> anything in that list or if you have any other concerns/issues, please let
> me know asap since I am in the process of gathering the requirements for the
> new API. Note that we are also fixing the multiple login problem and this
> entails a few other changes to the API but those have not been finalized
> yet.
>
> Cheers!
> - willy
>
>
> *** List of APIs to be kept in libotr4 ***
> otrl_context_disconnect
> otrl_context_find
> otrl_context_find_fingerprint
> otrl_context_forget_all
> otrl_context_forget_fingerprint
> otrl_context_set_trust
>
> otrl_message_abort_smp
> otrl_message_disconnect
> otrl_message_free
> otrl_message_initiate_smp
> otrl_message_initiate_smp_q
> otrl_message_receiving
> otrl_message_respond_smp
> otrl_message_sending
>
> otrl_privkey_fingerprint
> otrl_privkey_forget_all
> otrl_privkey_generate
> otrl_privkey_generate_FILEp
> otrl_privkey_hash_to_human
> otrl_privkey_read
> otrl_privkey_read_FILEp
> otrl_privkey_read_fingerprints
> otrl_privkey_read_fingerprints_FILEp
> otrl_privkey_write_fingerprints
> otrl_privkey_write_fingerprints_FILEp
>
> otrl_proto_default_query_msg
> otrl_proto_message_type
>
> otrl_tlv_find
> otrl_tlv_free
>
> otrl_userstate_create
> otrl_userstate_free