NAME Protocol::OTR - Off-the-Record secure messaging protocol VERSION version 0.05 SYNOPSIS use Protocol::OTR qw( :constants ); my $otr = Protocol::OTR->new( { privkeys_file => "otr.private_key", contacts_file => "otr.fingerprints", instance_tags_file => "otr.instance_tags", } ); # find or create account my $alice = $otr->account('alice@domain', 'prpl-jabber'); # find or create contact known by $alice my $bob = $alice->contact('bob@domain'); # create secure channel to Bob my $channel = $bob->channel( { policy => ..., max_message_size => ..., on_write => sub { ... }, on_read => sub { ... }, on_gone_secure => sub { ... }, on_gone_insecure => sub { ... }, on_still_secure => sub { ... }, on_unverified_fingerprint => sub { ... }, on_symkey => sub { ... }, on_timer => sub { ... }, on_smp => sub { ... }, on_error => sub { ... }, on_event => sub { ... }, on_smp_event => sub { ... }, on_before_encrypt => sub { ... }, on_after_decrypt => sub { ... }, on_is_contact_logged_in => sub { ... }, } ); # establish private chat $channel->init(); # encrypt message $channel->write("Hi Bob!"); # finish all sessions $channel->finish(); DESCRIPTION Protocol::OTR provides bindings to Off-the-Record C library allowing to manage OTR setup and to communicate in secure way. METHODS new my $otr = Protocol::OTR->new( { privkeys_file => "otr.private_key", contacts_file => "otr.fingerprints", instance_tags_file => "otr.instance_tags", } ); Returns an context object using optionally specified files. If files do not exist, they will be created when needed. The example above shows the default filenames used. find_account my $account = $otr->find_account( $name, $protocol ); Returns an account object Protocol::OTR::Account if exists, otherwise "undef". account my $account = $otr->account( $name, $protocol ); Returns an existing matching account object Protocol::OTR::Account or creates new one. Note: Generating new private key may take some time. accounts my @accounts = $otr->accounts(); Returns a list of known account objects Protocol::OTR::Account. ENVIRONMENT VARIABLES PROTOCOL_OTR_ENABLE_QUICK_RANDOM BEGIN { $ENV{PROTOCOL_OTR_ENABLE_QUICK_RANDOM} = 1; } use Protocol::OTR; If exists in environment it will use much faster "/dev/urandom", rather then more secure, but slow "/dev/random". EXPORTED CONSTANTS Constants are grouped in four groups, to import them all use ":constants". :policies See "policy" in Protocol::OTR::Channel for usage details. POLICY_OPPORTUNISTIC Start OTR conversation whenever it detects that the correspondent supports it. Default. POLICY_ALWAYS Requires encrypted conversation. :error_codes See "on_error" in Protocol::OTR::Channel for usage details. ERRCODE_NONE ERRCODE_ENCRYPTION_ERROR Error occured while encrypting a message. ERRCODE_MSG_NOT_IN_PRIVATE Sent encrypted message to somebody who is not in a mutual OTR session. ERRCODE_MSG_UNREADABLE Sent an unreadable encrypted message ERRCODE_MSG_MALFORMED Message sent is malformed. :event_codes See "on_event" in Protocol::OTR::Channel for usage details. MSGEVENT_NONE MSGEVENT_ENCRYPTION_REQUIRED Our policy requires encryption but we are trying to send an unencrypted message out. MSGEVENT_ENCRYPTION_ERROR An error occured while encrypting a message and the message was not sent. MSGEVENT_CONNECTION_ENDED Message has not been sent because our buddy has ended the private conversation. We should either close the connection, or refresh it. MSGEVENT_SETUP_ERROR A private conversation could not be set up. Error message will be passed. MSGEVENT_MSG_REFLECTED Received our own OTR messages. MSGEVENT_MSG_RESENT The previous message was resent. MSGEVENT_RCVDMSG_NOT_IN_PRIVATE Received an encrypted message but cannot read it because no private connection is established yet. MSGEVENT_RCVDMSG_UNREADABLE Cannot read the received message. MSGEVENT_RCVDMSG_MALFORMED The message received contains malformed data. MSGEVENT_LOG_HEARTBEAT_RCVD Received a heartbeat. MSGEVENT_LOG_HEARTBEAT_SENT Sent a heartbeat. MSGEVENT_RCVDMSG_GENERAL_ERR Received a general OTR error. Error message will be passed. MSGEVENT_RCVDMSG_UNENCRYPTED Received an unencrypted message. The unencrypted message will be passed. MSGEVENT_RCVDMSG_UNRECOGNIZED Cannot recognize the type of OTR message received. MSGEVENT_RCVDMSG_FOR_OTHER_INSTANCE Received and discarded a message intended for another instance. :smp_event_codes See "on_smp_event" in Protocol::OTR::Channel for usage details. SMPEVENT_NONE SMPEVENT_CHEATED The current verification has been aborted, use progress percent to update auth progress dialog. SMPEVENT_IN_PROGRESS SMPEVENT_SUCCESS SMPEVENT_FAILURE SMPEVENT_ABORT Update the auth progress dialog with progress percent SMPEVENT_ERROR Same as "SMPEVENT_CHEATED". :instags See "select_session" in Protocol::OTR::Channel for usage details. INSTAG_BEST Session that has the best conversation status, then fingerprint status (in the event of a tie), then most recent (similarly in the event of a tie). When calculating how recent an instance has been active, "INSTAG_BEST" is limited by a one second resolution. INSTAG_RECENT The most recent session (either by message sent or received). INSTAG_RECENT_RECEIVED The session with the most recent message received. INSTAG_RECENT_SENT The session with the most recent message sent. SEE ALSO * * Protocol::OTR::Account * Protocol::OTR::Contact * Protocol::OTR::Fingerprint * Protocol::OTR::Channel AUTHOR Alex J. G. Burzyński COPYRIGHT AND LICENSE This software is copyright (c) 2014 by Alex J. G. Burzyński . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.