diff options
| -rw-r--r-- | pod/perlfunc.pod | 50 | ||||
| -rw-r--r-- | pod/perlsec.pod | 16 |
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 |