NAME

Crypt::Sodium::XS::auth - Secret key message authentication

SYNOPSIS

use Crypt::Sodium::XS;

my $auth = Crypt::Sodium::XS->auth;

my $key = $auth->keygen;
my $msg = "authenticate this message";

my $tag = $auth->auth($msg, $key);
die "message tampered with!" unless $auth->verify($tag, $msg, $key);

my $multipart = $auth->init($key);
$multipart->update("authenticate");
$multipart->update(" this", " message");
$tag = $multipart->final;
die "message tampered with!" unless $auth->verify($tag, $msg, $key);

DESCRIPTION

Crypt::Sodium::XS::auth computes an authentication tag for a message and a secret key, and provides a way to verify that a given tag is valid for a given message and a key.

The function computing the tag is deterministic: the same ($message, $key) tuple will always produce the same output. However, even if the message is public, knowing the key is required in order to be able to compute a valid tag. Therefore, the key should remain confidential. The tag, however, can be public.

A typical use case is:

* Alice prepares a message, adds an authentication tag, sends it to Bob

* Alice doesn't store the message

* Later on, Bob sends the message and the authentication tag back to Alice

* Alice uses the authentication tag to verify that she created this message

Crypt::Sodium::XS::auth does not encrypt the message. It only computes and verifies an authentication tag.

CONSTRUCTOR

The constructor is called with the Crypt::Sodium::XS->auth method.

my $auth = Crypt::Sodium::XS->auth;
my $auth = Crypt::Sodium::XS->auth(primitive => 'hmacsha256');

Returns a new auth object.

Implementation detail: the returned object is blessed into Crypt::Sodium::XS::OO::auth.

ATTRIBUTES

primitive

my $primitive = $auth->primitive;
$auth->primitive('hmacsha256');

Gets or sets the primitive used for all operations by this object. It must be one of the primitives listed in "PRIMITIVES", including default.

METHODS

primitives

my @primitives = $auth->primitives;
my @primitives = Crypt::Sodium::XS::auth->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $auth->PRIMITIVE;

Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.

auth

my $tag = $auth->auth($message, $key);

$message is the message to authenticate. It may be a Crypt::Sodium::XS::MemVault.

$key is the secret key with which to generate the authentication tag. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns the authentication tag. The tag is "BYTES" bytes.

init

my $multipart = $auth->init($key, $flags);

$key is the secret key used by the multipart object. It should be at least "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$flags is optional. It is the flags used for the multipart protected memory object. See Crypt::Sodium::XS::ProtMem.

Returns an opaque protected memory object: a multi-part auth object. This is useful when authenticating a stream or large message in chunks, rather than in one message. See "MULTI-PART INTERFACE".

Note: The multipart interface may use arbitrary-size keys. This is not recommended as it can be easily misused (e.g., accidentally using an empty key). Avoid by always using keys of "KEYBYTES" bytes as returned by "keygen".

keygen

my $key = $auth->keygen($flags);

$flags is optional. It is the flags used for the $key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

Returns a Crypt::Sodium::XS::MemVault: a new secret key of "KEYBYTES" bytes.

verify

my $is_valid = $auth->verify($tag, $message, $key);

$tag is the previously generated authentication tag. It must be "BYTES" bytes.

$message is the message to authenticate.

$key is the secret key used to generate the authentication tag. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

Returns true if $tag is a valid tag for $message and $key, false otherwise.

BYTES

my $tag_size = $auth->BYTES;

The size, in bytes, of an authentication tag.

KEYBYTES

my $key_size = $auth->KEYBYTES;

The size, in bytes, of a secret key.

MULTI-PART INTERFACE

A multipart auth object is created by calling the "init" method. Data to be authenticated is added by calling the "update" method of that object as many times as desired. An output tag is generated by calling its "final" method. Do not use the object after calling "final".

The multipart auth object is an opaque object which provides the following methods:

clone

my $multipart_copy = $multipart->clone;

Returns a cloned copy of the multipart auth object, duplicating its internal state.

final

my $tag = $multipart->final;

Returns a tag for $key (from "init") and all authenticated data (from "update"). The tag is "BYTES" bytes.

Once "final" has been called, the multipart object must not be used further.

update

$multipart->update(@messages);

Adds all given arguments (stringified) to authenticated data. Any argument may be a Crypt::Sodium::XS::MemVault.

PRIMITIVES

hmachsa256
hmacsha512
hmacsha512256 (default)

FUNCTIONS

The object API above is the recommended way to use this module. The functions and constants documented below can be imported instead or in addition.

Nothing is exported by default. A :default tag imports the functions and constants documented below. A separate :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES" in Crypt::Sodium::XS::auth. These tags import the auth_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

auth

auth_<primitive>

my $tag = auth($message, $key);

Same as "auth".

auth_init

auth_<primitive>_init

my $multipart = auth_init($key, $flags);

Same as "init".

auth_keygen

auth_<primitive>_keygen

my $key = auth_keygen($flags);

Same as "keygen".

auth_verify

auth_<primitive>_verify

my $is_valid = auth_verify($tag, $message, $key);

Same as "verify".

CONSTANTS

auth_PRIMITIVE

my $default_primitive = auth_PRIMITIVE();

Returns the name of the default primitive.

auth_BYTES

auth_<primitive>_BYTES

my $tag_size = auth_BYTES();

Same as "BYTES".

auth_KEYBYTES

auth_<primitive>_KEYBYTES

my $key_size = auth_KEYBYTES();

Same as "KEYBYTES".

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel #sodium on irc.perl.org.
Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

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

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

cpanm

cpanm Crypt::Sodium::XS

CPAN shell

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

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

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

ATTRIBUTES

primitive

METHODS

primitives

PRIMITIVE

auth

init

keygen

verify

BYTES

KEYBYTES

MULTI-PART INTERFACE

clone

final

update

PRIMITIVES

FUNCTIONS

auth

auth_<primitive>

auth_init

auth_<primitive>_init

auth_keygen

auth_<primitive>_keygen

auth_verify

auth_<primitive>_verify

CONSTANTS

auth_PRIMITIVE

auth_BYTES

auth_<primitive>_BYTES

auth_KEYBYTES

auth_<primitive>_KEYBYTES

SEE ALSO

FEEDBACK

AUTHOR

COPYRIGHT & LICENSE

Module Install Instructions