NAME

Crypt::OTR - Off-The-Record encryption library for secure instant messaging applications

SYNOPSIS

use Crypt::OTR;

# call near the beginning of your program
Crypt::OTR->init;

# create OTR object, set up callbacks
my $otr = new Crypt::OTR(
    account_name     => "alice",            # name of account associated with this keypair
    protocol_name    => "my_protocol_name", # e.g. 'AIM'
    max_message_size => 1024,               # how much to fragment
);
$otr->set_callback('inject' => \&otr_inject);
$otr->set_callback('otr_message' => \&otr_system_message);
$otr->set_callback('secured' => \&otr_verified);
$otr->set_callback('unverified' => \&otr_unverified);

# create a context for user "bob"
$otr->establish("bob");  # calls otr_inject($account_name, $protocol, $dest_account, $message)

# send a message to bob
my $plaintext = "hello, bob! this is a message from alice";
if (my $ciphertext = $otr->encrypt("bob", $plaintext)) {
    $my_app->send_message_to_user("bob", $ciphertext);
} else {
    warn "Your message was not sent - no encrypted conversation is established\n";
}

# called from bob's end
if (my $plaintext = $otr->decrypt("alice", $ciphertext)) {
    print "alice: $plaintext\n";
} else {
    warn "We received an encrypted message from alice but were unable to decrypt it\n";
}

# done with chats
$otr->finish("bob");

# CALLBACKS 
#  (if writing a multithreaded application you will
#   probably want to lock a mutex when sending/receiving)

# called when OTR is ready to send a message after massaging it.
# this method should actually transmit $message to $dest_account
sub otr_inject {
    my ($self, $account_name, $protocol, $dest_account, $message) = @_;
    $my_app->send_message_to_user($dest_account, $message);
}

# called to display an OTR control message for a particular user or protocol
sub otr_system_message {
    my ($self, $account_name, $protocol, $other_user, $otr_message) = @_;
    warn "OTR says: $otr_message\n";
    return 1;
}

# called when a verified conversation is established with $from_account
sub verified {
    my ($self, $from_account) = @_;
    print "Started verified conversation with $from_account\n";
}

# called when an unverified conversation is established with $from_account
sub unverified {
    my ($self, $from_account) = @_;
    print "Started unverified conversation with $from_account\n";
}

DESCRIPTION

Perl wrapper around libotr2 - see http://www.cypherpunks.ca/otr/README-libotr-3.2.0.txt

EXPORT

None by default.

METHODS

init(%opts)

This method sets up OTR and initializes the global OTR context. It is probably unsafe to call this more than once

new(%opts)

This method sets up an OTR context for an account on a protocol (e.g. sk8rD00d510 on OSCAR)

Options: 'account_name' => name of the account in your application 'protocol' => string identifying your application 'max_message_size' => how many bytes messages should be fragmented into

set_callback($event, \&callback)

Set a callback to be called when various events happen:

inject: Called when establishing a connection, or sending a
fragmented message. This should send your message over whatever
communication channel your application is using.

otr_message: Called when OTR wants to display a notification. Return
1 if the message has been displayed, return 0 if you want OTR to
display the message inline.

connect: Called when a verified conversation is established

unverified: called when an unverified conversation is established
establish($user_name)

Attemps to begin an OTR-encrypted conversation with $user_name. This will call the inject callback with a message containing an OTR connection attempt.

encrypt($user_name, $plaintext)

Encrypts $plaintext for $user_name. Returns undef unless an encrypted message has been generated, in which case it returns that.

decrypt($user_name, $ciphertext)

Decrypt a message from $user_name, returns plaintext if successful, otherwise undef

start_smp($user_name, $secret, $question)

Start the Socialist Millionaires' Protocol over the current connection, using the given initial secret, and optionally a question to pass to the buddy (not supported).

continue_smp($user_name, $secret)

Continue the Socialist Millionaires' Protocol over the current connection, using the given initial secret

abort_smp($user_name)

Abort the SMP protocol. Used when malformed or unexpected messages are received.

finish($user_name)

Ends an encrypted conversation, no new messages from $user_name will be able to be decrypted

SEE ALSO

http://www.cypherpunks.ca/otr

TODO

- More documentation (always)

- More tests (always)

AUTHOR

Patrick Tierney, <patrick.l.tierney@gmail.com> Mischa Spiegelmock, <mspiegelmock@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Patrick Tierney, Mischa Spiegelmock

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.