Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Crypt::Random::Seed(3)User Contributed Perl DocumentatioCrypt::Random::Seed(3)

NAME
       Crypt::Random::Seed - Simple method to get strong randomness

VERSION
       Version 0.03

SYNOPSIS
	 use Crypt::Random::Seed;

	 my $source = new Crypt::Random::Seed;
	 die "No strong	sources	exist" unless defined $source;
	 my $seed_string = $source->random_bytes(4);
	 my @seed_values = $source->random_values(4);

	 # Only	non-blocking sources
	 my $nonblocking_source	= Crypt::Random::Seed->new( NonBlocking=>1 );

	 # Blacklist sources (never choose the listed sources)
	 my $nowin32_source = Crypt::Random::Seed->new(	Never=>['Win32'] );

	 # Whitelist sources (only choose from these sources)
	 my $devr_source = Crypt::Random::Seed->new( Only=>['TESHA2'] );

	 # Supply a custom source.
	 my $user_src =	Crypt::Random::Seed->new( Source=>sub {	myfunc(shift) }	);
	 # Or supply a list of [name, sub, is_blocking,	is_strong]
	 $user_src = Crypt::Random::Seed->new(
	    Source=>['MyRandomFunction',sub {myfunc(shift)},0,1] );

	 # Given a source there	are a few things we can	do:
	 say "My randomness source is ", $source->name();
	 say "I	am a blocking source" if $source->is_blocking();
	 say "I	am a strong randomness source" if $source->is_strong()
	 say "Four 8-bit numbers:",
	     join(",", map { ord $source->random_bytes(1) } 1..4);'
	 say "Four 32-bit numbers:", join(",", $source->random_values(4));

DESCRIPTION
       A simple	mechanism to get strong	randomness.  The main purpose of this
       module is to provide a simple way to generate a seed for	a PRNG such as
       Math::Random::ISAAC, for	use in cryptographic key generation, or	as the
       seed for	an upstream module such	as Bytes::Random::Secure.  Flags for
       requiring non-blocking sources are allowed, as well as a	very simple
       method for plugging in a	source.

       The randomness sources used are,	in order:

       User supplied.
	   If the constructor is called	with a Source defined, then it is
	   used.  It is	not checked vs.	other flags (NonBlocking, Never,
	   Only).

       Win32 Crypto API.
	   This	will use "CryptGenRandom" on Windows 2000 and "RtlGenRand" on
	   Windows XP and newer.  According to MSDN, these are well-seeded
	   CSPRNGs (FIPS 186-2 or AES-CTR), so will be non-blocking.

       EGD / PRNGD.
	   This	looks for sockets that speak the EGD
	   <http://egd.sourceforge.net/> protocol, including PRNGD
	   <http://prngd.sourceforge.net/>.  These are userspace entropy
	   daemons that	are commonly used by OpenSSL, OpenSSH, and GnuGP.  The
	   locations searched are "/var/run/egd-pool", "/dev/egd-pool",
	   "/etc/egd-pool", and	"/etc/entropy".	 EGD is	blocking, while	PRNGD
	   is non-blocking (like the Win32 API,	it is really a seeded CSPRNG).
	   However there is no way to tell them	apart, so we treat it as
	   blocking.  If your O/S supports /dev/random,	consider HAVEGED
	   <http://www.issihosts.com/haveged/> as an alternative (a system
	   daemon that refills /dev/random as needed).

       /dev/random.
	   The strong source of	randomness on most UNIX-like systems.  Cygwin
	   uses	this, though it	maps to	the Win32 API.	On almost all systems
	   this	is a blocking source of	randomness -- if it runs out of
	   estimated entropy, it will hang until more has come into the
	   system.  If this is an issue, which it often	is on embedded
	   devices, running a tool such	as HAVEGED
	   <http://www.issihosts.com/haveged/> will help immensely.

       /dev/urandom.
	   A nonblocking source	of randomness that we label as weak, since it
	   will	continue providing output even if the actual entropy has been
	   exhausted.

       TESHA2.
	   Crypt::Random::TESHA2 is a Perl module that generates random	bytes
	   from	an entropy pool	fed with timer/scheduler variations.
	   Measurements	and tests are performed	on installation	to determine
	   whether the source is considered strong or weak.  This is entirely
	   in portable userspace, which	is good	for ease of use, but really
	   requires user verification that it is working as expected if	we
	   expect it to	be strong.  The	concept	is similar to
	   Math::TrulyRandom though updated to something closer	to what
	   TrueRand 2.1	does vs. the obsolete version 1	that Math::TrulyRandom
	   implements.	It is very slow	and has	wide speed variability across
	   platforms : I've seen numbers ranging from 40 to 150,000 bits per
	   second.

       A source	can also be supplied in	the constructor.  Each of these
       sources will have its debatable points about perceived strength.	 E.g.
       Why is /dev/urandom considered weak while Win32 is strong?  Can any
       userspace method	such as	TrueRand or TESHA2 be considered strong?

   SOURCE TABLE
       This table summarizes the default sources:

	 +------------------+-------------+------------+--------------------+
	 |	SOURCE	    |  STRENGTH	  |  BLOCKING  |       NOTE	    |
	 |------------------+-------------+------------+--------------------|
	 | RtlGenRandom	    |	Strong(1) |	No     | Default WinXP+	    |
	 |------------------+-------------+------------+--------------------|
	 | CryptGenRandom   |	Strong(1) |	No     | Default Win2000    |
	 |------------------+-------------+------------+--------------------|
	 | EGD		    |	Strong	  |    Yes(2)  | also PRNGD, etc.   |
	 |------------------+-------------+------------+--------------------|
	 | /dev/random	    |	Strong	  |    Yes     | Typical UNIX	    |
	 |------------------+-------------+------------+--------------------|
	 | /dev/urandom	    |	 Weak	  |	No     | Typical UNIX NB    |
	 |------------------+-------------+------------+--------------------|
	 | TESHA2-strong    |	Strong	  |	No     |		    |
	 |------------------+-------------+------------+--------------------|
	 | TESHA2-weak	    |	 Weak	  |	No     |		    |
	 +------------------+-------------+------------+--------------------+

       The alias 'Win32' can be	used in	whitelist and blacklist	and will match
       both the	Win32 sources "RtlGenRandom" and "CryptGenRandom".  The	alias
       'TESHA2'	may be similarly used and matches both the weak	and strong
       sources.

	 1) Both CryptGenRandom	and RtlGenRandom are considered	strong by this
	    package, even though both are seeded CSPRNGs so should be the equal	of
	    /dev/urandom in this respect.  The CryptGenRandom function used in
	    Windows 2000 has some known	issues so should be considered weaker.

	 2) EGD	is blocking, PRNGD is not.  We cannot tell the two apart.  There are
	    other software products that use the same protocol,	and each will act
	    differently.  E.g. EGD mixes in system entropy on every request, while
	    PRNGD mixes	on a time schedule.

   STRENGTH
       In theory, a strong generator will provide true entropy.	 Even if a
       third party knew	a previous result and the entire state of the
       generator at any	time up	to when	their value was	returned, they could
       still not effectively predict the result	of the next returned value.
       This implies the	generator must either be blocking to wait for entropy
       (e.g. /dev/random) or go	through	some possibly time-consuming process
       to gather it (TESHA2, EGD, the HAVEGE daemon refilling /dev/random).
       Note: strong in this context means practically strong, as most
       computers don't have a true hardware entropy generator.	The goal is to
       make all	the attackers ill-gotten knowledge give	them no	better
       solution	than if	they did not have the information.

       Creating	a satisfactory strength	measurement is problematic.  The Win32
       Crypto API is considered	"strong" by most customers and every other
       Perl module, however it is a well seeded	CSPRNG according to the	MSDN
       docs, so	is not a strong	source based on	the definition in the previous
       paragraph.  Similarly, almost all sources consider /dev/urandom to be
       weak, as	once it	runs out of entropy it returns a deterministic
       function	based on its state (albeit one that cannot be run either
       direction from a	returned result	if the internal	state is not known).

       Because of this confusion, I have removed the "Weak" configuration
       option that was present in version 0.01.	 It will now be	ignored.  You
       should be able to use a combination of whitelist, blacklist, and	the
       source's	"is_strong" return value to decide if this meets your needs.
       On Win32, you really only have a	choice of Win32	and TESHA2.  The
       former is going to be what most people want, and	can be chosen even
       with non-blocking set.  On most UNIX systems, "/dev/random" will	be
       chosen for blocking and "/dev/urandom" for non-blocking,	which is what
       should be done in most cases.

   BLOCKING
       EGD and /dev/random are blocking	sources.  This means that if they run
       out of estimated	entropy, they will pause until they've collected more.
       This means your program also pauses.  On	typical	workstations this may
       be a few	seconds	or even	minutes.  On an	isolated network server	this
       may cause a delay of hours or days.  EGD	is proactive about gathering
       more entropy as fast as it can.	Running	a tool such as the HAVEGE
       daemon or timer_entropyd	can make /dev/random act like a	non-blocking
       source, as the entropy daemon will wake up and refill the pool almost
       instantly.

       Win32, PRNGD, and /dev/urandom are fast nonblocking sources.  When they
       run out of entropy, they	use a CSPRNG to	keep supplying data at high
       speed.  However this means that there is	no additional entropy being
       supplied.

       TESHA2 is nonblocking, but can be very slow.  /dev/random can be	faster
       if run on a machine with	lots of	activity.  On an isolated server,
       TESHA2 may be much faster.  Also	note that the blocking sources such as
       EGD and /dev/random both	try to maintain	reasonably large entropy
       pools, so small requests	can be supplied	without	blocking.

   IN PRACTICE
       Use the default to get the best source known.  If you know more about
       the sources available, you can use a whitelist, blacklist, or a custom
       source.	In general, to get the best source (typically Win32 or
       /dev/random):

	 my $source = Crypt::Random::Seed->new();

       To get a	good non-blocking source (Win32	or /dev/urandom):

	 my $source = Crypt::Random::Seed->new(NonBlocking => 1);

METHODS
   new
       The constructor with no arguments will find the first available source
       in its fixed list and return an object that performs the	defined
       methods.	 If no sources could be	found (quite unusual) then the
       returned	value will be undef.

       Optional	parameters are passed in as a hash and may be mixed.

       NonBlocking =_ boolean

       Only non-blocking sources will be allowed.  In practice this means EGD
       and /dev/random will not	be chosen (except on FreeBSD where it is non-
       blocking).

       Only =_ [list of	strings]

       Takes an	array reference	containing one or more string source names.
       No source whose name does not match one of these	strings	will be
       chosen.	The string 'Win32' will	match either of	the Win32 sources, and
       'TESHA2'	will match both	the strong and weak versions.

       Never =_	[list of strings]

       Takes an	array reference	containing one or more string source names.
       No source whose name matches one	of these strings will be chosen.  The
       string 'Win32' will match either	of the Win32 sources, and 'TESHA2'
       will match both the strong and weak versions.

       Source =_ sub { ... }

       Uses the	given anonymous	subroutine as the generator.  The subroutine
       will be given an	integer	(the argument to "random_bytes") and should
       return random data in a string of the given length.  For	the purposes
       of the other object methods, the	returned object	will have the name
       'User', and be considered non-blocking and non-strong.

       Source =_ ['name', sub {	... }, is_blocking, is_strong]

       Similar to the simpler source routine, but also allows the other	source
       parameters to be	defined.  The name may not be one of the standard
       names listed in the "name" section.

   random_bytes($n)
       Takes an	integer	and returns a string of	that size filled with random
       data.  Returns an empty string if the argument is not defined or	is not
       more than zero.

   random_values($n)
       Takes an	integer	and returns an array of	that many random 32-bit
       values.	Returns	an empty array if the argument is not defined or is
       not more	than zero.

   name
       Returns the text	name of	the random source.  This will be one of:
       "User" for user defined,	"CryptGenRandom" for Windows 2000 Crypto API,
       "RtlGenRand" for	Windows	XP and newer Crypto API, "EGD" for a known
       socket speaking the EGD protocol, "/dev/random" for the UNIX-like
       strong randomness source, "/dev/urandom"	for the	UNIX-like non-blocking
       randomness source, "TESHA2-strong" for the userspace entropy method
       when considered strong, "TESHA2-weak" for the userspace entropy method
       when considered weak.  Other methods may	be supported in	the future.
       User supplied sources may be named anything other than one of the
       defined names.

   is_strong
       Returns 1 or 0 indicating whether the source is considered a strong
       source of randomness.  See the "STRENGTH" section for more discussion
       of what this means, and the source table	for what we think of each
       source.

   is_blocking
       Returns 1 or 0 indicating whether the source can	block on read.	Be
       aware that even if a source doesn't block, it may be extremely slow.

AUTHORS
       Dana Jacobsen <dana@acm.org>

ACKNOWLEDGEMENTS
       To the best of my knowledge, Max	Kanat-Alexander	was the	original
       author of the Perl code that uses the Win32 API.	 I used	his code as a
       reference.

       David Oswald gave me a lot of help with API discussions and code
       reviews.

SEE ALSO
       The first question one may ask is "Why yet another module of this
       type?"  None of the modules on CPAN quite fit my	needs, hence this.
       Some alternatives:

   Crypt::Random::Source
       A comprehensive system using multiple plugins.  It has a	nice API, but
       uses Any::Moose which means you're loading up Moose or Mouse just to
       read a few bytes	from /dev/random.  It also has a very long dependency
       chain, with on the order	of 40 modules being installed as prerequisites
       (depending of course on whether you use any of them on other projects).
       Lastly, it requires at least Perl 5.8, which may	or may not matter to
       you.  But it matters to some other module builders who end up with the
       restriction in their modules.

   Crypt::URandom
       A great little module that is almost what I was looking for.
       Crypt::Random::Seed will	act the	same if	given the constructor:

	 my $source = Crypt::Random::Seed->new(
	    NonBlocking	=> 1,
	    Only => [qw(/dev/random /dev/urandom Win32)]
	 );
	 croak "No randomness source available"	unless defined $source;

       Or you can leave	out the	"Only" and have	TESHA2 as a backup.

   Crypt::Random
       Requires	Math::Pari which makes it unacceptable in some environments.
       Has more	features (numbers in arbitrary bigint intervals	or bit sizes).
       Crypt::Random::Seed is taking a simpler approach, just handling
       returning octets	and letting upstream modules handle the	rest.

   Data::Entropy
       An interesting module that contains a source encapsulation (defaults to
       system rand, but	has many plugins), a good CSPRNG (AES in counter
       mode), and the Data::Entropy::Algorithms	module with many ways to get
       bits, ints, bigints, floats, bigfloats, shuffles, and so	forth.	From
       my perspective, the algorithms module is	the highlight, with a lot of
       interesting code.

   Upstream modules
       Some modules that could use this	module to help them:
       Bytes::Random::Secure, Math::Random::ISAAC, Math::Random::Secure, and
       Math::Random::MT	to name	a few.

COPYRIGHT
       Copyright 2013 by Dana Jacobsen <dana@acm.org>

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       The software is provided	"AS IS", without warranty of any kind, express
       or implied, including but not limited to	the warranties of
       merchantability,	fitness	for a particular purpose and noninfringement.
       In no event shall the authors or	copyright holders be liable for	any
       claim, damages or other liability, whether in an	action of contract,
       tort or otherwise, arising from,	out of or in connection	with the
       software	or the use or other dealings in	the software.

perl v5.24.1			  2013-02-16		Crypt::Random::Seed(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | AUTHORS | ACKNOWLEDGEMENTS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Crypt::Random::Seed&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help