NAME
   Crypt::NaCl::Sodium - NaCl compatible modern, easy-to-use library for
   encryption, decryption, signatures, password hashing and more

VERSION
   version 1.0.6.1

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

       my $crypto = Crypt::NaCl::Sodium->new();

       ##########################
       ## Secret-key cryptography

       # Secret-key authenticated encryption (XSalsa20/Poly1305 MAC)
       my $crypto_secretbox = $crypto->secretbox();

       # Secret-key message authentication (HMAC-SHA256, HMAC-SHA512, HMAC-SHA512/256 )
       my $crypto_auth = $crypto->auth();

       # Authenticated Encryption with Additional Data (ChaCha20/Poly1305 MAC, AES256-GCM)
       my $crypto_aead = $crypto->aead();

       ##########################
       ## Public-key cryptography

       # Public-key authenticated encryption (Curve25519/XSalsa20/Poly1305 MAC)
       my $crypto_box = $crypto->box();

       # Public-key signatures (Ed25519)
       my $crypto_sign = $crypto->sign();

       ##########################
       ## Hashing

       # Generic hashing (Blake2b)
       my $crypto_generichash = $crypto->generichash();

       # Short-input hashing (SipHash-2-4)
       my $crypto_shorthash = $crypto->shorthash();

       ##########################
       ## Password hashing (yescrypt)

       my $crypto_pwhash = $crypto->pwhash();

       ##########################
       ## Advanced

       # SHA-2 (SHA-256, SHA-512)
       my $crypto_hash = $crypto->hash();

       # One-time authentication (Poly1305)
       my $crypto_onetimeauth = $crypto->onetimeauth();

       # Diffie-Hellman (Curve25519)
       my $crypto_scalarmult = $crypto->scalarmult();

       # Stream ciphers (XSalsa20, ChaCha20, Salsa20, AES-128-CTR)
       my $crypto_stream = $crypto->stream();

       ##########################
       ## Utilities

       # convert binary data to hexadecimal
       my $hex = bin2hex($bin);

       # convert hexadecimal to binary
       my $bin = hex2bin($hex);

       # constant time comparision of strings
       memcmp($a, $b, $length ) or die '$a ne $b';

       # constant time comparision of large numbers
       compare($x, $y, $length ) == -1 and print '$x < $y';

       # increment nonce
       increment($nonce);

       # overwrite with null bytes
       memzero($a, $b, ...);

       # generate random number
       my $num = random_number($upper_bound);

       # generate random bytes
       my $bytes = random_bytes($count);

       ##########################
       ## Guarded data storage

       my $locker = Data::BytesLocker->new($password);
       ...
       $locker->unlock();
       print $locker->to_hex();
       $locker->lock();

DESCRIPTION
   Crypt::NaCl::Sodium provides bindings to libsodium - NaCl compatible
   modern, easy-to-use library for encryption, decryption, signatures,
   password hashing and more.

   It is a portable, cross-compilable, installable, packageable fork of
   NaCl <http://nacl.cr.yp.to/>, with a compatible API, and an extended API
   to improve usability even further.

   Its goal is to provide all of the core operations needed to build
   higher-level cryptographic tools.

   The design choices emphasize security, and "magic constants" have clear
   rationales.

   And despite the emphasis on high security, primitives are faster
   across-the-board than most implementations of the NIST standards.

   Crypt::NaCl::Sodium uses Alien::Sodium that tracks the most current
   releases of libsodium.

METHODS
 new
       my $crypto = Crypt::NaCl::Sodium->new();

   Returns a proxy object for methods provided below.

 secretbox
       # Secret-key authenticated encryption (XSalsa20/Poly1305 MAC)
       my $crypto_secretbox = Crypt::NaCl::Sodium->secretbox();

   Read Crypt::NaCl::Sodium::secretbox for more details.

 auth
       # Secret-key authentication (HMAC-SHA512/256 and advanced usage of HMAC-SHA-2)
       my $crypto_auth = Crypt::NaCl::Sodium->auth();

   Read Crypt::NaCl::Sodium::auth for more details.

 aead
       # Authenticated Encryption with Additional Data (ChaCha20/Poly1305 MAC, AES256-GCM)
       my $crypto_aead = Crypt::NaCl::Sodium->aead();

   Read Crypt::NaCl::Sodium::aead for more details.

 box
       # Public-key authenticated encryption (Curve25519/XSalsa20/Poly1305 MAC)
       my $crypto_box = Crypt::NaCl::Sodium->box();

   Read Crypt::NaCl::Sodium::box for more details.

 sign
       # Public-key signatures (Ed25519)
       my $crypto_sign = Crypt::NaCl::Sodium->sign();

   Read Crypt::NaCl::Sodium::sign for more details.

 generichash
       # Generic hashing (Blake2b)
       my $crypto_generichash = Crypt::NaCl::Sodium->generichash();

   Read Crypt::NaCl::Sodium::generichash for more details.

 shorthash
       # Short-input hashing (SipHash-2-4)
       my $crypto_shorthash = Crypt::NaCl::Sodium->shorthash();

   Read Crypt::NaCl::Sodium::shorthash for more details.

 pwhash
       # Password hashing (yescrypt)
       my $crypto_pwhash = Crypt::NaCl::Sodium->pwhash();

   Read Crypt::NaCl::Sodium::pwhash for more details.

 hash
       # SHA-2 (SHA-256, SHA-512)
       my $crypto_hash = Crypt::NaCl::Sodium->hash();

   Read Crypt::NaCl::Sodium::hash for more details.

 onetimeauth
       # One-time authentication (Poly1305)
       my $crypto_onetimeauth = Crypt::NaCl::Sodium->onetimeauth();

   Read Crypt::NaCl::Sodium::onetimeauth for more details.

 scalarmult
       # Diffie-Hellman (Curve25519)
       my $crypto_scalarmult = Crypt::NaCl::Sodium->scalarmult();

   Read Crypt::NaCl::Sodium::scalarmult for more details.

 stream
       # Stream ciphers (XSalsa20, ChaCha20, Salsa20, AES-128-CTR)
       my $crypto_stream = Crypt::NaCl::Sodium->stream();

   Read Crypt::NaCl::Sodium::stream for more details.

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

   Imports all provided functions.

 bin2hex
       my $hex = bin2hex($bin);

   Returns converted $bin into a hexadecimal string.

 hex2bin
       my $hex = "41 : 42 : 43";
       my $bin = hex2bin($hex, ignore => ": ", max_len => 2 );
       print $bin; # AB

   Parses a hexadecimal string $hex and converts it to a byte sequence.

   Optional arguments:

   *   ignore

       A string of characters to skip. For example, the string ": " allows
       columns and spaces to be present at any locations in the hexadecimal
       string. These characters will just be ignored.

       If unset any non-hexadecimal characters are disallowed.

   *   max_len

       The maximum number of bytes to return.

   The parser stops when a non-hexadecimal, non-ignored character is found
   or when "max_len" bytes have been written.

 memcmp
       memcmp($a, $b, $length ) or die '$a ne $b';

   Compares strings in constant-time. Returns true if they match, false
   otherwise.

   The argument $length is optional if variables are of the same length.
   Otherwise it is required and cannot be greater then the length of the
   shorter of compared variables.

 compare
       # constant time comparision of large numbers
       compare($x, $y, $length ) == -1 and print '$x < $y';

   A constant-time version of "memcmp", useful to compare nonces and
   counters in little-endian format, that plays well with "increment".

   Returns -1 if $x is lower then $y, 0 if $x and $y are identical, or 1 if
   $x is greater then $y. Both $x and $y are assumed to be numbers encoded
   in little-endian format.

   The argument $length is optional if variables are of the same length.
   Otherwise it is required and cannot be greater then the length of the
   shorter of compared variables.

 memzero
       memzero($a, $b, ...);

   Replaces the value of the provided stringified variables with "null"
   bytes. Length of the zeroed variables is unchanged.

 random_number
       my $num = random_number($upper_bound);

   Returns an unpredictable number between 0 and optional $upper_bound
   (excluded). If $upper_bound is not specified the maximum value is
   0xffffffff (included).

 increment
       increment($nonce);

   Increments an arbitrary long unsigned number (in place). Function runs
   in constant-time for a given length of number and considers the number
   to be encoded in little-endian format.

   This function can be used to increment nonces.

 random_bytes
       my $bytes = random_bytes($num_of_bytes);

   Generates unpredictable sequence of $num_of_bytes bytes.

   The length of the $bytes equals the value of $num_of_bytes.

   Returns Data::BytesLocker object.

VARIABLES
 $Data::BytesLocker::DEFAULT_LOCKED
       use Crypt::NaCl::Sodium;
       $Data::BytesLocker::DEFAULT_LOCKED = 1;

   By default all values returned from the provided methods are unlocked
   Data::BytesLocker objects. If this variable is set to true then the
   returned objects are locked and require calling "unlock" in
   Data::BytesLocker before accessing.

SEE ALSO
   *   Crypt::NaCl::Sodium::secretbox - Secret-key authenticated encryption
       (XSalsa20/Poly1305 MAC)

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

   *   Crypt::NaCl::Sodium::aead - Authenticated Encryption with Additional
       Data (ChaCha20/Poly1305 MAC, AES256-GCM)

   *   Crypt::NaCl::Sodium::box - Public-key authenticated encryption
       (Curve25519/XSalsa20/Poly1305 MAC)

   *   Crypt::NaCl::Sodium::sign - Public-key signatures (Ed25519)

   *   Crypt::NaCl::Sodium::generichash - Generic hashing (Blake2b)

   *   Crypt::NaCl::Sodium::shorthash - Short-input hashing (SipHash-2-4)

   *   Crypt::NaCl::Sodium::pwhash - Password hashing (yescrypt)

   *   Crypt::NaCl::Sodium::hash - SHA-2 (SHA-256, SHA-512)

   *   Crypt::NaCl::Sodium::onetimeauth - One-time authentication
       (Poly1305)

   *   Crypt::NaCl::Sodium::scalarmult - Diffie-Hellman (Curve25519)

   *   Crypt::NaCl::Sodium::stream - Stream ciphers (XSalsa20, ChaCha20,
       Salsa20, AES-128-CTR)

   *   Data::BytesLocker - guarded data storage

   *   libsodium <http://jedisct1.gitbooks.io/libsodium> - libsodium

AUTHOR
   Alex J. G. Burzyński <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2015 by Alex J. G. Burzyński
   <[email protected]>.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.