/ 
Crypt-OTR-0.08
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 libotr - see http://www.cypherpunks.ca/otr/README-libotr-3.2.0.txt

This module is experimental and unfinished, not yet recommended for production or important systems.

EXPORT

No namespace pollution will be tolerated.

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 $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

In list context, returns ($plaintext, $should_discard). If $should_discard is set, you should ignore the message entirely as it is an internal OTR protocol message or message fragment.

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)

- Find leaking scalars

AUTHOR

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

This module is unfinished, not very tested, and incomplete. Would you like to help make it better? Send an email to one of the authors, we'd love to get more people involved

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Patrick Tierney, Mischa Spiegelmock

  This program is free software: you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation, either version 3 of the
  License, or any later version.

  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, see
  <http://www.gnu.org/licenses/>.