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

2 files changed, 48 insertions, 18 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index c67e831035..050e2d5490 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1650,11 +1650,16 @@ this a syntax error.  When called in scalar context, returns only the key
 (not the value) in a hash, or the index in an array.
 
 Hash entries are returned in an apparently random order.  The actual random
-order is subject to change in future versions of Perl, but it is
-guaranteed to be in the same order as either the C<keys> or C<values>
-function would produce on the same (unmodified) hash.  Since Perl
-5.8.2 the ordering can be different even between different runs of Perl
-for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
 
 After C<each> has returned all entries from the hash or array, the next
 call to C<each> returns the empty list in list context and C<undef> in
@@ -3106,13 +3111,17 @@ named hash, or in Perl 5.12 or later only, the indices of an array.  Perl
 releases prior to 5.12 will produce a syntax error if you try to use an
 array argument.  In scalar context, returns the number of keys or indices.
 
-The keys of a hash are returned in an apparently random order.  The actual
-random order is subject to change in future versions of Perl, but it
-is guaranteed to be the same order as either the C<values> or C<each>
-function produces (given that the hash has not been modified).  Since
-Perl 5.8.1 the ordering can be different even between different runs of
-Perl for security reasons (see L<perlsec/"Algorithmic Complexity
-Attacks">).
+Hash entries are returned in an apparently random order.  The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
 
 As a side effect, calling keys() resets the internal iterator of the HASH or
 ARRAY (see L</each>).  In particular, calling keys() in void context resets
@@ -8618,12 +8627,17 @@ hash.  In Perl 5.12 or later only, will also return a list of the values of
 an array; prior to that release, attempting to use an array argument will
 produce a syntax error.  In scalar context, returns the number of values.
 
-When called on a hash, the values are returned in an apparently random
-order.  The actual random order is subject to change in future versions of
-Perl, but it is guaranteed to be the same order as either the C<keys> or
-C<each> function would produce on the same (unmodified) hash.  Since Perl
-5.8.1 the ordering is different even between different runs of Perl for
-security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+Hash entries are returned in an apparently random order.  The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
 
 As a side effect, calling values() resets the HASH or ARRAY's internal
 iterator, see L</each>.  (In particular, calling values() in void context
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