view release on metacpan or  search on metacpan

lib/Protocol/OTR.pm  view on Meta::CPAN

        {
            name => $name,
            protocol => $protocol,
        }
    );
}

sub accounts {
    my ($self) = @_;

    return map {
        Protocol::OTR::Account->_new($self, $_)
    } @{ $self->_accounts() }
}

sub find_account {
    my $self = shift;

    my ($name, $protocol) = validate_pos(
        @_,
        {
            type => SCALAR,
        },
        {
            type => SCALAR,
        }
    );

    return Protocol::OTR::Account->_new(
        $self,
        {
            name => $name,
            protocol => $protocol,
        },
        1, # find only
    );
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Protocol::OTR - Off-the-Record secure messaging protocol

=head1 VERSION

version 0.05

=head1 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();

=head1 DESCRIPTION

L<Protocol::OTR> provides bindings to L<Off-the-Record C library|https://otr.cypherpunks.ca/>
allowing to manage OTR setup and to communicate in secure way.

=head1 METHODS

=head2 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.

=head2 find_account

    my $account = $otr->find_account( $name, $protocol );

Returns an account object L<Protocol::OTR::Account> if exists, otherwise C<undef>.

=head2 account

    my $account = $otr->account( $name, $protocol );

Returns an existing matching account object L<Protocol::OTR::Account> or creates new one.

Note: Generating new private key may take some time.

=head2 accounts

    my @accounts = $otr->accounts();

Returns a list of known account objects L<Protocol::OTR::Account>.

=head1 ENVIRONMENT VARIABLES

=head2 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 C</dev/urandom>, rather then more
secure, but slow C</dev/random>.

=head1 EXPORTED CONSTANTS

Constants are grouped in four groups, to import them all use C<:constants>.

=head2 :policies

See L<Protocol::OTR::Channel/policy> for usage details.

=head3 POLICY_OPPORTUNISTIC

Start OTR conversation whenever it detects that the correspondent supports it. Default.

=head3 POLICY_ALWAYS

Requires encrypted conversation.

=head2 :error_codes

See L<Protocol::OTR::Channel/on_error> for usage details.