view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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
    <https://otr.cypherpunks.ca/> 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.