* Strengthen the wording in `&caution.cryptographically-insecure;`
It’s not: “should not”, it’s “must not”.
* random: Unify use of `&caution.cryptographically-insecure;`
- The warning goes last.
- It is actually applied to all functions.
* random: Completely rewrite the `&caution.cryptographically-insecure;` warning
* random: Revert indentation changes to lcg-value.xml
* random: Add description to the jumping methods of Xoshiro256StarStar
* random: Improve explanation of Xoshiro jumping
Co-authored-by: George Peter Banyard <girgias@php.net>
Co-authored-by: George Peter Banyard <girgias@php.net>
* random: Unify the short description for random_(bytes|int) with Randomizer
* random: Use imperative mood for short descriptions of engine methods
This is for consistency. The PHP manual appears to use imperative mood for the
majority of functions and all of Randomizer’s functions already too.
* random: Shorten the short description for random_int and Randomizer::getInt()
* random: Reference the corresponding Randomizer methods in random_(bytes|int)
* random: Cross-reference the Randomizer in `str_shuffle()`
* random: Cross-reference the Randomizer in `shuffle()`
* random: Cross-reference the Randomizer in `array_rand()`
* random: Cross-reference `random_bytes()` in `uniqid()`
* random: Do not cross-reference `uniqid()` in `openssl_random_pseudo_bytes()`
uniqid() really is no good alternative to *anything*. In the vast majority of
cases it is better replaced by `bin2hex(random_bytes(…))`.
* random: Replace the `mt_rand()` cross-reference in `openssl_random_pseudo_bytes()` with `random_int()`
random_int() is a CSPRNG like openssl_random_pseudo_bytes(), mt_rand() is not.
* random: Add descriptions to Randomizer::shuffleArray() and Randomizer::shuffleBytes()
* random: Move detailed explanation about the input/outputs into the respective sections for Randomizer::shuffle*()
* random: Remove openssl_random_pseudo_bytes() from caution.cryptographically-insecure
The `random_bytes()` and `random_int()` alternatives are available since since
PHP 7.0, are available by default and directly map to the OS' CSPRNG and thus
are likely more secure.
Thus this commit stops mentioning `openssl_random_pseudo_bytes()` as a possible
option any more to keep things simple for the reader.
* random: Remove `openssl_random_pseudo_bytes()` from “See Also” sections for ext/random
The reasoning as with the previous commit applies.
* hash: Replace `openssl_random_pseudo_bytes()` by `random_bytes()`
* session: Replace `openssl_random_pseudo_bytes()` by `random_bytes()`
* random: Add a description to the Engine interface
* random: Add description to the Random::generate() method
* random: Hard wrap the description for the Engine interface
* random: Hard wrap the Random::generate() error list
* random: Fix phrasing in Engine interface description
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Co-authored-by: George Peter Banyard <girgias@php.net>
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Co-authored-by: George Peter Banyard <girgias@php.net>
* random: Remove redundant “Returns” prefix from return value explanation
* random: Document Engine::generate()'s return value
* random: Document Xoshiro256StarStar::generate()'s return value
* random: Document PcgOneseq128XslRr64::generate()'s return value
* random: Document Mt19937::generate()'s return value
* random: Document Secure::generate()'s return value
* random: Document the Randomizer::$engine property
* random: Clarify the int seeding for PcgOneseq128XslRr64
This change is relevant for negative seed values.
* random: Document Mt19937::__construct()'s parameter value
* random: Add description for CryptoSafeEngine
* random: Add description for RandomError
* random: Add description for RandomException
* random: Improve phrasing for MT_RAND_PHP for Mt19937
Co-authored-by: George Peter Banyard <girgias@php.net>
* random: Explain the `$mode` parameter for Mt19937 construction with a list
Co-authored-by: George Peter Banyard <girgias@php.net>
* random: Document Randomizer::shuffleArray()'s parameter and return value
* random: Document Randomizer::shuffleBytes()' parameter and return value
* random: Document Randomizer::pickArrayKeys()' parameter and return value
* random: Unify sentence structure for integer parameter constraints
* random: Document PcgOneseq128XslRr64::jump()'s parameter and return value
* random: Add external reference links for the engines
* random: Document PcgOneseq128XslRr64::__construct()'s parameter value
* random: Document Xoshiro256StarStar::__construct()'s parameter value
* random: Fix casing of "bytes" and "bits"
* fixup! random: Document PcgOneseq128XslRr64::__construct()'s parameter value
* fixup! random: Document PcgOneseq128XslRr64::__construct()'s parameter value
* fixup! random: Document Xoshiro256StarStar::__construct()'s parameter value
* fixup! random: Document PcgOneseq128XslRr64::__construct()'s parameter value
* random: Use entities to link to the engine specifications
see php/doc-base#76
* random: Fix typo in Randomizer::getInt()'s return value description
* random: Fix Randomizer::__construct()'s default value
The parameter is nullable and the actual default value should rather be
considered `null`. `null` is then *internally* replaced with a new instance of
`Random\Engine\Secure`.
* random: Document Randomizer::__construct()'s parameters
* random: Document Randomizer::getBytes()' parameter and return value
The phrasing is adapted from and synced with `random_bytes()`.
* random: Fix classname references for CSPRNG failures
* random: Unify phrasing random_int parameter description
* random: Document Randomizer::getInt()'s parameter and return value
The phrasing is adapted from and synced with `random_int()`.
* random: Add random.engineErrors snippets
This explains that the Randomizer's methods will pass through any Throwables
thrown by the engine.
* random: Fix definition of Randomizer::$engine
* random: Improve random_int/getInt parameter descriptions
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Improve random_int return value description
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Fix link to Randomizer::$engine property
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
* random: Use `&null;` entity in Randomizer::__construct()
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
Co-authored-by: Christoph M. Becker <cmbecker69@gmx.de>
