The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Crypt-NaCl-Sodium-1.0.8.0
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ Crypt::NaCl::Sodium::auth

NAME

Crypt::NaCl::Sodium::auth - Secret-key message authentication (HMAC-SHA256, HMAC-SHA512, HMAC-SHA512/256 )

VERSION

version 1.0.8.0

SYNOPSIS

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

    my $crypto_auth = Crypt::NaCl::Sodium->auth();

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

    ## Alice
    ########

    # Alice generates secret key
    $key = $crypto_auth->keygen();

    # ... and shares it with Bob
    send_to( Bob => { key => $key } );

    # now Alice and Bob can start communicating

    # Alice's message to Bob
    $msg = "Hi Bob!";

    # MAC guarantees message integrity and authenticity
    $mac = $crypto_auth->mac( $msg, $key );

    # we can now send unencrypted message to Bob
    send_to( Bob => { msg => $msg } );

    # and MAC confirming that Alice has wrote it
    send_to( Bob => { mac => $mac } );

    ## Bob
    ########

    # Bob receives the secret key from Alice
    $key = receive_for( Bob => 'key' );

    # Bob is now ready to receive first message from Alice
    $msg = receive_for( Bob => 'msg' );

    # and the MAC
    $mac = receive_for( Bob => 'mac' );

    # Bob can now confirm that Alice has sent the message
    unless ( $crypto_auth->verify( $mac, $msg, $key ) ) {
        die "Impostor alert!";
    }

    # now we know that Alice is talking to us - time to reply
    $msg = "Hello Alice!";

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

    # Alice will get our reply and the MAC
    send_to( Alice => { msg => $msg } );
    send_to( Alice => { mac => $mac } );

    ## Alice
    ########

    # 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

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.

METHODS

keygen

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

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

The length of the $key equals "KEYBYTES".

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

mac

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

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

The length of the $mac equals "BYTES".

Returns Data::BytesLocker object.

verify

    unless ( $crypto_auth->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.

ADVANCED USAGE

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

HMAC-SHA-256

hmacsha256_keygen

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

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

The length of the $key256 equals "HMACSHA256_KEYBYTES".

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

hmacsha256

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

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

The length of the $mac256 equals "HMACSHA256_BYTES".

Returns Data::BytesLocker object.

hmacsha256_verify

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

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

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

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

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!";
    }

hmacsha256_init

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

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

NOTE: this function supports a key of arbitrary length. Key larger then the block size gets reduced to sha256($key).

Returns Crypt::NaCl::Sodium::auth::hmacsha256stream object which encapsulates the computation state of the HMAC-SHA-256 algorithm.

clone

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

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

update

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

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

Returns the $ctx256 object itself.

final

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

Computes the final MAC of the input data.

Returns Data::BytesLocker object.

HMAC-SHA-512

hmacsha512_keygen

    my $key512 = $crypto_auth->hmacsha512_keygen();

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

The length of the $key512 equals "HMACSHA512_KEYBYTES".

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

hmacsha512

    my $mac512 = $crypto_auth->hmacsha512( $msg, $key512 );

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

The length of the $mac512 equals "HMACSHA512_BYTES".

Returns Data::BytesLocker object.

hmacsha512_verify

    unless ( $crypto_auth->hmacsha512_verify( $mac512, $msg, $key512 ) ) {
        die "Impostor alert!";
    }

Verifies the integrity and authenticity of the $msg using given $mac512 and $key512.

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

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

Multi-part API

Multi-part computation is also supported.

    my $ctx512 = $crypto_auth->hmacsha512_init( $key );

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

    my $mac512 = $ctx512->final();

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

hmacsha512_init

    my $ctx512 = $crypto_auth->hmacsha512_init( $key );

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

NOTE: this function supports a key of arbitrary length. Key larger then the block size gets reduced to sha512($key).

Returns Crypt::NaCl::Sodium::auth::hmacsha512stream object which encapsulates the computation state of the HMAC-SHA-512 algorithm.

clone

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

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

update

    $ctx512->update( $msgX, ... );

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

Returns the $ctx512 object itself.

final

    my $mac512 = $ctx512->final();

Computes the final MAC of the input data.

Returns Data::BytesLocker object.

HMAC-SHA-512/256

hmacsha512256_keygen

    my $key512256 = $crypto_auth->hmacsha512256_keygen();

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

The length of the $key512256 equals "HMACSHA512256_KEYBYTES".

NOTE: keep the key confidential.

Returns Data::BytesLocker object.

hmacsha512256

    my $mac512256 = $crypto_auth->hmacsha512256( $msg, $key512256 );

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

The length of the $mac512256 equals "HMACSHA512256_BYTES".

Returns Data::BytesLocker object.

hmacsha512256_verify

    unless ( $crypto_auth->hmacsha512256_verify( $mac512256, $msg, $key512256 ) ) {
        die "Impostor alert!";
    }

Verifies the integrity and authenticity of the $msg using given $mac512256 and $key512256.

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

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

Multi-part API

Multi-part computation is also supported.

    my $ctx512256 = $crypto_auth->hmacsha512256_init( $key );

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

    my $mac512256 = $ctx512256->final();

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

hmacsha512256_init

    my $ctx512256 = $crypto_auth->hmacsha512256_init( $key );

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

NOTE: this function supports a key of arbitrary length. Key larger then the block size gets reduced to sha512($key).

Returns Crypt::NaCl::Sodium::auth::hmacsha512256stream object which encapsulates the computation state of the HMAC-SHA-512/256 algorithm.

clone

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

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

update

    $ctx512256->update( $msgX, ... );

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

Returns the $ctx512256 object itself.

final

    my $mac512256 = $ctx512256->final();

Computes the final MAC of the input data.

Returns Data::BytesLocker object.

CONSTANTS

KEYBYTES

    my $key_length = $crypto_auth->KEYBYTES;

Returns the length of key.

HMACSHA256_KEYBYTES

    my $key256_length = $crypto_auth->HMACSHA256_KEYBYTES;

Returns the length of key for HMAC-SHA-256 algorithm.

HMACSHA512_KEYBYTES

    my $key512_length = $crypto_auth->HMACSHA512_KEYBYTES;

Returns the length of key for HMAC-SHA-512 algorithm.

HMACSHA512256_KEYBYTES

    my $key512256_length = $crypto_auth->HMACSHA512256_KEYBYTES;

Returns the length of key for HMAC-SHA-512/256 algorithm.

BYTES

    my $mac_length = $crypto_auth->BYTES;

Returns the length of MAC.

HMACSHA256_BYTES

    my $mac256_length = $crypto_auth->HMACSHA256_BYTES;

Returns the length of MAC for HMAC-SHA-256 algorithm.

HMACSHA512_BYTES

    my $mac512_length = $crypto_auth->HMACSHA512_BYTES;

Returns the length of MAC for HMAC-SHA-512 algorithm.

HMACSHA512256_BYTES

    my $mac512256_length = $crypto_auth->HMACSHA512256_BYTES;

Returns the length of MAC for HMAC-SHA-512/256 algorithm.

SECURITY MODEL

crypto_auth does not make any promises regarding strong unforgeability; perhaps one valid authenticator can be converted into another valid authenticator for the same message. crypto_auth also does not make any promises regarding truncated unforgeability.

Default value for "HMACSHA512_KEYBYTES" is 32, while RFC4868 recommends using 64 bytes when used as authentication/integrity mechanism. The *_init() functions however support keys of any length.

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.