Crypt::OTR - Off-The-Record encryption library for secure instant messaging applications
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";
}
Perl wrapper around libotr2 - see http://www.cypherpunks.ca/otr/README-libotr-3.2.0.txt
None by default.
This method sets up OTR and initializes the global OTR context. It is probably unsafe to call this more than once
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 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
Attemps to begin an OTR-encrypted conversation with $user_name. This will call the inject callback with a message containing an OTR connection attempt.
Encrypts $plaintext for $user_name. Returns undef unless an encrypted message has been generated, in which case it returns that.
Decrypt a message from $user_name, returns plaintext if successful, otherwise undef
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 the Socialist Millionaires' Protocol over the current connection, using the given initial secret
Abort the SMP protocol. Used when malformed or unexpected messages are received.
Ends an encrypted conversation, no new messages from $user_name will be able to be decrypted
- More documentation (always)
- More tests (always)
Patrick Tierney, <patrick.l.tierney@gmail.com> Mischa Spiegelmock, <mspiegelmock@gmail.com>
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.
