/ 
Crypt-Sodium-XS-0.000022
River stage zero No dependents
/ Crypt::Sodium::XS::auth

NAME

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

SYNOPSIS

use Crypt::Sodium::XS::auth ":default";

my $key = auth_keygen;
my $msg = "authenticate this message";

my $mac = auth($msg, $key);
die "message tampered with!" unless auth_verify($mac, $msg, $key);

my $multipart = auth_init($key);
$multipart->update("authenticate");
$multipart->update(" this", " message");
$mac = $multipart->final;
die "message tampered with!" unless auth_verify($mac, $msg, $key);

DESCRIPTION

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

The function computing the MAC 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 MAC. Therefore, the key should remain confidential. The MAC, however, can be public.

A typical use case is:

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

* Alice doesn't store the message

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

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

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

FUNCTIONS

Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :hmacsha256 imports auth_hmacsha256_verify. You should use at least one import tag.

auth

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

auth_init

my $multipart = auth_init($key);

Returns 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".

auth_keygen

my $key = auth_keygen();

auth_verify

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

MULTI-PART INTERFACE

NOTE: The multipart interface may use arbitrary-length keys. this is not recommended as it can be easily misused (e.g., accidentally using an empty key).

A multipart auth object is created by calling the "auth_init" function. Data to be authenticated is added by calling the "update" method of that object as many times as desired. An output mac 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 $mac = $multipart->final;

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

update

$multipart->update($message);
$multipart->update(@messages);

Adds all given arguments (stringified) to authenticated data.

CONSTANTS

auth_PRIMITIVE

my $default_primitive = auth_PRIMITIVE();

auth_BYTES

my $mac_length = auth_BYTES();

auth_KEYBYTES

my $key_length = auth_KEYBTES();

PRIMITIVES

All constants (except _PRIMITIVE) and functions have auth_<primitive>-prefixed counterparts (e.g., auth_hmacsha256_verify, auth_hmacsha512256_BYTES).

  • hmachsa256

  • hmacsha512

  • hmacsha512256

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::OO::auth
https://doc.libsodium.org/secret-key_cryptography/secret-key_authentication
https://doc.libsodium.org/advanced/hmac-sha2

FEEDBACK

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

  • IRC channel #sodium on irc.perl.org.

  • Email the author directly.

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

Copyright (c) 2022 Brad Barden. All rights reserved.

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