improve hash related documentation in perlfunc and perlsec to reflect new hash randomization logic

1 files changed, 16 insertions, 0 deletions

diff --git a/pod/perlsec.pod b/pod/perlsec.pod
index 7b3f99dd81..056e8bc549 100644
--- a/pod/perlsec.pod
+++ b/pod/perlsec.pod
@@ -477,6 +477,22 @@ new behaviour consecutive runs of Perl will order hash keys differently,
 which may confuse some applications (like Data::Dumper: the outputs of two
 different runs are no longer identical).
 
+In Perl 5.18.0 the rehash mechanism has been removed, and replaced by
+true randomization similar to that used in 5.8.1. Additionally measures
+have been taken to ensure that C<keys>, C<values>, and C<each> return items
+in a per-hash randomized order. Modifying a hash by insertion is
+guaranteed to change the iteration order. Combined with a hardened
+hash function we believe that discovery attacks on the hash seed
+are very unlikely.  This traversal randomization cannot be disabled,
+and is unaffected by the value of PERL_HASH_SEED.
+
+In addition to these measure as Perl 5.18.0 the source code includes
+multiple hash algorithms to choose from.  While we believe that the
+default perl hash is robust to attack we have included the hash function
+Siphash which at the time of release of Perl 5.18.0 is believed to be
+of cyptographic strength as a fallback option. This is not the default
+as it is much slower than the default hash.
+
 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