NAME

Crypt::Nettle::Hash - Perl interface to cryptographic digests from libnettle

SYNOPSIS

  use Crypt::Nettle::Hash;

  my $digest = Crypt::Nettle::Hash->new('sha1');
  $digest->update('abc123');
  my $output = $digest->digest();
  printf("sha1: %s\n", unpack('H*', $output));

ABSTRACT

Crypt::Nettle::Hash provides an object interface to cryptographic digests from the nettle C library.

BASIC OPERATIONS

algos_available()

Get a list of strings that refer to the digests this perl module knows how to coax out of libnettle:

 my @algos = Crypt::Nettle::Hash::algos_available();

hash_data($algo, $data)

This is a convenience function to avoid needing to create digest contexts.

 my $hash = Crypt::Nettle::Hash::hash_data('sha1', $buffer);

hmac_data($algo, $data, $key)

This is a convenience function to avoid needing to create digest contexts.

 my $hmac = Crypt::Nettle::Hash::hmac_data('sha1', $buffer, $key);

DIGEST CONTEXT CREATION

new($algo)

Create a new digest context:

  my $digest = Crypt::Nettle::Hash->new('sha1');

The parameter $algo must be the name of a digest algorithm supported by libnettle.

On error, will return undefined.

Supported digest algorithms are: md2, md4, md5, sha1, sha224, sha256, sha384, and sha512 (you can retrieve these programmatically with algos_available()).

new_hmac($algo, $key)

Create a new HMAC digest context using a given key:

  my $digest = Crypt::Nettle::Hash->new_hmac('sha1', 'akeY$wkxEYS9d2MaW_ge');

It is recommended that you use a key of the same size as the digest_length() of the chosen digest algorithm.

copy()

Copy an existing Crypt::Nettle::Hash object, including its internal state:

  my $new_digest = $digest->copy();

On error, will return undefined.

HASH CONTEXT OPERATION

update($data)

Pass data into the digest context:

  $digest->update($data);

$data is expected to be a string. You can call this function as many times as needed on a $digest object, it will produce a digest over everything fed to it since its creation.

digest()

Return the completed digest over the concatenation of all data passed to update():

  $output = $digest->digest();

This will also resets the state to be the same as when it was created. If you want to see the current hash value without resetting the context state, you should do:

  $output = $digest->copy()->digest();

DIGEST DETAILS

is_hmac()

Returns non-zero if this digest context is an HMAC digest context:

  printf("Is HMAC: %s\n", ($digest->is_hmac() ? 'yes' : 'no'));

name()

Return the name of the digest algorithm:

  printf("Digest Algorithm: %s\n", $digest->name());

digest_size()

Return the size (in bytes) of the digest produced by a digest algorithm. This can be called either on digest context, or just by passing the name of an algorithm to the module directly:

  printf("Digest size: %d\n", $digest->digest_size());

or

  printf("Digest size: %d\n", Crypt::Nettle::Hash->digest_size('sha1'));

block_size()

Return the internal block size (in bytes) of a digest algorithm. This can be called either on digest context, or just by passing the name of an algorithm to the module directly:

  printf("Block size: %d\n", $digest->block_size());

or

  printf("Block size: %d\n", Crypt::Nettle::Hash->block_size('sha1'));

BUGS AND FEEDBACK

Crypt::Nettle::Hash has no known bugs, mostly because no one has found them yet. Please write mail to the maintainer (dkg@fifthhorseman.net) with your contributions, comments, suggestions, bug reports or complaints.

AUTHORS AND CONTRIBUTORS

Daniel Kahn Gillmor <dkg@fifthhorseman.net>

COPYRIGHT AND LICENSE

Copyright © Daniel Kahn Gillmor

Crypt::Nettle::Hash is free software, you may redistribute it and/or modify it under the GPL version 2 or later (your choice). Please see the COPYING file for the full text of the GPL.

ACKNOWLEDGEMENTS

This module was initially inspired by the GCrypt.pm bindings made by Alessandro Ranellucci.

DISCLAIMER

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

cpanm Crypt::Nettle

perl -MCPAN -e shell
install Crypt::Nettle