document and improve hash algorithm randomization related build options

Install was a copy of other material, made heavy reference to 5.8.x and
and didnt really document what it should have. I reworked it to be more
up to date.

1 files changed, 60 insertions, 32 deletions

diff --git a/INSTALL b/INSTALL
index c547867900..4fce90a108 100644
--- a/INSTALL
+++ b/INSTALL
@@ -336,38 +336,62 @@ and the long double support.
 
 =head3 Algorithmic Complexity Attacks on Hashes
 
-In Perls 5.8.0 and earlier it was easy to create degenerate hashes.
-Processing such hashes would consume large amounts of CPU time,
-enabling a "Denial of Service" attack against Perl.  Such hashes may be
-a problem for example for mod_perl sites, sites with Perl CGI scripts
-and web services, that process data originating from external sources.
-
-In Perl 5.8.1 a security feature was introduced to make it harder to
-create such degenerate hashes. A visible side effect of this was that
-the keys(), values(), and each() functions may return the hash elements
-in different order between different runs of Perl even with the same
-data.  It also had unintended binary incompatibility issues with
-certain modules compiled against Perl 5.8.0.
-
-In Perl 5.8.2 an improved scheme was introduced.  Hashes will return
-elements in the same order as Perl 5.8.0 by default.  On a hash by hash
-basis, if pathological data is detected during a hash key insertion,
-then that hash will switch to an alternative random hash seed.  As
-adding keys can always dramatically change returned hash element order,
-existing programs will not be affected by this, unless they
-specifically test for pre-recorded hash return order for contrived
-data. (eg the list of keys generated by C<map {"\0"x$_} 0..15> trigger
-randomisation) In effect the new implementation means that 5.8.1 scheme
-is only being used on hashes which are under attack.
-
-One can still revert to the old guaranteed repeatable order (and be
-vulnerable to attack by wily crackers) by setting the environment
-variable PERL_HASH_SEED, see L<perlrun/PERL_HASH_SEED>.  Another option
-is to add -DUSE_HASH_SEED_EXPLICIT to the compilation flags (for
-example by using C<Configure -Accflags=-DUSE_HASH_SEED_EXPLICIT>), in
-which case one has to explicitly set the PERL_HASH_SEED environment
-variable to enable the security feature, or by adding -DNO_HASH_SEED to
-the compilation flags to completely disable the randomisation feature.
+Perl 5.18 reworked the measures used to secure its hash function
+from algorithmic complexity attacks.  By default it will build with
+all of these measures enabled along with support for controlling and
+disabling them via environment variables.
+
+You can override various aspects of this feature by defining various
+symbols during configure. An example might be:
+
+    Configure -Accflags=-DPERL_HASH_FUNC_SIPHASH
+
+B<Unless stated otherwise these options are considered experimental or
+insecure and are not recommended for production use.>
+
+Perl 5.18 includes support for multiple hash functions, and changed
+the default (to ONE_AT_A_TIME_HARD), you can choose a different
+algorithm by defining one of the following symbols. Note that as of
+Perl 5.18 we can only recommend use of the default or SIPHASH. All
+the others are known to have security issues and are for research
+purposes only.
+
+    PERL_HASH_FUNC_SIPHASH
+    PERL_HASH_FUNC_SDBM
+    PERL_HASH_FUNC_DJB2
+    PERL_HASH_FUNC_SUPERFAST
+    PERL_HASH_FUNC_MURMUR3
+    PERL_HASH_FUNC_ONE_AT_A_TIME
+    PERL_HASH_FUNC_ONE_AT_A_TIME_HARD
+    PERL_HASH_FUNC_ONE_AT_A_TIME_OLD
+
+Perl 5.18 randomizes the order returned by keys(), values(), and each(),
+and allows controlling this behavior by using of the PERL_PERTURB_KEYS
+option. You can disable this option entirely with the define:
+
+    PERL_PERTURB_KEYS_DISABLED
+
+You can disable the environment variable checks and specify the type of
+key traversal randomization to be used by defining one of these:
+
+    PERL_PERTURB_KEYS_RANDOM
+    PERL_PERTURB_KEYS_DETERMINISTIC
+
+In Perl 5.18 the seed used for the hash function is randomly selected
+at process start which can be overriden by specifing a seed by setting
+the PERL_HASH_SEED environment variable.
+
+You can change this behavior by building perl with the
+
+   USE_HASH_SEED_EXPLICIT
+
+define, in which case one has to explicitly set the PERL_HASH_SEED
+environment variable to enable the security feature or by adding
+
+    NO_HASH_SEED
+
+to the compilation flags to completely disable the randomisation feature.
+Note these modes are poorly tested, insecure and not recommended.
 
 B<Perl has never guaranteed any ordering of the hash keys>, and the
 ordering has already changed several times during the lifetime of Perl
@@ -378,6 +402,10 @@ between different runs of Perl, since Data::Dumper by default dumps
 hashes "unordered".  The use of the Data::Dumper C<Sortkeys> option is
 recommended.
 
+See L<perlrun/PERL_HASH_SEED> and L<perlrun/PERL_PERTURB_KEYS> for details on
+the environment variables, and L<perlsec/Algorithmic Complexity Attacks> for
+further security details.
+
 =head3 SOCKS
 
 Perl can be configured to be 'socksified', that is, to use the SOCKS