| 1 | package Digest::SipHash; | ||||||||||||||||||||
| 2 | |||||||||||||||||||||
| 3 | 3 | ▶ | use 5.008001; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 4 | 3 | ▶ | use strict; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 5 | 3 | ▶ | use warnings; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 6 | |||||||||||||||||||||
| 7 | 3 | our $VERSION = sprintf "%d.%02d", q$Revision: 0.21 $ =~ /(\d+)/g; | |||||||||||||||||||
| 8 | 3 | require XSLoader; | |||||||||||||||||||
| 9 | 3 | XSLoader::load( 'Digest::SipHash', $VERSION ); | |||||||||||||||||||
| 10 | |||||||||||||||||||||
| 11 | 3 | ▶ | use base 'Exporter'; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 12 | 3 | our @EXPORT_OK = qw/siphash siphash32/; | |||||||||||||||||||
| 13 | |||||||||||||||||||||
| 14 | 3 | ▶ | use constant BIG_ENDIAN => pack( "L", 1 ) eq pack( "N", 1 ); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 15 | 3 | ▶ | use constant USE64BITINT => eval { pack 'Q', 1 }; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 16 | |||||||||||||||||||||
| 17 | 3 | push @EXPORT_OK, 'siphash64' if USE64BITINT; | |||||||||||||||||||
| 18 | 3 | our %EXPORT_TAGS = ( all => [@EXPORT_OK] ); | |||||||||||||||||||
| 19 | 3 | our $DEFAULT_SEED = pack 'C16', map { int( rand(256) ) } ( 0 .. 0xF ); | |||||||||||||||||||
| 20 | |||||||||||||||||||||
| 21 | 10 | ▶ | sub siphash { | ||||||||||||||||||
|
Subroutine
siphash: called CC=5 SCAR=16.3
Pod
documented
| |||||||||||||||||||||
| 22 | 10 | my $str = shift; | |||||||||||||||||||
| 23 | 10 | ▶ | my $seed = shift || $DEFAULT_SEED; | ||||||||||||||||||
|
Condition33%1/3
shift() || $Digest::SipHash::DEFAULT_SEED
MC/DC0%0/2
shift() || $Digest::SipHash::DEFAULT_SEED
shift()
$Digest::SipHash::DEFAULT_SEED
Truth table33%1/3
A || B
A= shift()B= $Digest::SipHash::DEFAULT_SEED
| |||||||||||||||||||||
| 24 | 10 | ▶ | unless (@_) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 25 | 9 | utf8::downgrade($str,1); | |||||||||||||||||||
| 26 | 9 | utf8::downgrade($seed,1); | |||||||||||||||||||
| 27 | } | ||||||||||||||||||||
| 28 | 3 | ▶ | use bytes; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 29 | 10 | ▶ | $seed .= substr( $DEFAULT_SEED, length($seed) ) if length($seed) < 16; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 30 | 10 | my $lohi = _xs_siphash_av( $str, $seed ); | |||||||||||||||||||
| 31 | 10 | ▶ | return wantarray ? @$lohi : $lohi->[0]; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 32 | } | ||||||||||||||||||||
| 33 | |||||||||||||||||||||
| 34 | 3 | *siphash32 = \&siphash; | |||||||||||||||||||
| 35 | |||||||||||||||||||||
| 36 | 3 | if (USE64BITINT) { | |||||||||||||||||||
| 37 | 1 | ▶ | *siphash64 = sub { | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=4 SCAR=14.4
| |||||||||||||||||||||
| 38 | 1 | my $str = shift; | |||||||||||||||||||
| 39 | 1 | ▶ | my $seed = shift || $DEFAULT_SEED; | ||||||||||||||||||
|
Condition33%1/3
shift() || $Digest::SipHash::DEFAULT_SEED
MC/DC0%0/2
shift() || $Digest::SipHash::DEFAULT_SEED
shift()
$Digest::SipHash::DEFAULT_SEED
Truth table33%1/3
A || B
A= shift()B= $Digest::SipHash::DEFAULT_SEED
| |||||||||||||||||||||
| 40 | 1 | ▶ | unless (@_) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 41 | 1 | utf8::downgrade($str,1); | |||||||||||||||||||
| 42 | 1 | utf8::downgrade($seed,1); | |||||||||||||||||||
| 43 | } | ||||||||||||||||||||
| 44 | 3 | ▶ | use bytes; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 45 | 1 | ▶ | $seed .= substr( $DEFAULT_SEED, length($seed) ) if length($seed) < 16; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 46 | 1 | return _xs_siphash64( $str, $seed ); | |||||||||||||||||||
| 47 | 3 | }; | |||||||||||||||||||
| 48 | } | ||||||||||||||||||||
| 49 | |||||||||||||||||||||
| 50 | 3 | 1; | |||||||||||||||||||
| 51 | |||||||||||||||||||||
| 52 | =head1 NAME | ||||||||||||||||||||
| 53 | |||||||||||||||||||||
| 54 | Digest::SipHash - Perl XS interface to the SipHash algorithm | ||||||||||||||||||||
| 55 | |||||||||||||||||||||
| 56 | =head1 VERSION | ||||||||||||||||||||
| 57 | |||||||||||||||||||||
| 58 | $Id: SipHash.pm,v 0.21 2020/12/11 18:05:44 dankogai Exp $ | ||||||||||||||||||||
| 59 | |||||||||||||||||||||
| 60 | =head1 SYNOPSIS | ||||||||||||||||||||
| 61 | |||||||||||||||||||||
| 62 | use Digest::SipHash qw/siphash/; | ||||||||||||||||||||
| 63 | my $seed = pack 'C16', 0 .. 0xF; # 16 chars long | ||||||||||||||||||||
| 64 | my $str = "hello world!"; | ||||||||||||||||||||
| 65 | my ( $lo, $hi ) = siphash( $str, $seed ); | ||||||||||||||||||||
| 66 | # $lo = 0x10cf32e0, $hi == 0x7da9cd17 | ||||||||||||||||||||
| 67 | my $u32 = siphash( $str, $seed ) | ||||||||||||||||||||
| 68 | # $u32 = 0x10cf32e0 | ||||||||||||||||||||
| 69 | |||||||||||||||||||||
| 70 | use Config; | ||||||||||||||||||||
| 71 | if ( $Config{use64bitint} ) { | ||||||||||||||||||||
| 72 | use Digest::SipHash qw/siphash64/; | ||||||||||||||||||||
| 73 | my $uint64 = siphash64( $str, $seed ); # scalar context; | ||||||||||||||||||||
| 74 | # $uint64 == 0x7da9cd1710cf32e0 | ||||||||||||||||||||
| 75 | } | ||||||||||||||||||||
| 76 | |||||||||||||||||||||
| 77 | =head1 DESCRIPTION | ||||||||||||||||||||
| 78 | |||||||||||||||||||||
| 79 | SipHash is the default perl hash function for 64 bit builds now. | ||||||||||||||||||||
| 80 | |||||||||||||||||||||
| 81 | L<http://perl5.git.perl.org/perl.git/commit/3db6cbfca39da94d152d3e860e2aa79b9c6bb161> | ||||||||||||||||||||
| 82 | |||||||||||||||||||||
| 83 | L<https://131002.net/siphash/> | ||||||||||||||||||||
| 84 | |||||||||||||||||||||
| 85 | This module does only one thing - culculates the SipHash value of the | ||||||||||||||||||||
| 86 | given string. | ||||||||||||||||||||
| 87 | |||||||||||||||||||||
| 88 | =head1 EXPORT | ||||||||||||||||||||
| 89 | |||||||||||||||||||||
| 90 | C<siphash()>, C<siphash32()> and C<siphash64()> on demand. | ||||||||||||||||||||
| 91 | |||||||||||||||||||||
| 92 | C<:all> to all of above | ||||||||||||||||||||
| 93 | |||||||||||||||||||||
| 94 | =head1 SUBROUTINES/METHODS | ||||||||||||||||||||
| 95 | |||||||||||||||||||||
| 96 | =head2 siphash | ||||||||||||||||||||
| 97 | |||||||||||||||||||||
| 98 | my ($hi, $lo) = siphash($str [, $seed][, $no_downgrade]); | ||||||||||||||||||||
| 99 | my $uint32 = siphash($str [, $seed][, $no_downgrade]); | ||||||||||||||||||||
| 100 | |||||||||||||||||||||
| 101 | Calculates the SipHash value of C<$src> with $<$seed>. | ||||||||||||||||||||
| 102 | |||||||||||||||||||||
| 103 | If C<$seed> is omitted, it defaults to C<$Digest:::SipHash::DEFAULT_SEED>, | ||||||||||||||||||||
| 104 | which is set randomly upon initialization of this module. | ||||||||||||||||||||
| 105 | |||||||||||||||||||||
| 106 | If C<$seed> is set but less than 16 bytes long, it is padded with C<$DEFAULT_SEED>. | ||||||||||||||||||||
| 107 | |||||||||||||||||||||
| 108 | To be compatible with 32-bit perl, It returns a pair of 32-bit | ||||||||||||||||||||
| 109 | integers instead of a 64-bit integer. Since C<Hash::Util::hash_value()> | ||||||||||||||||||||
| 110 | always returns the lower 32-bit first so that: | ||||||||||||||||||||
| 111 | |||||||||||||||||||||
| 112 | use Hash::Util qw/hash_seed hash_value/; | ||||||||||||||||||||
| 113 | use Digest::SipHash qw/siphash/; | ||||||||||||||||||||
| 114 | hash_value($str) == siphash($str, hash_seed()); # scalar context | ||||||||||||||||||||
| 115 | |||||||||||||||||||||
| 116 | always holds true when PERL_HASH_FUN_SIPHASH is in effect. | ||||||||||||||||||||
| 117 | |||||||||||||||||||||
| 118 | =head2 About Unicode | ||||||||||||||||||||
| 119 | |||||||||||||||||||||
| 120 | By default this module follows the same rules as Perl does regarding | ||||||||||||||||||||
| 121 | hashing, utf8 strings are passed to utf8::downgrade() with the $fail_ok | ||||||||||||||||||||
| 122 | flag set to true. This means that if the complete string can be downgraded | ||||||||||||||||||||
| 123 | to non-utf8 prior to hashing it will be, otherwise it will be left in | ||||||||||||||||||||
| 124 | utf8 form. This means that all strings which are string equivalent | ||||||||||||||||||||
| 125 | hash equivalently, and may not be what you want. In which case you can | ||||||||||||||||||||
| 126 | pass a third argument to the hash functions, which when true disables | ||||||||||||||||||||
| 127 | the downgrade behavior. | ||||||||||||||||||||
| 128 | |||||||||||||||||||||
| 129 | =head2 siphash32 | ||||||||||||||||||||
| 130 | |||||||||||||||||||||
| 131 | just an alias of C<siphash>. | ||||||||||||||||||||
| 132 | |||||||||||||||||||||
| 133 | =head2 siphash64 | ||||||||||||||||||||
| 134 | |||||||||||||||||||||
| 135 | my $uint64 = siphash64($str [, $seed]); | ||||||||||||||||||||
| 136 | |||||||||||||||||||||
| 137 | Calculates the SipHash value of C<$src> with C<$seed> in 64-bit. | ||||||||||||||||||||
| 138 | Available on 64-bit platforms only. | ||||||||||||||||||||
| 139 | |||||||||||||||||||||
| 140 | =head1 AUTHOR | ||||||||||||||||||||
| 141 | |||||||||||||||||||||
| 142 | Dan Kogai, C<< <dankogai+cpan at gmail.com> >> | ||||||||||||||||||||
| 143 | |||||||||||||||||||||
| 144 | =head1 BUGS | ||||||||||||||||||||
| 145 | |||||||||||||||||||||
| 146 | Please report any bugs or feature requests to C<bug-digest-siphash at rt.cpan.org>, or through | ||||||||||||||||||||
| 147 | the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Digest-SipHash>. I will be notified, and then you'll | ||||||||||||||||||||
| 148 | automatically be notified of progress on your bug as I make changes. | ||||||||||||||||||||
| 149 | |||||||||||||||||||||
| 150 | =head1 SUPPORT | ||||||||||||||||||||
| 151 | |||||||||||||||||||||
| 152 | You can find documentation for this module with the perldoc command. | ||||||||||||||||||||
| 153 | |||||||||||||||||||||
| 154 | perldoc Digest::SipHash | ||||||||||||||||||||
| 155 | |||||||||||||||||||||
| 156 | You can also look for information at: | ||||||||||||||||||||
| 157 | |||||||||||||||||||||
| 158 | =over 4 | ||||||||||||||||||||
| 159 | |||||||||||||||||||||
| 160 | =item * RT: CPAN's request tracker (report bugs here) | ||||||||||||||||||||
| 161 | |||||||||||||||||||||
| 162 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Digest-SipHash> | ||||||||||||||||||||
| 163 | |||||||||||||||||||||
| 164 | =item * AnnoCPAN: Annotated CPAN documentation | ||||||||||||||||||||
| 165 | |||||||||||||||||||||
| 166 | L<http://annocpan.org/dist/Digest-SipHash> | ||||||||||||||||||||
| 167 | |||||||||||||||||||||
| 168 | =item * CPAN Ratings | ||||||||||||||||||||
| 169 | |||||||||||||||||||||
| 170 | L<http://cpanratings.perl.org/d/Digest-SipHash> | ||||||||||||||||||||
| 171 | |||||||||||||||||||||
| 172 | =item * Search CPAN | ||||||||||||||||||||
| 173 | |||||||||||||||||||||
| 174 | L<http://search.cpan.org/dist/Digest-SipHash/> | ||||||||||||||||||||
| 175 | |||||||||||||||||||||
| 176 | =back | ||||||||||||||||||||
| 177 | |||||||||||||||||||||
| 178 | =head1 SEE ALSO | ||||||||||||||||||||
| 179 | |||||||||||||||||||||
| 180 | L<Hash::Util>, L<https://131002.net/siphash/> | ||||||||||||||||||||
| 181 | |||||||||||||||||||||
| 182 | =head1 ACKNOWLEDGEMENTS | ||||||||||||||||||||
| 183 | |||||||||||||||||||||
| 184 | B<SipHash: a fast short-input PRF> | ||||||||||||||||||||
| 185 | |||||||||||||||||||||
| 186 | by Jean-Philippe Aumasson & Daniel J. Bernstein | ||||||||||||||||||||
| 187 | |||||||||||||||||||||
| 188 | L<https://131002.net/siphash/> | ||||||||||||||||||||
| 189 | |||||||||||||||||||||
| 190 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||
| 191 | |||||||||||||||||||||
| 192 | =head2 csiphash.c | ||||||||||||||||||||
| 193 | |||||||||||||||||||||
| 194 | Copyright (c) 2013 Marek Majkowski | ||||||||||||||||||||
| 195 | |||||||||||||||||||||
| 196 | MIT License L<http://opensource.org/licenses/MIT> | ||||||||||||||||||||
| 197 | |||||||||||||||||||||
| 198 | L<https://github.com/majek/csiphash> | ||||||||||||||||||||
| 199 | |||||||||||||||||||||
| 200 | =head2 The rest of this module | ||||||||||||||||||||
| 201 | |||||||||||||||||||||
| 202 | Copyright 2013 Dan Kogai. | ||||||||||||||||||||
| 203 | |||||||||||||||||||||
| 204 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||||
| 205 | under the terms of the the Artistic License (2.0). You may obtain a | ||||||||||||||||||||
| 206 | copy of the full license at: | ||||||||||||||||||||
| 207 | |||||||||||||||||||||
| 208 | L<http://www.perlfoundation.org/artistic_license_2_0> | ||||||||||||||||||||
| 209 | |||||||||||||||||||||
| 210 | Any use, modification, and distribution of the Standard or Modified | ||||||||||||||||||||
| 211 | Versions is governed by this Artistic License. By using, modifying or | ||||||||||||||||||||
| 212 | distributing the Package, you accept this license. Do not use, modify, | ||||||||||||||||||||
| 213 | or distribute the Package, if you do not accept this license. | ||||||||||||||||||||
| 214 | |||||||||||||||||||||
| 215 | If your Modified Version has been derived from a Modified Version made | ||||||||||||||||||||
| 216 | by someone other than you, you are nevertheless required to ensure that | ||||||||||||||||||||
| 217 | your Modified Version complies with the requirements of this license. | ||||||||||||||||||||
| 218 | |||||||||||||||||||||
| 219 | This license does not grant you the right to use any trademark, service | ||||||||||||||||||||
| 220 | mark, tradename, or logo of the Copyright Holder. | ||||||||||||||||||||
| 221 | |||||||||||||||||||||
| 222 | This license includes the non-exclusive, worldwide, free-of-charge | ||||||||||||||||||||
| 223 | patent license to make, have made, use, offer to sell, sell, import and | ||||||||||||||||||||
| 224 | otherwise transfer the Package with respect to any patent claims | ||||||||||||||||||||
| 225 | licensable by the Copyright Holder that are necessarily infringed by the | ||||||||||||||||||||
| 226 | Package. If you institute patent litigation (including a cross-claim or | ||||||||||||||||||||
| 227 | counterclaim) against any party alleging that the Package constitutes | ||||||||||||||||||||
| 228 | direct or contributory patent infringement, then this Artistic License | ||||||||||||||||||||
| 229 | to you shall terminate on the date that such litigation is filed. | ||||||||||||||||||||
| 230 | |||||||||||||||||||||
| 231 | Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER | ||||||||||||||||||||
| 232 | AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. | ||||||||||||||||||||
| 233 | THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR | ||||||||||||||||||||
| 234 | PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY | ||||||||||||||||||||
| 235 | YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR | ||||||||||||||||||||
| 236 | CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR | ||||||||||||||||||||
| 237 | CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, | ||||||||||||||||||||
| 238 | EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||||||||||||||||||||
| 239 | |||||||||||||||||||||
| 240 | =cut | ||||||||||||||||||||
| 241 | |||||||||||||||||||||
| 242 | 3 | 1; # End of Digest::SipHash | |||||||||||||||||||