NAME

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

VERSION

version 1.0.7.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.

AUTHOR

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

COPYRIGHT AND LICENSE

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

To install Crypt::NaCl::Sodium, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::NaCl::Sodium

CPAN shell

perl -MCPAN -e shell
install Crypt::NaCl::Sodium

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

keygen

mac

verify

ADVANCED USAGE

HMAC-SHA-256

hmacsha256_keygen

hmacsha256

hmacsha256_verify

Multi-part API

hmacsha256_init

clone

update

final

HMAC-SHA-512

hmacsha512_keygen

hmacsha512

hmacsha512_verify

Multi-part API

hmacsha512_init

clone

update

final

HMAC-SHA-512/256

hmacsha512256_keygen

hmacsha512256

hmacsha512256_verify

Multi-part API

hmacsha512256_init

clone

update

final

CONSTANTS

KEYBYTES

HMACSHA256_KEYBYTES

HMACSHA512_KEYBYTES

HMACSHA512256_KEYBYTES

BYTES

HMACSHA256_BYTES

HMACSHA512_BYTES

HMACSHA512256_BYTES

SECURITY MODEL

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions