view release on metacpan or  search on metacpan

lib/Crypt/NaCl/Sodium/auth.pod  view on Meta::CPAN

    # receiving the reply
    $msg = receive_for( Alice => 'msg' );
    $mac = receive_for( Alice => 'mac' );

    # and Alice can now confirm that it is from Bob
    unless ( $crypto_auth->verify( $mac, $msg, $key ) ) {
        die "Impostor alert!";
    }

    # NOTE: send_to() and receive_for() and user functions providing transport of
    # messages


=head1 DESCRIPTION

Secret-key authentication allows to compute the authentication tag (also known
as Message Authentication Code) that verifies the integrity and authenticity of
the message to those who share the secret key.

For the same message the same key will always product the same output.

Unencrypted messages and their MACs can be made public, while the key should
remain secret.

=head1 METHODS

=head2 keygen

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

Helper method to generate a random key to be used by C<$crypto_auth>.

The length of the C<$key> equals L</KEYBYTES>.

B<NOTE:> keep the key confidential.

Returns L<Data::BytesLocker> object.

=head2 mac

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

Computes the MAC of the C<$msg> using given C<$key>.

The length of the C<$mac> equals L</BYTES>.

Returns L<Data::BytesLocker> object.

=head2 verify

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

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

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

=head1 ADVANCED USAGE

Single pass and streaming API keyed message authentication using I<HMAC-SHA-256>,
I<HMAC-SHA-512> and I<HMAC-SHA-512/256> are described below.

=head2 HMAC-SHA-256

=head3 hmacsha256_keygen

    my $key256 = $crypto_auth->hmacsha256_keygen();

Helper method to generate a random key to be used by C<$crypto_auth>.

The length of the C<$key256> equals L</HMACSHA256_KEYBYTES>.

B<NOTE:> keep the key confidential.

Returns L<Data::BytesLocker> object.

=head3 hmacsha256

    my $mac256 = $crypto_auth->hmacsha256( $msg, $key256 );

Computes the MAC of the C<$msg> using given C<$key256>.

The length of the C<$mac256> equals L</HMACSHA256_BYTES>.

Returns L<Data::BytesLocker> object.

=head3 hmacsha256_verify

    unless ( $crypto_auth->hmacsha256_verify( $mac256, $msg, $key256 ) ) {
        die "Impostor alert!";
    }

Verifies the integrity and authenticity of the C<$msg> using given C<$mac256> and
C<$key256>.

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

B<NOTE:> this function supports a key of arbitrary length, allowing it to be
used with the multi-part API.

=head3 Multi-part API

Multi-part computation is also supported.

    my $ctx256 = $crypto_auth->hmacsha256_init( $key );

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

    my $mac256 = $ctx256->final();

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

=head4 hmacsha256_init

    my $ctx256 = $crypto_auth->hmacsha256_init( $key );