NAME Crypt::NaCl::Sodium - NaCl compatible modern, easy-to-use library for encryption, decryption, signatures, password hashing and more VERSION version 1.0.8.0 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'; # 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 , 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 for length: $length"; 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. NOTE: "memcmp" in Data::BytesLocker provides the same functionality. $locker->memcmp($b, $length) or die "\$locker ne \$b for length: $length"; compare 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. NOTE: "compare" in Data::BytesLocker provides the same functionality. $locker->compare($y, $length) == -1 and print "\$locker < \$y for length: $length"; 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, ...); NOTE: This function is deprecated and will be removed in next version. Please use "increment" in Data::BytesLocker. Increments an arbitrary long unsigned number(s) (in place). Function runs in constant-time for a given length of arguments and considers them to be encoded in little-endian format. 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 - libsodium AUTHOR Alex J. G. Burzyński COPYRIGHT AND LICENSE This software is copyright (c) 2015 by Alex J. G. Burzyński . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.