]>
Commit | Line | Data |
---|---|---|
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 |