2 *--------------------------------------------------------------------------------------
3 * The "hash seed" feature was added in Perl 5.8.1 to perturb the results
4 * to avoid "algorithmic complexity attacks".
6 * If USE_HASH_SEED is defined, hash randomisation is done by default
7 * If USE_HASH_SEED_EXPLICIT is defined, hash randomisation is done
8 * only if the environment variable PERL_HASH_SEED is set.
9 * (see also perl.c:perl_parse() and S_init_tls_and_interp() and util.c:get_hash_seed())
12 #ifndef PERL_SEEN_HV_FUNC_H /* compile once */
13 #define PERL_SEEN_HV_FUNC_H
16 || defined(PERL_HASH_FUNC_SIPHASH) \
17 || defined(PERL_HASH_FUNC_SDBM) \
18 || defined(PERL_HASH_FUNC_DJB2) \
19 || defined(PERL_HASH_FUNC_SUPERFAST) \
20 || defined(PERL_HASH_FUNC_MURMUR3) \
21 || defined(PERL_HASH_FUNC_ONE_AT_A_TIME) \
22 || defined(PERL_HASH_FUNC_ONE_AT_A_TIME_HARD) \
23 || defined(PERL_HASH_FUNC_ONE_AT_A_TIME_OLD) \
25 #define PERL_HASH_FUNC_ONE_AT_A_TIME_HARD
28 #if defined(PERL_HASH_FUNC_SIPHASH)
29 # define PERL_HASH_FUNC "SIPHASH_2_4"
30 # define PERL_HASH_SEED_BYTES 16
31 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_siphash_2_4((seed),(U8*)(str),(len))
32 #elif defined(PERL_HASH_FUNC_SUPERFAST)
33 # define PERL_HASH_FUNC "SUPERFAST"
34 # define PERL_HASH_SEED_BYTES 4
35 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_superfast((seed),(U8*)(str),(len))
36 #elif defined(PERL_HASH_FUNC_MURMUR3)
37 # define PERL_HASH_FUNC "MURMUR3"
38 # define PERL_HASH_SEED_BYTES 4
39 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_murmur3((seed),(U8*)(str),(len))
40 #elif defined(PERL_HASH_FUNC_DJB2)
41 # define PERL_HASH_FUNC "DJB2"
42 # define PERL_HASH_SEED_BYTES 4
43 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_djb2((seed),(U8*)(str),(len))
44 #elif defined(PERL_HASH_FUNC_SDBM)
45 # define PERL_HASH_FUNC "SDBM"
46 # define PERL_HASH_SEED_BYTES 4
47 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_sdbm((seed),(U8*)(str),(len))
48 #elif defined(PERL_HASH_FUNC_ONE_AT_A_TIME_HARD)
49 # define PERL_HASH_FUNC "ONE_AT_A_TIME_HARD"
50 # define PERL_HASH_SEED_BYTES 8
51 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_one_at_a_time_hard((seed),(U8*)(str),(len))
52 #elif defined(PERL_HASH_FUNC_ONE_AT_A_TIME)
53 # define PERL_HASH_FUNC "ONE_AT_A_TIME"
54 # define PERL_HASH_SEED_BYTES 4
55 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_one_at_a_time((seed),(U8*)(str),(len))
56 #elif defined(PERL_HASH_FUNC_ONE_AT_A_TIME_OLD)
57 # define PERL_HASH_FUNC "ONE_AT_A_TIME_OLD"
58 # define PERL_HASH_SEED_BYTES 4
59 # define PERL_HASH_WITH_SEED(seed,hash,str,len) (hash)= S_perl_hash_old_one_at_a_time((seed),(U8*)(str),(len))
62 #ifndef PERL_HASH_WITH_SEED
63 #error "No hash function defined!"
65 #ifndef PERL_HASH_SEED_BYTES
66 #error "PERL_HASH_SEED_BYTES not defined"
68 #ifndef PERL_HASH_FUNC
69 #error "PERL_HASH_FUNC not defined"
72 #ifndef PERL_HASH_SEED
73 # if defined(USE_HASH_SEED) || defined(USE_HASH_SEED_EXPLICIT)
74 # define PERL_HASH_SEED PL_hash_seed
75 # elif PERL_HASH_SEED_BYTES == 4
76 # define PERL_HASH_SEED "PeRl"
77 # elif PERL_HASH_SEED_BYTES == 16
78 # define PERL_HASH_SEED "PeRlHaShhAcKpErl"
80 # error "No PERL_HASH_SEED definition for " PERL_HASH_FUNC
84 #define PERL_HASH(hash,str,len) PERL_HASH_WITH_SEED(PERL_HASH_SEED,hash,str,len)
86 /*-----------------------------------------------------------------------------
87 * Endianess, misalignment capabilities and util macros
89 * The following 3 macros are defined in this section. The other macros defined
90 * are only needed to help derive these 3.
92 * U8TO32_LE(x) Read a little endian unsigned 32-bit int
93 * UNALIGNED_SAFE Defined if READ_UINT32 works on non-word boundaries
94 * ROTL32(x,r) Rotate x left by r bits
97 #if (defined(__GNUC__) && defined(__i386__)) || defined(__WATCOMC__) \
98 || defined(_MSC_VER) || defined (__TURBOC__)
99 #define U8TO16_LE(d) (*((const U16 *) (d)))
102 #if !defined (U8TO16_LE)
103 #define U8TO16_LE(d) ((((const U8 *)(d))[1] << 8)\
104 +((const U8 *)(d))[0])
108 /* Now find best way we can to READ_UINT32 */
109 #if (BYTEORDER == 0x1234 || BYTEORDER == 0x12345678) && U32SIZE == 4
110 /* CPU endian matches murmurhash algorithm, so read 32-bit word directly */
111 #define U8TO32_LE(ptr) (*((U32*)(ptr)))
112 #elif BYTEORDER == 0x4321 || BYTEORDER == 0x87654321
113 /* TODO: Add additional cases below where a compiler provided bswap32 is available */
114 #if defined(__GNUC__) && (__GNUC__>4 || (__GNUC__==4 && __GNUC_MINOR__>=3))
115 #define U8TO32_LE(ptr) (__builtin_bswap32(*((U32*)(ptr))))
117 /* Without a known fast bswap32 we're just as well off doing this */
118 #define U8TO32_LE(ptr) (ptr[0]|ptr[1]<<8|ptr[2]<<16|ptr[3]<<24)
119 #define UNALIGNED_SAFE
122 /* Unknown endianess so last resort is to read individual bytes */
123 #define U8TO32_LE(ptr) (ptr[0]|ptr[1]<<8|ptr[2]<<16|ptr[3]<<24)
124 /* Since we're not doing word-reads we can skip the messing about with realignment */
125 #define UNALIGNED_SAFE
130 /* This probably isn't going to work, but failing with a compiler error due to
131 lack of uint64_t is no worse than failing right now with an #error. */
132 #define U64TYPE uint64_t
136 /* Find best way to ROTL32/ROTL64 */
137 #if defined(_MSC_VER)
138 #include <stdlib.h> /* Microsoft put _rotl declaration in here */
139 #define ROTL32(x,r) _rotl(x,r)
141 #define ROTL64(x,r) _rotl64(x,r)
144 /* gcc recognises this code and generates a rotate instruction for CPUs with one */
145 #define ROTL32(x,r) (((U32)x << r) | ((U32)x >> (32 - r)))
147 #define ROTL64(x,r) (((U64TYPE)x << r) | ((U64TYPE)x >> (64 - r)))
153 #define ROTL_UV(x,r) ROTL64(x,r)
155 #define ROTL_UV(x,r) ROTL32(x,r)
158 /* This is SipHash by Jean-Philippe Aumasson and Daniel J. Bernstein.
159 * The authors claim it is relatively secure compared to the alternatives
160 * and that performance wise it is a suitable hash for languages like Perl.
163 * https://www.131002.net/siphash/
165 * This implementation seems to perform slightly slower than one-at-a-time for
166 * short keys, but degrades slower for longer keys. Murmur Hash outperforms it
167 * regardless of keys size.
174 #define U8TO64_LE(p) \
175 (((U64TYPE)((p)[0]) ) | \
176 ((U64TYPE)((p)[1]) << 8) | \
177 ((U64TYPE)((p)[2]) << 16) | \
178 ((U64TYPE)((p)[3]) << 24) | \
179 ((U64TYPE)((p)[4]) << 32) | \
180 ((U64TYPE)((p)[5]) << 40) | \
181 ((U64TYPE)((p)[6]) << 48) | \
182 ((U64TYPE)((p)[7]) << 56))
186 v0 += v1; v1=ROTL64(v1,13); v1 ^= v0; v0=ROTL64(v0,32); \
187 v2 += v3; v3=ROTL64(v3,16); v3 ^= v2; \
188 v0 += v3; v3=ROTL64(v3,21); v3 ^= v0; \
189 v2 += v1; v1=ROTL64(v1,17); v1 ^= v2; v2=ROTL64(v2,32); \
194 PERL_STATIC_INLINE U32
195 S_perl_hash_siphash_2_4(const unsigned char * const seed, const unsigned char *in, const STRLEN inlen) {
196 /* "somepseudorandomlygeneratedbytes" */
197 U64TYPE v0 = UINT64_C(0x736f6d6570736575);
198 U64TYPE v1 = UINT64_C(0x646f72616e646f6d);
199 U64TYPE v2 = UINT64_C(0x6c7967656e657261);
200 U64TYPE v3 = UINT64_C(0x7465646279746573);
203 U64TYPE k0 = ((U64TYPE*)seed)[0];
204 U64TYPE k1 = ((U64TYPE*)seed)[1];
206 const int left = inlen & 7;
207 const U8 *end = in + inlen - left;
209 b = ( ( U64TYPE )(inlen) ) << 56;
215 for ( ; in != end; in += 8 )
226 case 7: b |= ( ( U64TYPE )in[ 6] ) << 48;
227 case 6: b |= ( ( U64TYPE )in[ 5] ) << 40;
228 case 5: b |= ( ( U64TYPE )in[ 4] ) << 32;
229 case 4: b |= ( ( U64TYPE )in[ 3] ) << 24;
230 case 3: b |= ( ( U64TYPE )in[ 2] ) << 16;
231 case 2: b |= ( ( U64TYPE )in[ 1] ) << 8;
232 case 1: b |= ( ( U64TYPE )in[ 0] ); break;
246 b = v0 ^ v1 ^ v2 ^ v3;
247 return (U32)(b & U32_MAX);
249 #endif /* defined(HAS_QUAD) */
251 /* FYI: This is the "Super-Fast" algorithm mentioned by Bob Jenkins in
252 * (http://burtleburtle.net/bob/hash/doobs.html)
253 * It is by Paul Hsieh (c) 2004 and is analysed here
254 * http://www.azillionmonkeys.com/qed/hash.html
255 * license terms are here:
256 * http://www.azillionmonkeys.com/qed/weblicense.html
260 PERL_STATIC_INLINE U32
261 S_perl_hash_superfast(const unsigned char * const seed, const unsigned char *str, STRLEN len) {
262 U32 hash = *((U32*)seed) + len;
267 for (;len > 0; len--) {
268 hash += U8TO16_LE (str);
269 tmp = (U8TO16_LE (str+2) << 11) ^ hash;
270 hash = (hash << 16) ^ tmp;
271 str += 2 * sizeof (U16);
275 /* Handle end cases */
277 case 3: hash += U8TO16_LE (str);
279 hash ^= str[sizeof (U16)] << 18;
282 case 2: hash += U8TO16_LE (str);
286 case 1: hash += *str;
290 /* Force "avalanching" of final 127 bits */
296 return (hash + (hash >> 6));
300 /*-----------------------------------------------------------------------------
301 * MurmurHash3 was written by Austin Appleby, and is placed in the public
304 * This implementation was originally written by Shane Day, and is also public domain,
305 * and was modified to function as a macro similar to other perl hash functions by
308 * This is a portable ANSI C implementation of MurmurHash3_x86_32 (Murmur3A)
309 * with support for progressive processing.
311 * If you want to understand the MurmurHash algorithm you would be much better
312 * off reading the original source. Just point your browser at:
313 * http://code.google.com/p/smhasher/source/browse/trunk/MurmurHash3.cpp
317 * We can only process entire 32 bit chunks of input, except for the very end
318 * that may be shorter.
320 * To handle endianess I simply use a macro that reads a U32 and define
321 * that macro to be a direct read on little endian machines, a read and swap
322 * on big endian machines, or a byte-by-byte read if the endianess is unknown.
326 /*-----------------------------------------------------------------------------
327 * Core murmurhash algorithm macros */
329 #define MURMUR_C1 (0xcc9e2d51)
330 #define MURMUR_C2 (0x1b873593)
331 #define MURMUR_C3 (0xe6546b64)
332 #define MURMUR_C4 (0x85ebca6b)
333 #define MURMUR_C5 (0xc2b2ae35)
335 /* This is the main processing body of the algorithm. It operates
336 * on each full 32-bits of input. */
337 #define MURMUR_DOBLOCK(h1, k1) STMT_START { \
339 k1 = ROTL32(k1,15); \
343 h1 = ROTL32(h1,13); \
344 h1 = h1 * 5 + MURMUR_C3; \
348 /* Append unaligned bytes to carry, forcing hash churn if we have 4 bytes */
349 /* cnt=bytes to process, h1=name of h1 var, c=carry, n=bytes in c, ptr/len=payload */
350 #define MURMUR_DOBYTES(cnt, h1, c, n, ptr, len) STMT_START { \
351 int MURMUR_DOBYTES_i = cnt; \
352 while(MURMUR_DOBYTES_i--) { \
353 c = c>>8 | *ptr++<<24; \
356 MURMUR_DOBLOCK(h1, c); \
363 /* now we create the hash function */
364 PERL_STATIC_INLINE U32
365 S_perl_hash_murmur3(const unsigned char * const seed, const unsigned char *ptr, STRLEN len) {
366 U32 h1 = *((U32*)seed);
370 const unsigned char *end;
371 int bytes_in_carry = 0; /* bytes in carry */
372 I32 total_length= len;
374 #if defined(UNALIGNED_SAFE)
375 /* Handle carry: commented out as its only used in incremental mode - it never fires for us
378 MURMUR_DOBYTES(i, h1, carry, bytes_in_carry, ptr, len);
382 /* This CPU handles unaligned word access */
383 /* Process 32-bit chunks */
385 for( ; ptr < end ; ptr+=4) {
387 MURMUR_DOBLOCK(h1, k1);
390 /* This CPU does not handle unaligned word access */
392 /* Consume enough so that the next data byte is word aligned */
393 STRLEN i = -PTR2IV(ptr) & 3;
395 MURMUR_DOBYTES(i, h1, carry, bytes_in_carry, ptr, len);
398 /* We're now aligned. Process in aligned blocks. Specialise for each possible carry count */
400 switch(bytes_in_carry) { /* how many bytes in carry */
401 case 0: /* c=[----] w=[3210] b=[3210]=w c'=[----] */
402 for( ; ptr < end ; ptr+=4) {
404 MURMUR_DOBLOCK(h1, k1);
407 case 1: /* c=[0---] w=[4321] b=[3210]=c>>24|w<<8 c'=[4---] */
408 for( ; ptr < end ; ptr+=4) {
410 carry = U8TO32_LE(ptr);
412 MURMUR_DOBLOCK(h1, k1);
415 case 2: /* c=[10--] w=[5432] b=[3210]=c>>16|w<<16 c'=[54--] */
416 for( ; ptr < end ; ptr+=4) {
418 carry = U8TO32_LE(ptr);
420 MURMUR_DOBLOCK(h1, k1);
423 case 3: /* c=[210-] w=[6543] b=[3210]=c>>8|w<<24 c'=[654-] */
424 for( ; ptr < end ; ptr+=4) {
426 carry = U8TO32_LE(ptr);
428 MURMUR_DOBLOCK(h1, k1);
432 /* Advance over whole 32-bit chunks, possibly leaving 1..3 bytes */
435 /* Append any remaining bytes into carry */
436 MURMUR_DOBYTES(len, h1, carry, bytes_in_carry, ptr, len);
438 if (bytes_in_carry) {
439 k1 = carry >> ( 4 - bytes_in_carry ) * 8;
457 PERL_STATIC_INLINE U32
458 S_perl_hash_djb2(const unsigned char * const seed, const unsigned char *str, const STRLEN len) {
459 const unsigned char * const end = (const unsigned char *)str + len;
460 U32 hash = *((U32*)seed) + len;
462 hash = ((hash << 5) + hash) + *str++;
467 PERL_STATIC_INLINE U32
468 S_perl_hash_sdbm(const unsigned char * const seed, const unsigned char *str, const STRLEN len) {
469 const unsigned char * const end = (const unsigned char *)str + len;
470 U32 hash = *((U32*)seed) + len;
472 hash = (hash << 6) + (hash << 16) - hash + *str++;
477 /* - ONE_AT_A_TIME_HARD is the 5.17+ recommend ONE_AT_A_TIME algorithm
478 * - ONE_AT_A_TIME_OLD is the unmodified 5.16 and older algorithm
479 * - ONE_AT_A_TIME is a 5.17+ tweak of ONE_AT_A_TIME_OLD to
480 * prevent strings of only \0 but different lengths from colliding
482 * Security-wise, from best to worst,
483 * ONE_AT_A_TIME_HARD > ONE_AT_A_TIME > ONE_AT_A_TIME_OLD
484 * There is a big drop-off in security between ONE_AT_A_TIME_HARD and
488 /* This is the "One-at-a-Time" algorithm by Bob Jenkins
489 * from requirements by Colin Plumb.
490 * (http://burtleburtle.net/bob/hash/doobs.html)
491 * With seed/len tweak.
493 PERL_STATIC_INLINE U32
494 S_perl_hash_one_at_a_time(const unsigned char * const seed, const unsigned char *str, const STRLEN len) {
495 const unsigned char * const end = (const unsigned char *)str + len;
496 U32 hash = *((U32*)seed) + len;
499 hash += (hash << 10);
503 hash ^= (hash >> 11);
504 return (hash + (hash << 15));
507 /* Derived from "One-at-a-Time" algorithm by Bob Jenkins */
508 PERL_STATIC_INLINE U32
509 S_perl_hash_one_at_a_time_hard(const unsigned char * const seed, const unsigned char *str, const STRLEN len) {
510 const unsigned char * const end = (const unsigned char *)str + len;
511 U32 hash = *((U32*)seed) + len;
514 hash += (hash << 10);
519 hash += (hash << 10);
523 hash += (hash << 10);
527 hash += (hash << 10);
531 hash += (hash << 10);
535 hash += (hash << 10);
539 hash ^= (hash >> 11);
540 return (hash + (hash << 15));
543 PERL_STATIC_INLINE U32
544 S_perl_hash_old_one_at_a_time(const unsigned char * const seed, const unsigned char *str, const STRLEN len) {
545 const unsigned char * const end = (const unsigned char *)str + len;
546 U32 hash = *((U32*)seed);
549 hash += (hash << 10);
553 hash ^= (hash >> 11);
554 return (hash + (hash << 15));
557 /* legacy - only mod_perl should be doing this. */
558 #ifdef PERL_HASH_INTERNAL_ACCESS
559 #define PERL_HASH_INTERNAL(hash,str,len) PERL_HASH(hash,str,len)
562 #endif /*compile once*/
566 * c-indentation-style: bsd
568 * indent-tabs-mode: nil
571 * ex: set ts=8 sts=4 sw=4 et: