Bytes::Random::Secure(3pm) - phpMan

Command: man perldoc info search(apropos)  


Bytes::Random::Secure(3pm)     User Contributed Perl Documentation     Bytes::Random::Secure(3pm)

NAME
       Bytes::Random::Secure - Perl extension to generate cryptographically-secure random bytes.

SYNOPSIS
           use Bytes::Random::Secure qw(
               random_bytes random_bytes_base64 random_bytes_hex
           );

           my $bytes = random_bytes(32); # A string of 32 random bytes.

           my $bytes = random_string_from( 'abcde', 10 ); # 10 random a,b,c,d, and e's.

           my $bytes_as_base64 = random_bytes_base64(57); # Base64 encoded rand bytes.

           my $bytes_as_hex = random_bytes_hex(8); # Eight random bytes as hex digits.

           my $bytes_as_quoted_printable = random_bytes_qp(100); # QP encoded bytes.

           my $random = Bytes::Random::Secure->new(
               Bits        => 64,
               NonBlocking => 1,
           ); # Seed with 64 bits, and use /dev/urandom (or other non-blocking).

           my $bytes = $random->bytes(32); # A string of 32 random bytes.
           my $long  = $random->irand;     # 32-bit random integer.

DESCRIPTION
       Bytes::Random::Secure provides two interfaces for obtaining crypto-quality random bytes.
       The simple interface is built around plain functions.  For greater control over the Random
       Number Generator's seeding, there is an Object Oriented interface that provides much more
       flexibility.

       The "functions" interface provides functions that can be used any time you need a string
       of a specific number of random bytes.  The random bytes are available as simple strings,
       or as hex-digits, Quoted Printable, or MIME Base64.  There are equivalent methods
       available from the OO interface, plus a few others.

       This module can be a drop-in replacement for Bytes::Random, with the primary enhancement
       of using a cryptographic-quality random number generator to create the random data.  The
       "random_bytes" function emulates the user interface of Bytes::Random's function by the
       same name.  But with Bytes::Random::Secure the random number generator comes from
       Math::Random::ISAAC, and is suitable for cryptographic purposes.  The harder problem to
       solve is how to seed the generator.  This module uses Crypt::Random::Seed to generate the
       initial seeds for Math::Random::ISAAC.

       In addition to providing "random_bytes()", this module also provides several functions not
       found in Bytes::Random: "random_string_from", "random_bytes_base64()", "random_bytes_hex",
       and "random_bytes_qp".

       And finally, for those who need finer control over how Crypt::Random::Seed generates its
       seed, there is an object oriented interface with a constructor that facilitates
       configuring the seeding process, while providing methods that do everything the
       "functions" interface can do (truth be told, the functions interface is just a thin
       wrapper around the OO version, with some sane defaults selected).  The OO interface also
       provides an "irand" method, not available through the functions interface.

RATIONALE
       There are many uses for cryptographic quality randomness.  This module aims to provide a
       generalized tool that can fit into many applications while providing a minimal dependency
       chain, and a user interface that is simple.  You're free to come up with your own use-
       cases, but there are several obvious ones:

       o   Creating temporary passphrases ("random_string_from()").

       o   Generating per-account random salt to be hashed along with passphrases (and stored
           alongside them) to prevent rainbow table attacks.

       o   Generating a secret that can be hashed along with a cookie's session content to
           prevent cookie forgeries.

       o   Building raw cryptographic-quality pseudo-random data sets for testing or sampling.

       o   Feeding secure key-gen utilities.

       Why use this module?  This module employs several well-designed CPAN tools to first
       generate a strong random seed, and then to instantiate a high quality random number
       generator based on the seed.  The code in this module really just glues together the
       building blocks.  However, it has taken a good deal of research to come up with what I
       feel is a strong tool-chain that isn't going to fall back to a weak state on some systems.
       The interface is designed with simplicity in mind, to minimize the potential for
       misconfiguration.

EXPORTS
       By default "random_bytes" is the only function exported.  Optionally "random_string_from",
       "random_bytes_base64", "random_bytes_hex", and "random_bytes_qp" may be exported.

FUNCTIONS
       The functions interface seeds the ISAAC generator on first use with a 256 bit seed that
       uses Crypt::Random::Seed's default configuration as a strong random seed source.

   random_bytes
           my $random_bytes = random_bytes( 512 );

       Returns a string containing as many random bytes as requested.  Obviously the string isn't
       useful for display, as it can contain any byte value from 0 through 255.

       The parameter is a byte-count, and must be an integer greater or equal to zero.

   random_string_from
           my $random_bytes = random_string_from( $bag, $length );
           my $random_bytes = random_string_from( 'abc', 50 );

       $bag is a string of characters from which "random_string_from" may choose in building a
       random string.  We call it a 'bag', because it's permissible to have repeated chars in the
       bag (if not, we could call it a set).  Repeated digits get more weight.  For example,
       "random_string_from( 'aab', 1 )" would have a 66.67% chance of returning an 'a', and a
       33.33% chance of returning a 'b'.  For unweighted distribution, ensure there are no
       duplicates in $bag.

       This isn't a "draw and discard", or a permutation algorithm; each character selected is
       independent of previous or subsequent selections; duplicate selections are possible by
       design.

       Return value is a string of size $length, of characters chosen at random from the 'bag'
       string.

       It is perfectly legal to pass a Unicode string as the "bag", and in that case, the yield
       will include Unicode characters selected from those passed in via the bag string.

       This function is useful for random string generation such as temporary random passwords.

   random_bytes_base64
           my $random_bytes_b64           = random_bytes_base64( $num_bytes );
           my $random_bytes_b64_formatted = random_bytes_base64( $num_bytes, $eol );

       Returns a MIME Base64 encoding of a string of $number_of_bytes random bytes.  Note, it
       should be obvious, but is worth mentioning that a base64 encoding of base256 data requires
       more digits to represent the bytes requested.  The actual number of digits required,
       including padding is "4(n/3)".  Furthermore, the Base64 standard is to add padding to the
       end of any string for which "length % 57" is a non-zero value.

       If an $eol is specified, the character(s) specified will be used as line delimiters after
       every 76th character.  The default is "qq{\n}".  If you wish to eliminate line-break
       insertions, specify an empty string: "q{}".

   random_bytes_hex
           my $random_bytes_as_hex = random_bytes_hex( $num_bytes );

       Returns a string of hex digits representing the string of $number_of_bytes random bytes.

       It's worth mentioning that a hex (base16) representation of base256 data requires two
       digits for every byte requested. So "length( random_bytes_hex( 16 ) )" will return 32, as
       it takes 32 hex digits to represent 16 bytes.  Simple stuff, but better to mention it now
       than forget and set a database field that's too narrow.

   random_bytes_qp
           my $random_bytes_qp           = random_bytes_qp( $num_bytes );
           my $random_bytes_qp_formatted = random_bytes_qp( $num_bytes, $eol );

       Produces a string of $num_bytes random bytes, using MIME Quoted Printable encoding (as
       produced by MIME::QuotedPrint's "encode_qp" function.  The default configuration uses "\n"
       as a line break after every 76 characters, and the "binmode" setting is used to guarantee
       a lossless round trip.  If no line break is wanted, pass an empty string as $eol.

METHODS
       The Object Oriented interface provides methods that mirror the "functions" interface.
       However, the OO interface offers the advantage that the user can control how many bits of
       entropy are used in seeding, and even how Crypt::Random::Seed is configured.

   new
           my $random = Bytes::Random::Secure->new( Bits => 512 );
           my $bytes  = $random->bytes( 32 );

       The constructor is used to specify how the ISAAC generator is seeded.  Future versions may
       also allow for alternate CSPRNGs to be selected.  If no parameters are passed the default
       configuration specifies 256 bits for the seed.  The rest of the default configuration
       accepts the Crypt::Random::Seed defaults, which favor the strongest operating system
       provided entropy source, which in many cases may be "blocking".

       CONSTRUCTOR PARAMETERS

       Bits

           my $random = Bytes::Random::Secure->new( Bits => 128 );

       The "Bits" parameter specifies how many bits (rounded up to nearest multiple of 32) will
       be used in seeding the ISAAC random number generator.  The default is 256 bits of entropy.
       But in some cases it may not be necessary, or even wise to pull so many bits of entropy
       out of "/dev/random" (a blocking source).

       Any value between 64 and 8192 will be accepted. If an out-of-range value is specified, or
       a value that is not a multiple of 32, a warning will be generated and the parameter will
       be rounded up to the nearest multiple of 32 within the range of 64 through 8192 bits.  So
       if 16384 is specified, you will get 8192.  If 33 is specified, you will get 64.

       Note: In the Perlish spirit of "no arbitrary limits", the maximum number of bits this
       module accepts is 8192, which is the maximum number that ISAAC can utilize.  But just
       because you can specify a seed of 8192 bits doesn't mean you ought to, much less need to.
       And if you do, you probably want to use the "NonBlocking" option, discussed below.  8192
       bits is a lot to ask from a blocking source such as "/dev/random", and really anything
       beyond 512 bits in the seed is probably wasteful.

       PRNG

       Reserved for future use.  Eventually the user will be able to select other RNGs aside from
       Math::Random::ISAAC.

       Unique

       Reserved for future use.

       Other Crypt::Random::Seed Configuration Parameters

       For additional seeding control, refer to the POD for Crypt::Random::Seed.  By supplying a
       Crypt::Random::Seed parameter to Bytes::Random::Secure's constructor, it will be passed
       through to Crypt::Random::Seed.  For example:

           my $random = Bytes::Random::Secure->new( NonBlocking => 1, Bits => 64 );

       In this example, "Bits" is used internally, while "NonBlocking" is passed through to
       Crypt::Random::Seed.

   bytes
           my $random_bytes = $random->bytes(1024);

       This works just like the "random_bytes" function.

   string_from
           my $random_string = $random->string_from( 'abcdefg', 10 );

       Just like "random_string_from": Returns a string of random octets selected from the "Bag"
       string (in this case ten octets from 'abcdefg').

   bytes_hex
           my $random_hex = $random->bytes_hex(12);

       Identical in function to "random_bytes_hex".

   bytes_base64
           my $random_base64 = $random->bytes_base64( 32, EOL => "\n" );

       Identical in function to "random_bytes_base64".

   bytes_qp
           my $random_qp = $random->bytes_qp( 80 );

       You guessed it: Identical in function to "random_bytes_qp".

   irand
           my $unsigned_long = $random->irand;

       Returns a random 32-bit unsigned integer.  The value will satisfy "0 <= x <= 2**32-1".
       This functionality is only available through the OO interface.

   shuffle
           my $aref_shuffled = $random->shuffle($aref);

       Shuffles the contents of a reference to an array in sitiu, and returns the same reference.

       List::Util, which ships with Perl, includes "shuffle" function. But that function is
       flawed in two ways. First, from a cryptographic standpoint, it uses Perl's "rand", which
       is not a CSPRNG, and therefore is inadequate.

       Second, because Perl's rand has an internal state of just 32 bits, it cannot possibly
       generate all permutations of arrays containing 13 or more elements.

       This module's "shuffle" uses a CSPRNG, and also benefits from large seeds and a huge
       internal state. ISAAC can be seeded with up to 8192 bits, yielding 2^8192 possible initial
       states, and 2^8288 possible internal states. A seed of 8192 bits will assure that for
       arrays of up to 966 elements every permutation is accessible.

CONFIGURATION
       Bytes::Random::Secure's interface tries to keep it simple.  There is generally nothing to
       configure.  This design, eliminates much of the  potential for diminishing the quality of
       the random byte stream through misconfiguration.  The ISAAC algorithm is used as our
       factory, seeded with a strong source.

       There may be times when the default seed characteristics carry too heavy a burden on
       system resources.  The default seed for the functions interface is 256 bits of entropy
       taken from /dev/random (a blocking source on many systems), or via API calls on Windows.
       The default seed size for the OO interface is also 256 bits. If /dev/random should become
       depleted at the time that this module attempts to seed the ISAAC generator, there could be
       delay while additional system entropy is generated.  If this is a problem, it is possible
       to override the default seeding characteristics using the OO interface instead of the
       functions interface.  However, under most circumstances, this capability may be safely
       ignored.

       Beginning with Bytes::Random::Secure version 0.20, Crypt::Random::Seed provides our strong
       seed (previously it was Crypt::Random::Source).  This module gives us excellent "strong
       source" failsafe behavior, while keeping the non-core dependencies to a bare minimum.
       Best of all, it performs well across a wide variety of platforms, and is compatible with
       Perl versions back through 5.6.0.

       And as mentioned earlier in this document, there may be circumstances where the
       performance of the operating system's strong random source is prohibitive from using the
       module's default seeding configuration.  Use the OO interface instead, and read the
       documentation for Crypt::Random::Seed to learn what options are available.

       Prior to version 0.20, a heavy dependency chain was required for reliably and securely
       seeding the ISAAC generator.  Earlier versions required Crypt::Random::Source, which in
       turn required Any::Moose.  Thanks to Dana Jacobsen's new Crypt::Random::Seed module, this
       situation has been resolved.  So if you're looking for a secure random bytes solution that
       "just works" portably, and on Perl versions as far back as 5.6.0, you've come to the right
       place.  Users of older versions of this module are encouraged to update to version 0.20 or
       higher to benefit from the improved user interface and lighter dependency chain.

   OPTIONAL (RECOMMENDED) DEPENDENCY
       If performance is a consideration, you may also install Math::Random::ISAAC::XS.
       Bytes::Random::Secure's random number generator uses Math::Random::ISAAC.  That module
       implements the ISAAC algorithm in pure Perl.  However, if you install
       Math::Random::ISAAC::XS, you get the same algorithm implemented in C/XS, which will
       provide better performance.  If you need to produce your random bytes more quickly, simply
       installing Math::Random::ISAAC::XS will result in it automatically being used, and a
       pretty good performance improvement will coincide.

CAVEATS
   FORK AND THREAD SAFETY
       When programming for parallel computation, avoid the "functions" interface do use the
       Object Oriented interface, and create a unique "Bytes::Random::Secure" object within each
       process or thread.  Bytes::Random::Secure uses a CSPRNG, and sharing the same RNG between
       threads or processes will share the same seed and the same starting point.  This is
       probably not what one would want to do. By instantiating the B::R::S object after forking
       or creating threads, a unique randomness stream will be created per thread or process.

   STRONG RANDOMNESS
       It's easy to generate weak pseudo-random bytes.  It's also easy to think you're generating
       strong pseudo-random bytes when really you're not.  And it's hard to test for pseudo-
       random cryptographic acceptable quality.  There are many high quality random number
       generators that are suitable for statistical purposes, but not necessarily up to the
       rigors of cryptographic use.

       Assuring strong (ie, secure) random bytes in a way that works across a wide variety of
       platforms is also challenging.  A primary goal for this module is to provide
       cryptographically secure pseudo-random bytes.  A secondary goal is to provide a simple
       user experience (thus reducing the propensity for getting it wrong).  A tertiary goal is
       to minimize the dependencies required to achieve the primary and secondary goals, to the
       extent that is practical.

   ISAAC
       The ISAAC algorithm is considered to be a cryptographically strong pseudo-random number
       generator.  There are 1.0e2466 initial states.  The best known attack for discovering
       initial state would theoretically take a complexity of approximately 4.67e1240, which has
       no practical impact on ISAAC's security.  Cycles are guaranteed to have a minimum length
       of 2**40, with an average cycle of 2**8295.  Because there is no practical attack capable
       of discovering initial state, and because the average cycle is so long, it's generally
       unnecessary to re-seed a running application.  The results are uniformly distributed,
       unbiased, and unpredictable unless the seed is known.

       To confirm the quality of the CSPRNG, this module's test suite implements the FIPS-140-1
       <http://csrc.nist.gov/publications/fips/fips1401.htm> tests for strong random number
       generators.  See the comments in "t/27-fips140-1.t" for details.

   DEPENDENCIES
       To keep the dependencies as light as possible this module uses some ideas from
       Math::Random::Secure.  That module is an excellent resource, but implements a broader
       range of functionality than is needed here.  So we just borrowed from it.

       The primary source of random data in this module comes from the excellent
       Math::Random::ISAAC.  To be useful and secure, even Math::Random::ISAAC needs a
       cryptographically sound seed, which we derive from Crypt::Random::Seed.  There are no
       known weaknesses in the ISAAC algorithm.  And Crypt::Random::Seed does a very good job of
       preventing fall-back to weak seed sources.

       This module requires Perl 5.6 or newer.  The module also uses a number of core modules,
       some of which require newer versions than those contemporary with 5.6.  Unicode support in
       "random_string_from" is best with Perl 5.8.9 or newer.  See the INSTALLATION section in
       this document for details.

       If Test::Warn is installed, test coverage is 100%.  For those who don't want to bother
       installing Test::Warn, you can just take our word for it.  It's an optional installation
       dependency.

   BLOCKING ENTROPY SOURCE
       It is possible (and has been seen in testing) that the system's random entropy source
       might not have enough entropy in reserve to generate the seed requested by this module
       without blocking.  If you suspect that you're a victim of blocking from reads on
       "/dev/random", one option is to manipulate the random seed configuration by using the
       object oriented interface.

       This module seeds as lazily as possible so that using the module, and even instantiating a
       Bytes::Random::Secure object will not trigger reads from "/dev/random".  Only the first
       time the object is used to deliver random bytes will the RNG be seeded.  Long-running
       scripts may prefer to force early seeding as close to start-up time as possible, rather
       than allowing it to happen later in a program's run-time.  This can be achieved simply by
       invoking any of the functions or methods that return a random byte.  As soon as a random
       byte is requested for the first time, the CSPRNG will be seeded.

   UNICODE SUPPORT
       The "random_string_from" function, and "string_from" method permit the user to pass a
       "bag" (or source) string containing Unicode characters.  For any modern Perl version, this
       will work just as you would hope.  But some versions of Perl older than 5.8.9 exhibited
       varying degrees of bugginess in their handling of Unicode.  If you're depending on the
       Unicode features of this module while using Perl versions older than 5.8.9 be sure to test
       thoroughly, and don't be surprised when the outcome isn't as expected.  ...this is to be
       expected.  Upgrade.

       No other functions or methods in this module get anywhere near Perl's Unicode features.
       So as long as you're not passing Unicode source strings to "random_string_from", you have
       nothing to worry about, even if you're using Perl 5.6.0.

   MODULO BIAS
       Care is taken so that there is no modulo bias in the randomness returned either by
       "random_bytes" or its siblings, nor by "random_string_from".  As a matter if fact, this is
       exactly why the "random_string_from" function is useful.  However, the algorithm to
       eliminate modulo bias can impact the performance of the "random_string_from" function. Any
       time the length of the bag string is significantly less than the nearest greater or equal
       factor of 2**32, performance will degrade.  Unfortunately there is no known algorithm that
       improves upon this situation.  Fortunately, for sanely sized strings, it's a minor issue.
       To put it in perspective, even in the case of passing a "bag" string of length 2**31
       (which is huge), the expected time to return random bytes will only double.  Given that
       the entire Unicode range is just over a million possible code-points, it seems unlikely
       that the normal use case would ever have to be concerned with the performance of the
       "random_string_from" function.

INSTALLATION
       This module should install without any fuss on modern versions of Perl.  For older Perl
       versions (particularly 5.6 and early 5.8.x's), it may be necessary to update your CPAN
       installer to a more modern version before installing this this module.

       Another alternative for those with old Perl versions who don't want to update their CPAN
       installer (You must know you're crazy, right?): Review "Makefile.PL" and assure that
       you've got the dependencies listed under "PREREQ_PM" and "BUILD_REQUIRES", in at least the
       minimum versions specified.  Then proceed as usual.

       This module only has two non-Core dependencies.  But it does expect that some of the Core
       dependencies are newer than those supplied with 5.6 or early 5.8's.  If you keep your CPAN
       installer up-to-date, you shouldn't have to think about this, as it will usually just "do
       the right thing", pulling in newer dependency versions as directed by the module's META
       files.

       Test coverage for Bytes::Random::Secure is 100% (per Devel::Cover) on any system that has
       Test::Warn installed.  But to keep the module light-weight, Test::Warn is not dragged in
       by default at installation time.

SEE ALSO
       Math::Random::Secure and Crypt::Random provide strong CSPRINGs and even more configuration
       options, but come with hefty toolchains.

       Bytes::Random::Secure::Tiny is a stand-alone adaptation of Bytes::Random::Secure with no
       dependencies. It will, however, detect if Math::Random::ISAAC, Math::Random::ISAAC::XS,
       and Crypt::Random::Seed are installed on the target system, and if they are, it quietly
       upgrades to using them.

AUTHOR
       David Oswald "<davido [at] cpan (dot) org>"

BUGS
       Please report any bugs or feature requests to "bug-bytes-random-secure at rt.cpan.org", or
       through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bytes-Random-Secure>.  I will be notified,
       and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

           perldoc Bytes::Random::Secure

       You can also look for information at:

       o   Github Repo: <https://github.com/daoswald/Bytes-Random-Secure>

       o   RT: CPAN's request tracker (report bugs here)

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Bytes-Random-Secure>

       o   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/Bytes-Random-Secure>

       o   CPAN Ratings

           <http://cpanratings.perl.org/d/Bytes-Random-Secure>

       o   Search CPAN

           <http://search.cpan.org/dist/Bytes-Random-Secure/>

ACKNOWLEDGEMENTS
       Dana Jacobsen ( <dana AT acm.org> ) for his work that led to Crypt::Random::Seed, thereby
       significantly reducing the dependencies while improving the portability and backward
       compatibility of this module.  Also for providing a patch to this module that greatly
       improved the performance of "random_bytes".

       Dana Jacosen also provided extensive input, code reviews, and testing that helped to guide
       the direction this module has taken.  The code for the FIPS-140-1 tests was taken directly
       from Crypt::Random::TESHA2.  Thanks!

       Bytes::Random for implementing a nice, simple interface that this module patterns itself
       after.

LICENSE AND COPYRIGHT
       Copyright 2012 David Oswald.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See http://dev.perl.org/licenses/ for more information.

perl v5.26.1                                2018-04-14                 Bytes::Random::Secure(3pm)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-10-16 01:21 @3.237.15.145 CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!