lib/Digest/HighwayHash.pm

   1 package Digest::HighwayHash;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6 use parent qw/Exporter/;
   7
   8 our @EXPORT_OK = qw/highway_hash64 highway_hash128 highway_hash256/;
   9 our @EXPORT = @EXPORT_OK;
  10
  11 our $VERSION = '0.001001';
  12
  13 use Math::Int64;
  14
  15 require XSLoader;
  16 XSLoader::load('Digest::HighwayHash', $VERSION);
  17
  18 1;
  19 __END__
  20
  21 =encoding utf-8
  22
  23 =head1 NAME
  24
  25 Digest::HighwayHash - XS fast strong keyed hash function
  26
  27 =head1 SYNOPSIS
  28
  29   use Digest::HighwayHash;
  30   say highway_hash64 [1, 2, 3, 4], 'hello';
  31   # 11956820856122239241
  32   say join ' ', @{highway_hash128([1, 2, 3, 4], 'hello')};
  33   # 3048112761216189476 13900443277579286659
  34   say join ' ', @{highway_hash256([1, 2, 3, 4], 'hello')};
  35   # 8099666330974151427 17027479935588128037 4015249936799013189 10027181291351549853
  36
  37   my $state = Digest::HighwayHash->new([1, 2, 3, 4]);
  38   $state->append('he');
  39   $state->append('llo');
  40   say join ' ', @{$state->finish128};
  41   # 3048112761216189476 13900443277579286659
  42
  43 =head1 DESCRIPTION
  44
  45 HighwayHash is a fast and strong keyed hash function, documented at
  46 L<https://github.com/google/highwayhash>.
  47
  48 This module has a procedural interface (used to hash an entire
  49 message) and an OO interface (used to hash a message bit by bit). The
  50 procedural interface is made of three functions, all exported by
  51 default:
  52
  53 =over
  54
  55 =item B<highway_hash64> I<\@key>, I<$input>
  56
  57 Compute the 64-bit HighwayHash of I<$input>, using I<\@key> as a key.
  58 The key must be a 4-element arrayref, with each element either a
  59 number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is a single number or (on Perls without 64-bit numbers) a L<Math::Int64> object.
  60
  61 =item B<highway_hash128> I<\@key>, I<$input>
  62
  63 Compute the 128-bit HighwayHash of I<$input>, using I<\@key> as a key.
  64 The key must be a 4-element arrayref, with each element either a
  65 number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is an array of exactly two numbers or (on Perls without 64-bit numbers) L<Math::Int64> objects.
  66
  67 =item B<highway_hash256> I<\@key>, I<$input>
  68
  69 Compute the 256-bit HighwayHash of I<$input>, using I<\@key> as a key.
  70 The key must be a 4-element arrayref, with each element either a
  71 number or (on Perls without 64-bit numbers) a L<Math::Int64> object. The result is an array of exactly four numbers or (on Perls without 64-bit numbers) L<Math::Int64> objects.
  72
  73
  74 =back
  75
  76 The OO interface has these methods:
  77
  78 =over
  79
  80 =item Digest::HighwayHash->B<new>(I<\@key>)
  81
  82 Initialize a new C<Digest::HighwayHash> state with a given key. The
  83 B<append> method will be called with this state and parts of the
  84 message, and then one of the B<finish*> methods will be called to
  85 compute the result.
  86
  87 =item $state->B<append>(I<$input>)
  88
  89 Append I<$input> to the message to be hashed by $state.
  90
  91 =item $state->B<finish64>
  92
  93 =item $state->B<finish128>
  94
  95 =item $state->B<finish256>
  96
  97 Compute and return the 64-bit, 128-bit, or respectively 256-bit
  98 HighwayHash of this state. The return values are the same as in the
  99 procedural interface.
 100
 101 =back
 102
 103 =head1 SEE ALSO
 104
 105 L<https://github.com/google/highwayhash>
 106
 107 =head1 AUTHOR
 108
 109 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 110
 111 =head1 COPYRIGHT AND LICENSE
 112
 113 Copyright (C) 2018 by Marius Gavrilescu
 114
 115 This library is free software; you can redistribute it and/or modify
 116 it under the same terms as Perl itself, either Perl version 5.24.1 or,
 117 at your option, any later version of Perl 5 you may have available.
 118
 119
 120 =cut