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.