/ 
Crypt-NaCl-Sodium-0.03
River stage one • 1 direct dependent • 2 total dependents
/ Crypt::NaCl::Sodium::onetimeauth

NAME

Crypt::NaCl::Sodium::onetimeauth - One-time authentication (Poly1305)

VERSION

version 0.03

SYNOPSIS

use Crypt::NaCl::Sodium qw( :utils );

my $crypto_onetimeauth = Crypt::NaCl::Sodium->onetimeauth();

my ($msg, $key, $mac);

$msg = "First message";

# generate one-time secret key
$key = $crypto_onetimeauth->keygen();

# calculate authenticator
$mac = $crypto_onetimeauth->mac( $msg, $key );

# verify message
if ( $crypto_onetimeauth->verify($mac, $msg, $key) ) {
    # verified OK
}

DESCRIPTION

The crypto_onetimeauth's "mac", viewed as a function of the message for a uniform random key, is designed to meet the standard notion of unforgeability after a single message. After the sender authenticates one message, an attacker cannot find authenticators for any other messages.

The sender must not use this function to authenticate more than one message under the same key. Authenticators for two messages under the same key should be expected to reveal enough information to allow forgeries of authenticators on other messages.

When multiple messages need to be authenticated use Crypt::NaCl::Sodium::auth.

METHODS

keygen

my $key = $crypto_onetimeauth->keygen();

Helper method to generate a random key to be used by $crypto_onetimeauth.

The length of the $key equals "KEYBYTES".

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

mac

my $mac = $crypto_onetimeauth->mac( $msg, $key );

Computes the MAC of the $msg using given $key.

The length of the $mac equals "BYTES".

NOTE: Never use this method to authenticate more than one message under the same key.

Returns Data::BytesLocker object.

verify

unless ( $crypto_onetimeauth->verify( $mac, $msg, $key ) ) {
    die "Impostor alert!";
}

Verifies the integrity and authenticity of the $msg using given $mac and $key.

Method returns true if message has been verified, false otherwise.

Multi-part API

Multi-part computation is also supported.

my $ctx = $crypto_onetimeauth->init( $key );

$ctx->update( $msgX );
$ctx->update( $msgY )->update( $msgZ, ... );

my $mac = $ctx->final();

my $msgXYZ = join('', $msgX, $msgY, $msgZ, ...);
unless ( $crypto_onetimeauth->verify( $mac, $msgXYZ, $key) ) {
    die "Impostor alert!";
}

init

my $ctx = $crypto_onetimeauth->init( $key );

Creates a context for multi-part computation using given $key generated using "keygen".

Returns Crypt::NaCl::Sodium::onetimeauth::stream object which encapsulates the computation state of the algorithm.

clone

while ( <> ) {
    $ctx->update( $_ );
    print "Line: $.: ", $ctx->clone->final->to_hex, "\n";
}

Returns a copy of $ctx object, that contains the current computation state.

update

$ctx->update( $msg, ... );

Appends its arguments to the message for which the MAC is being calculated.

Returns the $ctx object itself.

final

my $mac = $ctx->final();

Computes the final MAC of the input data.

Returns Data::BytesLocker object.

CONSTANTS

KEYBYTES

my $key_length = $crypto_onetimeauth->KEYBYTES;

Returns the length of key.

BYTES

my $mac_length = $crypto_onetimeauth->BYTES;

Returns the length of MAC.

SECURITY MODEL

crypto_onetimeauth uses Poly1305 authenticator, which is proven to meet the standard notion of unforgeability after a single message.

SEE ALSO

AUTHOR

Alex J. G. Burzyński <ajgb@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Alex J. G. Burzyński <ajgb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.