INSTALL didn't mention the 5.8.2 hash changes. Fixed

p4raw-id: //depot/perl@22723

1 files changed, 34 insertions, 21 deletions

diff --git a/INSTALL b/INSTALL
index 99d4c2bb62..3f4e842090 100644
--- a/INSTALL
+++ b/INSTALL
@@ -888,29 +888,42 @@ 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.
-
-Because of this feature the keys(), values(), and each() functions may
-return the hash elements in different order between different runs of
-Perl even with the same data.  One can still revert to the old
-repeatable order 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_HAS_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.
+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_HAS_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.
 
 B<Perl has never guaranteed any ordering of the hash keys>, and the
-ordering has already changed several times during the lifetime of
-Perl 5.  Also, the ordering of hash keys has always been, and
-continues to be, affected by the insertion order.
-
-Note that because of this randomisation for example the Data::Dumper
-results will be different between different runs of Perl since
-Data::Dumper by default dumps hashes "unordered".  The use of the
-Data::Dumper C<Sortkeys> option is recommended.
+ordering has already changed several times during the lifetime of Perl
+5.  Also, the ordering of hash keys has always been, and continues to
+be, affected by the insertion order.  It is likely that Perl 5.10 and
+Perl 6 will randomise all hashes.  Note that because of this
+randomisation for example the Data::Dumper results will be different
+between different runs of Perl since Data::Dumper by default dumps
+hashes "unordered".  The use of the Data::Dumper C<Sortkeys> option is
+recommended.
 
 =head2 SOCKS