<?php
namespace Phalcon\Security;
/**
* Phalcon\Security\Random
*
* Secure random number generator class.
*
* Provides secure random number generator which is suitable for generating
* session key in HTTP cookies, etc.
*
* It supports following secure random number generators:
*
* - random_bytes (PHP 7)
* - libsodium
* - openssl, libressl
* - /dev/urandom
*
* `Phalcon\Security\Random` could be mainly useful for:
*
* - Key generation (e.g. generation of complicated keys)
* - Generating random passwords for new user accounts
* - Encryption systems
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* // Random binary string
* $bytes = $random->bytes();
*
* // Random hex string
* echo $random->hex(10); // a29f470508d5ccb8e289
* echo $random->hex(10); // 533c2f08d5eee750e64a
* echo $random->hex(11); // f362ef96cb9ffef150c9cd
* echo $random->hex(12); // 95469d667475125208be45c4
* echo $random->hex(13); // 05475e8af4a34f8f743ab48761
*
* // Random base62 string
* echo $random->base62(); // z0RkwHfh8ErDM1xw
*
* // Random base64 string
* echo $random->base64(12); // XfIN81jGGuKkcE1E
* echo $random->base64(12); // 3rcq39QzGK9fUqh8
* echo $random->base64(); // DRcfbngL/iOo9hGGvy1TcQ==
* echo $random->base64(16); // SvdhPcIHDZFad838Bb0Swg==
*
* // Random URL-safe base64 string
* echo $random->base64Safe(); // PcV6jGbJ6vfVw7hfKIFDGA
* echo $random->base64Safe(); // GD8JojhzSTrqX7Q8J6uug
* echo $random->base64Safe(8); // mGyy0evy3ok
* echo $random->base64Safe(null, true); // DRrAgOFkS4rvRiVHFefcQ==
*
* // Random UUID
* echo $random->uuid(); // db082997-2572-4e2c-a046-5eefe97b1235
* echo $random->uuid(); // da2aa0e2-b4d0-4e3c-99f5-f5ef62c57fe2
* echo $random->uuid(); // 75e6b628-c562-4117-bb76-61c4153455a9
* echo $random->uuid(); // dc446df1-0848-4d05-b501-4af3c220c13d
*
* // Random number between 0 and $len
* echo $random->number(256); // 84
* echo $random->number(256); // 79
* echo $random->number(100); // 29
* echo $random->number(300); // 40
*
* // Random base58 string
* echo $random->base58(); // 4kUgL2pdQMSCQtjE
* echo $random->base58(); // Umjxqf7ZPwh765yR
* echo $random->base58(24); // qoXcgmw4A9dys26HaNEdCRj9
* echo $random->base58(7); // 774SJD3vgP
* </code>
*
* This class partially borrows SecureRandom library from Ruby
*
* @link http://ruby-doc.org/stdlib-2.2.2/libdoc/securerandom/rdoc/SecureRandom.html
*/
class Random
{
/**
* Generates a random binary string
*
* The `Random::bytes` method returns a string and accepts as input an int
* representing the length in bytes to be returned.
*
* If $len is not specified, 16 is assumed. It may be larger in future.
* The result may contain any byte: "x00" - "xFF".
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* $bytes = $random->bytes();
* var_dump(bin2hex($bytes));
* // Possible output: string(32) "00f6c04b144b41fad6a59111c126e1ee"
* </code>
*
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @return string
*/
public function bytes($len = 16) {}
/**
* Generates a random hex string
*
* If $len is not specified, 16 is assumed. It may be larger in future.
* The length of the result string is usually greater of $len.
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->hex(10); // a29f470508d5ccb8e289
* </code>
*
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @return string
*/
public function hex($len = null) {}
/**
* Generates a random base58 string
*
* If $len is not specified, 16 is assumed. It may be larger in future.
* The result may contain alphanumeric characters except 0, O, I and l.
*
* It is similar to `Phalcon\Security\Random:base64` but has been modified to avoid both non-alphanumeric
* characters and letters which might look ambiguous when printed.
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->base58(); // 4kUgL2pdQMSCQtjE
* </code>
*
* @see \Phalcon\Security\Random:base64
* @link https://en.wikipedia.org/wiki/Base58
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @return string
*/
public function base58($len = null) {}
/**
* Generates a random base62 string
*
* If $len is not specified, 16 is assumed. It may be larger in future.
*
* It is similar to `Phalcon\Security\Random:base58` but has been modified to provide the largest value that can
* safely be used in URLs without needing to take extra characters into consideration because it is [A-Za-z0-9].
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->base62(); // z0RkwHfh8ErDM1xw
* </code>
*
* @see \Phalcon\Security\Random:base58
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @return string
*/
public function base62($len = null) {}
/**
* Generates a random base64 string
*
* If $len is not specified, 16 is assumed. It may be larger in future.
* The length of the result string is usually greater of $len.
* Size formula: 4 ($len / 3) and this need to be rounded up to a multiple of 4.
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->base64(12); // 3rcq39QzGK9fUqh8
* </code>
*
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @return string
*/
public function base64($len = null) {}
/**
* Generates a random URL-safe base64 string
*
* If $len is not specified, 16 is assumed. It may be larger in future.
* The length of the result string is usually greater of $len.
*
* By default, padding is not generated because "=" may be used as a URL delimiter.
* The result may contain A-Z, a-z, 0-9, "-" and "_". "=" is also used if $padding is true.
* See RFC 3548 for the definition of URL-safe base64.
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->base64Safe(); // GD8JojhzSTrqX7Q8J6uug
* </code>
*
* @link https://www.ietf.org/rfc/rfc3548.txt
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param int $len
* @param bool $padding
* @return string
*/
public function base64Safe($len = null, $padding = false) {}
/**
* Generates a v4 random UUID (Universally Unique IDentifier)
*
* The version 4 UUID is purely random (except the version). It doesn't contain meaningful
* information such as MAC address, time, etc. See RFC 4122 for details of UUID.
*
* This algorithm sets the version number (4 bits) as well as two reserved bits.
* All other bits (the remaining 122 bits) are set using a random or pseudorandom data source.
* Version 4 UUIDs have the form xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where x is any hexadecimal
* digit and y is one of 8, 9, A, or B (e.g., f47ac10b-58cc-4372-a567-0e02b2c3d479).
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->uuid(); // 1378c906-64bb-4f81-a8d6-4ae1bfcdec22
* </code>
*
* @link https://www.ietf.org/rfc/rfc4122.txt
* @throws Exception If secure random number generator is not available or unexpected partial read
* @return string
*/
public function uuid() {}
/**
* Generates a random number between 0 and $len
*
* Returns an integer: 0 <= result <= $len.
*
* <code>
* $random = new \Phalcon\Security\Random();
*
* echo $random->number(16); // 8
* </code>
*
* @throws Exception If secure random number generator is not available, unexpected partial read or $len <= 0
* @param int $len
* @return int
*/
public function number($len) {}
/**
* Generates a random string based on the number ($base) of characters ($alphabet).
*
* If $n is not specified, 16 is assumed. It may be larger in future.
*
* @throws Exception If secure random number generator is not available or unexpected partial read
* @param string $alphabet
* @param int $base
* @param mixed $n
* @return string
*/
protected function base($alphabet, $base, $n = null) {}
}
网友评论