=item PERL_HASH_SEED
X<PERL_HASH_SEED>
-(Since Perl 5.8.1.) Used to randomize Perl's internal hash function.
-To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means
-exactly the same order as in 5.8.0. "Pre-5.8.1" means, among other
-things, that hash keys will always have the same ordering between
-different runs of Perl.
+(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
+the randomization of Perl's internal hash function. The value is expressed
+in hexadecimal, and may include a leading 0x. Truncated patterns
+are treated as though they are suffixed with sufficient 0's as required.
-Most hashes by default return elements in the same order as in Perl 5.8.0.
-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.
-
-The default behaviour is to randomize unless the PERL_HASH_SEED is set.
-If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default
-behaviour is I<not> to randomize unless the PERL_HASH_SEED is set.
-
-If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses
-the pseudorandom seed supplied by the operating system and libraries.
+If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then
+a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value
+implies C<PERL_PERTURB_KEYS=2>.
B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
randomized to protect against local and remote attacks against Perl
code. By manually setting a seed, this protection may be partially or
completely lost.
-See L<perlsec/"Algorithmic Complexity Attacks"> and
+See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_PERTURB_KEYS>
L</PERL_HASH_SEED_DEBUG> for more information.
+=item PERL_PERTURB_KEYS
+X<PERL_PERTURB_KEYS>
+
+(Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys
+will be repeatable from run to run for the same PERL_HASH_SEED.
+Insertion into a hash will not change the order, except to provide
+for more space in the hash. When combined with setting PERL_HASH_SEED
+this mode is as close to pre 5.18 behavior as you can get.
+
+When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized.
+Every time a hash is inserted into the key order will change in a random
+fashion. The order may not be repeatable in a following program run
+even if the PERL_HASH_SEED has been specified. This is the default
+mode for perl.
+
+When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash
+will cause the key order to change, but in a way that is repeatable
+from program run to program run.
+
+B<NOTE:> Use of this option is considered insecure, and is intended only
+for debugging non-deterministic behavior in Perl's hash function. Do
+not use it in production.
+
+See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED>
+and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the
+key traversal mask for a specific hash by using the C<hash_traversal_mask()>
+function from L<Hash::Util>.
+
=item PERL_HASH_SEED_DEBUG
X<PERL_HASH_SEED_DEBUG>
-(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of
-the hash seed at the beginning of execution. This, combined with
-L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic
-behaviour caused by hash randomization.
+(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information
+about the hash function, seed, and what type of key traversal
+randomization is in effect at the beginning of execution. This, combined
+with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in
+debugging nondeterministic behaviour caused by hash randomization.
+
+B<Note> that any information about the hash function, especially the hash
+seed is B<sensitive information>: by knowing it, one can craft a denial-of-service
+attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks">
+for more information. B<Do not disclose the hash seed> to people who
+don't need to know it. See also C<hash_seed()> and
+C<key_traversal_mask()> in L<Hash::Util>.
+
+An example output might be:
-B<Note that the hash seed is sensitive information>: by knowing it, one
-can craft a denial-of-service attack against Perl code, even remotely;
-see L<perlsec/"Algorithmic Complexity Attacks"> for more information.
-B<Do not disclose the hash seed> to people who don't need to know it.
-See also hash_seed() in L<Hash::Util>.
+ HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
=item PERL_MEM_LOG
X<PERL_MEM_LOG>
https://perl5.git.perl.org / perl5.git / blobdiff