Skip to content
Crypt::NaCl::Sodium - NaCl compatible modern, easy-to-use library for encryption, decryption, signatures, password hashing and more
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
inc
lib
t
.gitignore
Changes
Makefile.PL
README
Sodium.xs
dist.ini
ppport.h
typemap

README

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 <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 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 <http://jedisct1.gitbooks.io/libsodium> - libsodium

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

COPYRIGHT AND LICENSE
    This software is copyright (c) 2015 by Alex J. G. Burzyński
    <ajgb@cpan.org>.

    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 can’t perform that action at this time.