/ 
Crypt-OTR-0.02
River stage zero No dependents
/ Crypt::OTR

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('verified' => \&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 

# 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 should be called early at the start of your application, before using any OTR facilities. It is probably unwise to call this more than once.

new(%opts)

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

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

'config_dir'       => where to store keys and fingerprints, defaults to C<$ENV{HOME}/.otr/>
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 to the
user. Return 1 if the message has been displayed, return 0 if you
want OTR to display the message inline.

verified: A conncetion has been established and the other party's
key fingerprint has been verified

unverified: A connection has been established but the key
fingerprint has not been verified

disconnect: Connection has been disconnected

system_message: OTR has a system message to display to the user

error: Error message to display

warning: Warning message to display

info: Informative message to display

new_fingerprint: Received a new fingerprint for a user

smp_request: Identity verification challenge request
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) 2010 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.