{ "mode": "perldoc", "parameter": "Bytes::Random::Secure", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Bytes%3A%3ARandom%3A%3ASecure/json", "generated": "2026-06-10T13:42:38Z", "synopsis": "use Bytes::Random::Secure qw(\nrandombytes randombytesbase64 randombyteshex\n);\nmy $bytes = randombytes(32); # A string of 32 random bytes.\nmy $bytes = randomstringfrom( 'abcde', 10 ); # 10 random a,b,c,d, and e's.\nmy $bytesasbase64 = randombytesbase64(57); # Base64 encoded rand bytes.\nmy $bytesashex = randombyteshex(8); # Eight random bytes as hex digits.\nmy $bytesasquotedprintable = randombytesqp(100); # QP encoded bytes.\nmy $random = Bytes::Random::Secure->new(\nBits => 64,\nNonBlocking => 1,\n); # Seed with 64 bits, and use /dev/urandom (or other non-blocking).\nmy $bytes = $random->bytes(32); # A string of 32 random bytes.\nmy $long = $random->irand; # 32-bit random integer.", "sections": { "NAME": { "content": "Bytes::Random::Secure - Perl extension to generate cryptographically-secure random bytes.\n", "subsections": [] }, "SYNOPSIS": { "content": "use Bytes::Random::Secure qw(\nrandombytes randombytesbase64 randombyteshex\n);\n\nmy $bytes = randombytes(32); # A string of 32 random bytes.\n\nmy $bytes = randomstringfrom( 'abcde', 10 ); # 10 random a,b,c,d, and e's.\n\nmy $bytesasbase64 = randombytesbase64(57); # Base64 encoded rand bytes.\n\nmy $bytesashex = randombyteshex(8); # Eight random bytes as hex digits.\n\nmy $bytesasquotedprintable = randombytesqp(100); # QP encoded bytes.\n\n\nmy $random = Bytes::Random::Secure->new(\nBits => 64,\nNonBlocking => 1,\n); # Seed with 64 bits, and use /dev/urandom (or other non-blocking).\n\nmy $bytes = $random->bytes(32); # A string of 32 random bytes.\nmy $long = $random->irand; # 32-bit random integer.\n", "subsections": [] }, "DESCRIPTION": { "content": "Bytes::Random::Secure provides two interfaces for obtaining crypto-quality random bytes. The\nsimple interface is built around plain functions. For greater control over the Random Number\nGenerator's seeding, there is an Object Oriented interface that provides much more flexibility.\n\nThe \"functions\" interface provides functions that can be used any time you need a string of a\nspecific number of random bytes. The random bytes are available as simple strings, or as\nhex-digits, Quoted Printable, or MIME Base64. There are equivalent methods available from the OO\ninterface, plus a few others.\n\nThis module can be a drop-in replacement for Bytes::Random, with the primary enhancement of\nusing a cryptographic-quality random number generator to create the random data. The\n\"randombytes\" function emulates the user interface of Bytes::Random's function by the same\nname. But with Bytes::Random::Secure the random number generator comes from Math::Random::ISAAC,\nand is suitable for cryptographic purposes. The harder problem to solve is how to seed the\ngenerator. This module uses Crypt::Random::Seed to generate the initial seeds for\nMath::Random::ISAAC.\n\nIn addition to providing \"randombytes()\", this module also provides several functions not found\nin Bytes::Random: \"randomstringfrom\", \"randombytesbase64()\", \"randombyteshex\", and\n\"randombytesqp\".\n\nAnd finally, for those who need finer control over how Crypt::Random::Seed generates its seed,\nthere is an object oriented interface with a constructor that facilitates configuring the\nseeding process, while providing methods that do everything the \"functions\" interface can do\n(truth be told, the functions interface is just a thin wrapper around the OO version, with some\nsane defaults selected). The OO interface also provides an \"irand\" method, not available through\nthe functions interface.\n", "subsections": [] }, "RATIONALE": { "content": "There are many uses for cryptographic quality randomness. This module aims to provide a\ngeneralized tool that can fit into many applications while providing a minimal dependency chain,\nand a user interface that is simple. You're free to come up with your own use-cases, but there\nare several obvious ones:\n\n* Creating temporary passphrases (\"randomstringfrom()\").\n\n* Generating per-account random salt to be hashed along with passphrases (and stored alongside\nthem) to prevent rainbow table attacks.\n\n* Generating a secret that can be hashed along with a cookie's session content to prevent\ncookie forgeries.\n\n* Building raw cryptographic-quality pseudo-random data sets for testing or sampling.\n\n* Feeding secure key-gen utilities.\n\nWhy use this module? This module employs several well-designed CPAN tools to first generate a\nstrong random seed, and then to instantiate a high quality random number generator based on the\nseed. The code in this module really just glues together the building blocks. However, it has\ntaken a good deal of research to come up with what I feel is a strong tool-chain that isn't\ngoing to fall back to a weak state on some systems. The interface is designed with simplicity in\nmind, to minimize the potential for misconfiguration.\n", "subsections": [] }, "EXPORTS": { "content": "By default \"randombytes\" is the only function exported. Optionally \"randomstringfrom\",\n\"randombytesbase64\", \"randombyteshex\", and \"randombytesqp\" may be exported.\n", "subsections": [] }, "FUNCTIONS": { "content": "The functions interface seeds the ISAAC generator on first use with a 256 bit seed that uses\nCrypt::Random::Seed's default configuration as a strong random seed source.\n\nrandombytes\nmy $randombytes = randombytes( 512 );\n\nReturns a string containing as many random bytes as requested. Obviously the string isn't useful\nfor display, as it can contain any byte value from 0 through 255.\n\nThe parameter is a byte-count, and must be an integer greater or equal to zero.\n\nrandomstringfrom\nmy $randombytes = randomstringfrom( $bag, $length );\nmy $randombytes = randomstringfrom( 'abc', 50 );\n\n$bag is a string of characters from which \"randomstringfrom\" may choose in building a random\nstring. We call it a 'bag', because it's permissible to have repeated chars in the bag (if not,\nwe could call it a set). Repeated digits get more weight. For example, \"randomstringfrom(\n'aab', 1 )\" would have a 66.67% chance of returning an 'a', and a 33.33% chance of returning a\n'b'. For unweighted distribution, ensure there are no duplicates in $bag.\n\nThis *isn't* a \"draw and discard\", or a permutation algorithm; each character selected is\nindependent of previous or subsequent selections; duplicate selections are possible by design.\n\nReturn value is a string of size $length, of characters chosen at random from the 'bag' string.\n\nIt is perfectly legal to pass a Unicode string as the \"bag\", and in that case, the yield will\ninclude Unicode characters selected from those passed in via the bag string.\n\nThis function is useful for random string generation such as temporary random passwords.\n\nrandombytesbase64\nmy $randombytesb64 = randombytesbase64( $numbytes );\nmy $randombytesb64formatted = randombytesbase64( $numbytes, $eol );\n\nReturns a MIME Base64 encoding of a string of $numberofbytes random bytes. Note, it should be\nobvious, but is worth mentioning that a base64 encoding of base256 data requires more digits to\nrepresent the bytes requested. The actual number of digits required, including padding is\n\"4(n/3)\". Furthermore, the Base64 standard is to add padding to the end of any string for which\n\"length % 57\" is a non-zero value.\n\nIf an $eol is specified, the character(s) specified will be used as line delimiters after every\n76th character. The default is \"qq{\\n}\". If you wish to eliminate line-break insertions, specify\nan empty string: \"q{}\".\n\nrandombyteshex\nmy $randombytesashex = randombyteshex( $numbytes );\n\nReturns a string of hex digits representing the string of $numberofbytes random bytes.\n\nIt's worth mentioning that a hex (base16) representation of base256 data requires two digits for\nevery byte requested. So \"length( randombyteshex( 16 ) )\" will return 32, as it takes 32 hex\ndigits to represent 16 bytes. Simple stuff, but better to mention it now than forget and set a\ndatabase field that's too narrow.\n\nrandombytesqp\nmy $randombytesqp = randombytesqp( $numbytes );\nmy $randombytesqpformatted = randombytesqp( $numbytes, $eol );\n\nProduces a string of $numbytes random bytes, using MIME Quoted Printable encoding (as produced\nby MIME::QuotedPrint's \"encodeqp\" function. The default configuration uses \"\\n\" as a line break\nafter every 76 characters, and the \"binmode\" setting is used to guarantee a lossless round trip.\nIf no line break is wanted, pass an empty string as $eol.\n", "subsections": [] }, "METHODS": { "content": "The Object Oriented interface provides methods that mirror the \"functions\" interface. However,\nthe OO interface offers the advantage that the user can control how many bits of entropy are\nused in seeding, and even how Crypt::Random::Seed is configured.\n\nnew\nmy $random = Bytes::Random::Secure->new( Bits => 512 );\nmy $bytes = $random->bytes( 32 );\n\nThe constructor is used to specify how the ISAAC generator is seeded. Future versions may also\nallow for alternate CSPRNGs to be selected. If no parameters are passed the default\nconfiguration specifies 256 bits for the seed. The rest of the default configuration accepts the\nCrypt::Random::Seed defaults, which favor the strongest operating system provided entropy\nsource, which in many cases may be \"blocking\".\n\nCONSTRUCTOR PARAMETERS\nBits\nmy $random = Bytes::Random::Secure->new( Bits => 128 );\n\nThe \"Bits\" parameter specifies how many bits (rounded up to nearest multiple of 32) will be used\nin seeding the ISAAC random number generator. The default is 256 bits of entropy. But in some\ncases it may not be necessary, or even wise to pull so many bits of entropy out of \"/dev/random\"\n(a blocking source).\n\nAny value between 64 and 8192 will be accepted. If an out-of-range value is specified, or a\nvalue that is not a multiple of 32, a warning will be generated and the parameter will be\nrounded up to the nearest multiple of 32 within the range of 64 through 8192 bits. So if 16384\nis specified, you will get 8192. If 33 is specified, you will get 64.\n\nNote: In the Perlish spirit of \"*no arbitrary limits*\", the maximum number of bits this module\naccepts is 8192, which is the maximum number that ISAAC can utilize. But just because you *can*\nspecify a seed of 8192 bits doesn't mean you ought to, much less need to. And if you do, you\nprobably want to use the \"NonBlocking\" option, discussed below. 8192 bits is a lot to ask from a\nblocking source such as \"/dev/random\", and really anything beyond 512 bits in the seed is\nprobably wasteful.\n\nPRNG\nReserved for future use. Eventually the user will be able to select other RNGs aside from\nMath::Random::ISAAC.\n\nUnique\nReserved for future use.\n\nOther Crypt::Random::Seed Configuration Parameters\nFor additional seeding control, refer to the POD for Crypt::Random::Seed. By supplying a\nCrypt::Random::Seed parameter to Bytes::Random::Secure's constructor, it will be passed through\nto Crypt::Random::Seed. For example:\n\nmy $random = Bytes::Random::Secure->new( NonBlocking => 1, Bits => 64 );\n\nIn this example, \"Bits\" is used internally, while \"NonBlocking\" is passed through to\nCrypt::Random::Seed.\n\nbytes\nmy $randombytes = $random->bytes(1024);\n\nThis works just like the \"randombytes\" function.\n\nstringfrom\nmy $randomstring = $random->stringfrom( 'abcdefg', 10 );\n\nJust like \"randomstringfrom\": Returns a string of random octets selected from the \"Bag\" string\n(in this case ten octets from 'abcdefg').\n\nbyteshex\nmy $randomhex = $random->byteshex(12);\n\nIdentical in function to \"randombyteshex\".\n\nbytesbase64\nmy $randombase64 = $random->bytesbase64( 32, EOL => \"\\n\" );\n\nIdentical in function to \"randombytesbase64\".\n\nbytesqp\nmy $randomqp = $random->bytesqp( 80 );\n\nYou guessed it: Identical in function to \"randombytesqp\".\n\nirand\nmy $unsignedlong = $random->irand;\n\nReturns a random 32-bit unsigned integer. The value will satisfy \"0 <= x <= 232-1\". This\nfunctionality is only available through the OO interface.\n\nshuffle\nmy $arefshuffled = $random->shuffle($aref);\n\nShuffles the contents of a reference to an array in sitiu, and returns the same reference.\n\nList::Util, which ships with Perl, includes \"shuffle\" function. But that function is flawed in\ntwo ways. First, from a cryptographic standpoint, it uses Perl's \"rand\", which is not a CSPRNG,\nand therefore is inadequate.\n\nSecond, because Perl's rand has an internal state of just 32 bits, it cannot possibly generate\nall permutations of arrays containing 13 or more elements.\n\nThis module's \"shuffle\" uses a CSPRNG, and also benefits from large seeds and a huge internal\nstate. ISAAC can be seeded with up to 8192 bits, yielding 2^8192 possible initial states, and\n2^8288 possible internal states. A seed of 8192 bits will assure that for arrays of up to 966\nelements every permutation is accessible.\n", "subsections": [] }, "CONFIGURATION": { "content": "Bytes::Random::Secure's interface tries to *keep it simple*. There is generally nothing to\nconfigure. This design, eliminates much of the potential for diminishing the quality of the\nrandom byte stream through misconfiguration. The ISAAC algorithm is used as our factory, seeded\nwith a strong source.\n\nThere may be times when the default seed characteristics carry too heavy a burden on system\nresources. The default seed for the functions interface is 256 bits of entropy taken from\n/dev/random (a blocking source on many systems), or via API calls on Windows. The default seed\nsize for the OO interface is also 256 bits. If /dev/random should become depleted at the time\nthat this module attempts to seed the ISAAC generator, there could be delay while additional\nsystem entropy is generated. If this is a problem, it is possible to override the default\nseeding characteristics using the OO interface instead of the functions interface. However,\nunder most circumstances, this capability may be safely ignored.\n\nBeginning with Bytes::Random::Secure version 0.20, Crypt::Random::Seed provides our strong seed\n(previously it was Crypt::Random::Source). This module gives us excellent \"strong source\"\nfailsafe behavior, while keeping the non-core dependencies to a bare minimum. Best of all, it\nperforms well across a wide variety of platforms, and is compatible with Perl versions back\nthrough 5.6.0.\n\nAnd as mentioned earlier in this document, there may be circumstances where the performance of\nthe operating system's strong random source is prohibitive from using the module's default\nseeding configuration. Use the OO interface instead, and read the documentation for\nCrypt::Random::Seed to learn what options are available.\n\nPrior to version 0.20, a heavy dependency chain was required for reliably and securely seeding\nthe ISAAC generator. Earlier versions required Crypt::Random::Source, which in turn required\nAny::Moose. Thanks to Dana Jacobsen's new Crypt::Random::Seed module, this situation has been\nresolved. So if you're looking for a secure random bytes solution that \"just works\" portably,\nand on Perl versions as far back as 5.6.0, you've come to the right place. Users of older\nversions of this module are encouraged to update to version 0.20 or higher to benefit from the\nimproved user interface and lighter dependency chain.\n\nOPTIONAL (RECOMMENDED) DEPENDENCY\nIf performance is a consideration, you may also install Math::Random::ISAAC::XS.\nBytes::Random::Secure's random number generator uses Math::Random::ISAAC. That module implements\nthe ISAAC algorithm in pure Perl. However, if you install Math::Random::ISAAC::XS, you get the\nsame algorithm implemented in C/XS, which will provide better performance. If you need to\nproduce your random bytes more quickly, simply installing Math::Random::ISAAC::XS will result in\nit automatically being used, and a pretty good performance improvement will coincide.\n", "subsections": [] }, "CAVEATS": { "content": "FORK AND THREAD SAFETY\nWhen programming for parallel computation, avoid the \"functions\" interface do use the Object\nOriented interface, and create a unique \"Bytes::Random::Secure\" object within each process or\nthread. Bytes::Random::Secure uses a CSPRNG, and sharing the same RNG between threads or\nprocesses will share the same seed and the same starting point. This is probably not what one\nwould want to do. By instantiating the B::R::S object after forking or creating threads, a\nunique randomness stream will be created per thread or process.\n\nSTRONG RANDOMNESS\nIt's easy to generate weak pseudo-random bytes. It's also easy to think you're generating strong\npseudo-random bytes when really you're not. And it's hard to test for pseudo-random\ncryptographic acceptable quality. There are many high quality random number generators that are\nsuitable for statistical purposes, but not necessarily up to the rigors of cryptographic use.\n\nAssuring strong (ie, secure) random bytes in a way that works across a wide variety of platforms\nis also challenging. A primary goal for this module is to provide cryptographically secure\npseudo-random bytes. A secondary goal is to provide a simple user experience (thus reducing the\npropensity for getting it wrong). A tertiary goal is to minimize the dependencies required to\nachieve the primary and secondary goals, to the extent that is practical.\n\nISAAC\nThe ISAAC algorithm is considered to be a cryptographically strong pseudo-random number\ngenerator. There are 1.0e2466 initial states. The best known attack for discovering initial\nstate would theoretically take a complexity of approximately 4.67e1240, which has no practical\nimpact on ISAAC's security. Cycles are guaranteed to have a minimum length of 240, with an\naverage cycle of 28295. Because there is no practical attack capable of discovering initial\nstate, and because the average cycle is so long, it's generally unnecessary to re-seed a running\napplication. The results are uniformly distributed, unbiased, and unpredictable unless the seed\nis known.\n\nTo confirm the quality of the CSPRNG, this module's test suite implements the FIPS-140-1\n tests for strong random number generators.\nSee the comments in \"t/27-fips140-1.t\" for details.\n\nDEPENDENCIES\nTo keep the dependencies as light as possible this module uses some ideas from\nMath::Random::Secure. That module is an excellent resource, but implements a broader range of\nfunctionality than is needed here. So we just borrowed from it.\n\nThe primary source of random data in this module comes from the excellent Math::Random::ISAAC.\nTo be useful and secure, even Math::Random::ISAAC needs a cryptographically sound seed, which we\nderive from Crypt::Random::Seed. There are no known weaknesses in the ISAAC algorithm. And\nCrypt::Random::Seed does a very good job of preventing fall-back to weak seed sources.\n\nThis module requires Perl 5.6 or newer. The module also uses a number of core modules, some of\nwhich require newer versions than those contemporary with 5.6. Unicode support in\n\"randomstringfrom\" is best with Perl 5.8.9 or newer. See the INSTALLATION section in this\ndocument for details.\n\nIf Test::Warn is installed, test coverage is 100%. For those who don't want to bother installing\nTest::Warn, you can just take our word for it. It's an optional installation dependency.\n\nBLOCKING ENTROPY SOURCE\nIt is possible (and has been seen in testing) that the system's random entropy source might not\nhave enough entropy in reserve to generate the seed requested by this module without blocking.\nIf you suspect that you're a victim of blocking from reads on \"/dev/random\", one option is to\nmanipulate the random seed configuration by using the object oriented interface.\n\nThis module seeds as lazily as possible so that using the module, and even instantiating a\nBytes::Random::Secure object will not trigger reads from \"/dev/random\". Only the first time the\nobject is used to deliver random bytes will the RNG be seeded. Long-running scripts may prefer\nto force early seeding as close to start-up time as possible, rather than allowing it to happen\nlater in a program's run-time. This can be achieved simply by invoking any of the functions or\nmethods that return a random byte. As soon as a random byte is requested for the first time, the\nCSPRNG will be seeded.\n\nUNICODE SUPPORT\nThe \"randomstringfrom\" function, and \"stringfrom\" method permit the user to pass a \"bag\" (or\nsource) string containing Unicode characters. For any modern Perl version, this will work just\nas you would hope. But some versions of Perl older than 5.8.9 exhibited varying degrees of\nbugginess in their handling of Unicode. If you're depending on the Unicode features of this\nmodule while using Perl versions older than 5.8.9 be sure to test thoroughly, and don't be\nsurprised when the outcome isn't as expected. ...this is to be expected. Upgrade.\n\nNo other functions or methods in this module get anywhere near Perl's Unicode features. So as\nlong as you're not passing Unicode source strings to \"randomstringfrom\", you have nothing to\nworry about, even if you're using Perl 5.6.0.\n\nMODULO BIAS\nCare is taken so that there is no modulo bias in the randomness returned either by\n\"randombytes\" or its siblings, nor by \"randomstringfrom\". As a matter if fact, this is\nexactly *why* the \"randomstringfrom\" function is useful. However, the algorithm to eliminate\nmodulo bias can impact the performance of the \"randomstringfrom\" function. Any time the length\nof the bag string is significantly less than the nearest greater or equal factor of 232,\nperformance will degrade. Unfortunately there is no known algorithm that improves upon this\nsituation. Fortunately, for sanely sized strings, it's a minor issue. To put it in perspective,\neven in the case of passing a \"bag\" string of length 231 (which is huge), the expected time to\nreturn random bytes will only double. Given that the entire Unicode range is just over a million\npossible code-points, it seems unlikely that the normal use case would ever have to be concerned\nwith the performance of the \"randomstringfrom\" function.\n", "subsections": [] }, "INSTALLATION": { "content": "This module should install without any fuss on modern versions of Perl. For older Perl versions\n(particularly 5.6 and early 5.8.x's), it may be necessary to update your CPAN installer to a\nmore modern version before installing this this module.\n\nAnother alternative for those with old Perl versions who don't want to update their CPAN\ninstaller (You must know you're crazy, right?): Review \"Makefile.PL\" and assure that you've got\nthe dependencies listed under \"PREREQPM\" and \"BUILDREQUIRES\", in at least the minimum versions\nspecified. Then proceed as usual.\n\nThis module only has two non-Core dependencies. But it does expect that some of the Core\ndependencies are newer than those supplied with 5.6 or early 5.8's. If you keep your CPAN\ninstaller up-to-date, you shouldn't have to think about this, as it will usually just \"do the\nright thing\", pulling in newer dependency versions as directed by the module's META files.\n\nTest coverage for Bytes::Random::Secure is 100% (per Devel::Cover) on any system that has\nTest::Warn installed. But to keep the module light-weight, Test::Warn is not dragged in by\ndefault at installation time.\n", "subsections": [] }, "SEE ALSO": { "content": "Math::Random::Secure and Crypt::Random provide strong CSPRINGs and even more configuration\noptions, but come with hefty toolchains.\n\nBytes::Random::Secure::Tiny is a stand-alone adaptation of Bytes::Random::Secure with no\ndependencies. It will, however, detect if Math::Random::ISAAC, Math::Random::ISAAC::XS, and\nCrypt::Random::Seed are installed on the target system, and if they are, it quietly upgrades to\nusing them.\n", "subsections": [] }, "AUTHOR": { "content": "David Oswald \"\"\n", "subsections": [] }, "BUGS": { "content": "Please report any bugs or feature requests to \"bug-bytes-random-secure at rt.cpan.org\", or\nthrough the web interface at\n. I will be notified, and\nthen you'll automatically be notified of progress on your bug as I make changes.\n", "subsections": [] }, "SUPPORT": { "content": "You can find documentation for this module with the perldoc command.\n\nperldoc Bytes::Random::Secure\n\nYou can also look for information at:\n\n* Github Repo: \n\n* RT: CPAN's request tracker (report bugs here)\n\n\n\n* AnnoCPAN: Annotated CPAN documentation\n\n\n\n* CPAN Ratings\n\n\n\n* Search CPAN\n\n\n", "subsections": [] }, "ACKNOWLEDGEMENTS": { "content": "Dana Jacobsen ( ** ) for his work that led to Crypt::Random::Seed, thereby\nsignificantly reducing the dependencies while improving the portability and backward\ncompatibility of this module. Also for providing a patch to this module that greatly improved\nthe performance of \"randombytes\".\n\nDana Jacosen also provided extensive input, code reviews, and testing that helped to guide the\ndirection this module has taken. The code for the FIPS-140-1 tests was taken directly from\nCrypt::Random::TESHA2. Thanks!\n\nBytes::Random for implementing a nice, simple interface that this module patterns itself after.\n", "subsections": [] }, "LICENSE AND COPYRIGHT": { "content": "Copyright 2012 David Oswald.\n\nThis program is free software; you can redistribute it and/or modify it under the terms of\neither: the GNU General Public License as published by the Free Software Foundation; or the\nArtistic License.\n\nSee http://dev.perl.org/licenses/ for more information.\n", "subsections": [] } }, "summary": "Bytes::Random::Secure - Perl extension to generate cryptographically-secure random bytes.", "flags": [], "examples": [], "see_also": [] }