pool_of_entropy 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 455d13c29630cf9a7255e9d4f76d1ee8ac7dd32b
+  data.tar.gz: 4b61829c13593ed3aa534d6ca462b04ca7139b66
+SHA512:
+  metadata.gz: f14bf6fdfc0466312c67608ca9bbb966ce5fbef1166d690d8baef622d4311fa9d8fa473bf5f5d292fdef38da9e8e08a5f2ef39ca20de677d59a9bb8ba9e6233f
+  data.tar.gz: acc6a94d9bd4f2e436d783489863fcf0e9bd97c3be5f25033b676aefdde9f6136f7e3c58bfd7013e845f3530a4cfa6aa718b3c9261683f88d1f68c972af959d2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - "2.1.0"
+  - jruby-19mode
+  - jruby-head

data/DIEHARDER_TEST.md

@@ -0,0 +1,156 @@
+# Results of dieharder randomness test
+
+See http://www.phy.duke.edu/~rgb/General/dieharder.php for details about
+the dieharder utility.
+
+The test consumes a large amount of data, several orders of magnitude
+more than the target use of PoolOfEntropy. It is a thorough test
+for hidden bias, short cycles and patterns that may occur as faults
+in "weak" PRNGs. No test of randomness can be 100% certain though.
+
+The test PASS received implies PoolOfEntropy is free from a variety
+of detectable faults that would prevent it being used as a source of
+statistically random numbers. Not all PRNGs pass these tests -
+for instance, C's standard library rand() fails most of them.
+All modern cryptographic PRNGs should be expected to pass,
+as should Ruby's built-in rand() - an implementation of the Mersenne
+Twister algorithm.
+
+## Date run: 9 May 2014
+
+Completing all the tests took roughly 3 days.
+
+## Command used
+
+PoolOfEntropy::CorePRNG was used in its default, simplest state to
+create a continuous stream of pseudo-random bytes, and this was
+fed into the dieharder test running the "all tests" option:
+
+    ruby -rpool_of_entropy -e \
+      'r=PoolOfEntropy::CorePRNG.new;loop do;print r.read_bytes;end' \
+      | dieharder -g 200 -a
+
+## Report from dieharder
+
+    #=============================================================================#
+    #            dieharder version 3.31.1 Copyright 2003 Robert G. Brown          #
+    #=============================================================================#
+       rng_name    |rands/second|   Seed   |
+    stdin_input_raw|  2.40e+05  |3475765104|
+    #=============================================================================#
+            test_name   |ntup| tsamples |psamples|  p-value |Assessment
+    #=============================================================================#
+       diehard_birthdays|   0|       100|     100|0.70127033|  PASSED
+          diehard_operm5|   0|   1000000|     100|0.49443406|  PASSED
+      diehard_rank_32x32|   0|     40000|     100|0.58788457|  PASSED
+        diehard_rank_6x8|   0|    100000|     100|0.08410111|  PASSED
+       diehard_bitstream|   0|   2097152|     100|0.97953152|  PASSED
+            diehard_opso|   0|   2097152|     100|0.97485622|  PASSED
+            diehard_oqso|   0|   2097152|     100|0.70397562|  PASSED
+             diehard_dna|   0|   2097152|     100|0.76551419|  PASSED
+    diehard_count_1s_str|   0|    256000|     100|0.95727516|  PASSED
+    diehard_count_1s_byt|   0|    256000|     100|0.42576929|  PASSED
+     diehard_parking_lot|   0|     12000|     100|0.08478625|  PASSED
+        diehard_2dsphere|   2|      8000|     100|0.27022174|  PASSED
+        diehard_3dsphere|   3|      4000|     100|0.37750039|  PASSED
+         diehard_squeeze|   0|    100000|     100|0.84447931|  PASSED
+            diehard_sums|   0|       100|     100|0.07148373|  PASSED
+            diehard_runs|   0|    100000|     100|0.84129944|  PASSED
+            diehard_runs|   0|    100000|     100|0.01135930|  PASSED
+           diehard_craps|   0|    200000|     100|0.08034019|  PASSED
+           diehard_craps|   0|    200000|     100|0.62929296|  PASSED
+     marsaglia_tsang_gcd|   0|  10000000|     100|0.56434071|  PASSED
+     marsaglia_tsang_gcd|   0|  10000000|     100|0.28872723|  PASSED
+             sts_monobit|   1|    100000|     100|0.80991806|  PASSED
+                sts_runs|   2|    100000|     100|0.91086458|  PASSED
+              sts_serial|   1|    100000|     100|0.88204963|  PASSED
+              sts_serial|   2|    100000|     100|0.77896528|  PASSED
+              sts_serial|   3|    100000|     100|0.99012882|  PASSED
+              sts_serial|   3|    100000|     100|0.57917534|  PASSED
+              sts_serial|   4|    100000|     100|0.29749662|  PASSED
+              sts_serial|   4|    100000|     100|0.91618340|  PASSED
+              sts_serial|   5|    100000|     100|0.61310658|  PASSED
+              sts_serial|   5|    100000|     100|0.70187732|  PASSED
+              sts_serial|   6|    100000|     100|0.63483611|  PASSED
+              sts_serial|   6|    100000|     100|0.63638375|  PASSED
+              sts_serial|   7|    100000|     100|0.87933422|  PASSED
+              sts_serial|   7|    100000|     100|0.92340602|  PASSED
+              sts_serial|   8|    100000|     100|0.08379368|  PASSED
+              sts_serial|   8|    100000|     100|0.30058991|  PASSED
+              sts_serial|   9|    100000|     100|0.47909085|  PASSED
+              sts_serial|   9|    100000|     100|0.99388217|  PASSED
+              sts_serial|  10|    100000|     100|0.62723409|  PASSED
+              sts_serial|  10|    100000|     100|0.04085355|  PASSED
+              sts_serial|  11|    100000|     100|0.40703003|  PASSED
+              sts_serial|  11|    100000|     100|0.07446698|  PASSED
+              sts_serial|  12|    100000|     100|0.45945558|  PASSED
+              sts_serial|  12|    100000|     100|0.50603459|  PASSED
+              sts_serial|  13|    100000|     100|0.19977550|  PASSED
+              sts_serial|  13|    100000|     100|0.22347592|  PASSED
+              sts_serial|  14|    100000|     100|0.68014498|  PASSED
+              sts_serial|  14|    100000|     100|0.38635200|  PASSED
+              sts_serial|  15|    100000|     100|0.44640327|  PASSED
+              sts_serial|  15|    100000|     100|0.65586709|  PASSED
+              sts_serial|  16|    100000|     100|0.97546459|  PASSED
+              sts_serial|  16|    100000|     100|0.84301307|  PASSED
+             rgb_bitdist|   1|    100000|     100|0.28629993|  PASSED
+             rgb_bitdist|   2|    100000|     100|0.56483445|  PASSED
+             rgb_bitdist|   3|    100000|     100|0.62133888|  PASSED
+             rgb_bitdist|   4|    100000|     100|0.81437794|  PASSED
+             rgb_bitdist|   5|    100000|     100|0.98632962|  PASSED
+             rgb_bitdist|   6|    100000|     100|0.97669342|  PASSED
+             rgb_bitdist|   7|    100000|     100|0.30828120|  PASSED
+             rgb_bitdist|   8|    100000|     100|0.66955561|  PASSED
+             rgb_bitdist|   9|    100000|     100|0.94528798|  PASSED
+             rgb_bitdist|  10|    100000|     100|0.90457257|  PASSED
+             rgb_bitdist|  11|    100000|     100|0.85673195|  PASSED
+             rgb_bitdist|  12|    100000|     100|0.22076625|  PASSED
+    rgb_minimum_distance|   2|     10000|    1000|0.53379172|  PASSED
+    rgb_minimum_distance|   3|     10000|    1000|0.43597963|  PASSED
+    rgb_minimum_distance|   4|     10000|    1000|0.31259419|  PASSED
+    rgb_minimum_distance|   5|     10000|    1000|0.61615392|  PASSED
+        rgb_permutations|   2|    100000|     100|0.95732489|  PASSED
+        rgb_permutations|   3|    100000|     100|0.78107574|  PASSED
+        rgb_permutations|   4|    100000|     100|0.64034376|  PASSED
+        rgb_permutations|   5|    100000|     100|0.89199822|  PASSED
+          rgb_lagged_sum|   0|   1000000|     100|0.63905487|  PASSED
+          rgb_lagged_sum|   1|   1000000|     100|0.16144850|  PASSED
+          rgb_lagged_sum|   2|   1000000|     100|0.66997505|  PASSED
+          rgb_lagged_sum|   3|   1000000|     100|0.54744094|  PASSED
+          rgb_lagged_sum|   4|   1000000|     100|0.15684876|  PASSED
+          rgb_lagged_sum|   5|   1000000|     100|0.06950708|  PASSED
+          rgb_lagged_sum|   6|   1000000|     100|0.04118395|  PASSED
+          rgb_lagged_sum|   7|   1000000|     100|0.62558494|  PASSED
+          rgb_lagged_sum|   8|   1000000|     100|0.06955632|  PASSED
+          rgb_lagged_sum|   9|   1000000|     100|0.80323801|  PASSED
+          rgb_lagged_sum|  10|   1000000|     100|0.95324347|  PASSED
+          rgb_lagged_sum|  11|   1000000|     100|0.92104340|  PASSED
+          rgb_lagged_sum|  12|   1000000|     100|0.68759225|  PASSED
+          rgb_lagged_sum|  13|   1000000|     100|0.21127858|  PASSED
+          rgb_lagged_sum|  14|   1000000|     100|0.97290617|  PASSED
+          rgb_lagged_sum|  15|   1000000|     100|0.33770624|  PASSED
+          rgb_lagged_sum|  16|   1000000|     100|0.14037461|  PASSED
+          rgb_lagged_sum|  17|   1000000|     100|0.42891060|  PASSED
+          rgb_lagged_sum|  18|   1000000|     100|0.01741981|  PASSED
+          rgb_lagged_sum|  19|   1000000|     100|0.01825942|  PASSED
+          rgb_lagged_sum|  20|   1000000|     100|0.82574915|  PASSED
+          rgb_lagged_sum|  21|   1000000|     100|0.55886738|  PASSED
+          rgb_lagged_sum|  22|   1000000|     100|0.96301438|  PASSED
+          rgb_lagged_sum|  23|   1000000|     100|0.35504422|  PASSED
+          rgb_lagged_sum|  24|   1000000|     100|0.86742325|  PASSED
+          rgb_lagged_sum|  25|   1000000|     100|0.97050104|  PASSED
+          rgb_lagged_sum|  26|   1000000|     100|0.45785583|  PASSED
+          rgb_lagged_sum|  27|   1000000|     100|0.91905828|  PASSED
+          rgb_lagged_sum|  28|   1000000|     100|0.53348048|  PASSED
+          rgb_lagged_sum|  29|   1000000|     100|0.19985210|  PASSED
+          rgb_lagged_sum|  30|   1000000|     100|0.63540309|  PASSED
+          rgb_lagged_sum|  31|   1000000|     100|0.88671466|  PASSED
+          rgb_lagged_sum|  32|   1000000|     100|0.87499608|  PASSED
+         rgb_kstest_test|   0|     10000|    1000|0.94490633|  PASSED
+         dab_bytedistrib|   0|  51200000|       1|0.21636554|  PASSED
+                 dab_dct| 256|     50000|       1|0.35659461|  PASSED
+            dab_filltree|  32|  15000000|       1|0.49053255|  PASSED
+            dab_filltree|  32|  15000000|       1|0.24508716|  PASSED
+           dab_filltree2|   0|   5000000|       1|0.27633380|  PASSED
+           dab_filltree2|   1|   5000000|       1|0.93106328|  PASSED
+            dab_monobit2|  12|  65000000|       1|0.21748673|  PASSED

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Dependencies are in pool_of_entropy.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Neil Slater
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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.

data/README.md

@@ -0,0 +1,151 @@
+# PoolOfEntropy
+[![Gem Version](https://badge.fury.io/rb/pool_of_entropy.png)](http://badge.fury.io/rb/pool_of_entropy)
+[![Build Status](https://travis-ci.org/neilslater/pool_of_entropy.png?branch=master)](http://travis-ci.org/neilslater/pool_of_entropy)
+[![Coverage Status](https://coveralls.io/repos/neilslater/pool_of_entropy/badge.png?branch=master)](https://coveralls.io/r/neilslater/pool_of_entropy?branch=master)
+[![Code Climate](https://codeclimate.com/github/neilslater/pool_of_entropy.png)](https://codeclimate.com/github/neilslater/pool_of_entropy)
+[![Dependency Status](https://gemnasium.com/neilslater/pool_of_entropy.png)](https://gemnasium.com/neilslater/pool_of_entropy)
+
+PoolOfEntropy is a pseudo random number generator (PRNG) based on secure hashes,
+intended to bring back the feeling of 'personal luck' that some gamers may feel when rolling
+their *own* dice. An instance of the PoolOfEntropy class could be assigned to a player, or
+to each die in a game, and it can be influenced (similar to throwing a die differently), or
+personalised by feeding in arbitrary data (e.g. a picture of the player, a favourite saying).
+It can handle these influences whilst remaining unbiased and fair on each roll.
+
+PoolOfEntropy is *probably* secure when used appropriately. However, cryptographic security is
+not its purpose. The core purpose is for playing with random number generation and non-standard
+sources of entropy. The choice of name is supposed to reflect this.
+
+If you are looking for a secure PRNG in Ruby, good for generating session codes or
+server-side secrets, use the standard library SecureRandom.
+
+If you think that rolling all your dice on an anonymous server has removed a little bit of soul
+from your game sessions, or if you want to generate unbiased random numbers using input from your
+laptop's microphone or mobile's accellerometer as a source, then PoolOfEntropy might be for you.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pool_of_entropy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pool_of_entropy
+
+## Usage
+
+Create a new generator:
+
+    pool = PoolOfEntropy.new
+
+Get a random number:
+
+    pool.rand( 20 )
+
+Influence the next random number (but not any others):
+
+    pool.modify_next( 'I hope this works! Whatever!' )
+    pool.rand( 20 )
+
+    # Also
+    pool.modify_next( 'I hope this works! Whatever!' ).rand( 20 )
+
+Influence all random numbers until change mind (but do not alter internal state):
+
+    pool.modify_all( 'Gawds help me in my hour of need!' )
+
+    # All these are modified in same way, the two modifier types "stack"
+    pool.rand( 20 )
+    pool.rand( 20 )
+    pool.modify_next( 'And I really mean it!' ).rand( 20 )
+
+Alter internal state of pool (aka customise or "collect entropy"):
+
+    pool.update_state( 'Purple is my favourite colour.' )
+
+## Rationale
+
+### Properties of Software Random Numbers
+
+Software PRNGs available are designed to produce data that cannot be statistically separated
+from an ideal unbiased "truly random" source. There are quite a few algorithms that can do that,
+with differing degrees of success. Current best-in-class generators are pretty good at creating
+psuedo random data that has no discernable pattern.
+
+Generators used for games also need another trait - they need to be unpredictable to the end users.
+Often that is not strictly true in the academic sense, for example a well-informed user with enough
+time and skill could predict the next output from Ruby's rand() method. However, when this really
+needs to be true, you can use a Crytogaphically Secure PRNG (CSPRNG). Ruby's SecureRandom cannot
+be predicted from outside the system. Part of how CSPRNGs achieve unpredicatbility is by collecting
+entropy from sources within the computer - this might be timing of events from network cards and
+keyboard presses, or by sampling from deliberately noisy circuits.
+
+### Properties of Dice
+
+A humble 6-sided die achieves similar statistics and unpredictability, but in a different way.
+Unbiased statistical randomness is achieved by making the shape and density as regular as possible.
+It also assumes the user has "rolled well enough", which is quite tricky to define, but obviously just
+placing the die with the number you want facing up does not count.
+
+Unpredictability for the physical die comes from lack of precise control. Imperfections and
+microscopic details of where the die is rolling have a large impact. Quantum mechanics may
+also have an impact if a die collides and bounces enough. Also, a huge influence is how the
+die is thrown, and that comes from the person throwing it. No-one can control their nerves
+and muscles to a degree where they "roll well enough" but can consciously choose the
+exact result on the die. However, the impulse you give to a die when you throw it caused
+by your nerves, bones and muscles. This gives many people a feeling of agency and relationship
+to the end result. It may just be a random number, but in some sense it is *your random
+number because you generated it*.
+
+### Normal PRNGs Used To Simulate Dice
+
+When it comes to finding computer-based sources of randomness, you will find many systems
+that excel at producing results that are statistically random. Ruby's rand() is already
+very good at that. Computer-based PRNGs can apparently be made closer to ideal unbiased
+randomness than physical dice (or at least beyond any realistic ability to measure it).
+
+Truly unpredictable sources are also easy enough to find. They make themselves unpredictable
+by collecting entropy from sources on the machines where they run, that no-one can predict.
+
+However, there has been a cost to the user's agency. If I was playing a game
+using one of these sources, even though it was fair in the sense that the outcomes could
+well be the same, it gives me the same feeling as if another player was rolling all the dice.
+In a role-playing game, it feels the same as if the DM was rolling all the dice. Now sometimes
+and for some (many/most?) people that's OK. But other times, part of the fun is in rolling
+the dice yourself. I would be happy rolling computer dice, but only if somehow it was
+"me" rolling them.
+
+### What PoolOfEntropy Attempts To Do
+
+That is the mission of this gem: To create a simple PRNG where the results are connected as much
+as possible to the end user. This has to be achieved without compromising the
+good features of fairness and unpredictability that PRNGs and CSPRNGs have in general.
+
+Luckily this can be achieved using an approach that many CSPRNGs already use - using a
+data source to seed number generation. The main difference between PoolOfEntropy and
+regular CSPRNGs used to protect your computer on the internet is how this "entropy" is sourced.
+In a secure system, entropy is sourced from multiple places - anywhere that data can be
+gathered that an imagined attacker will have a hard time guessing the value. In PoolOfEntropy
+this is subverted - the end user supplies any data they like, and the gem treats it
+as "entropy". Technically, if you were an attacker, this would not be called entropy at
+all (because you know it) - however, to the machinery of the PRNG, or to me as a fellow
+player in a dice game, it counts just fine.
+
+By default PoolOfEntropy objects start off with some machine-collected entropy from SecureRandom
+to avoid trivial attacks (of always using the dice in the exact same way). You could view this
+as representing the environment or the die itself (all the scratches and imperfections that
+you cannot control, and have no influence over). Or, under an honour system of not repeating
+yourself you can switch off that default.
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/pool_of_entropy/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+desc "PoolOfEntropy unit tests"
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.pattern = "spec/*_spec.rb"
+  t.verbose = false
+end
+
+task :default => [:test]

data/lib/pool_of_entropy.rb

@@ -0,0 +1,160 @@
+require "pool_of_entropy/version"
+require "pool_of_entropy/core_prng"
+
+# This class models a random number generator that can mix user input into
+# the generation mechanism in a few different ways.
+#
+# An object of the class has an internal state for generating numbers, plus
+# holds processed user data for "mixing" into the output.
+#
+# @example Using default internal state, initialised using SecureRandom.random_bytes
+#  prng = PoolOfEntropy.new
+#  prng.rand( 20 )
+#  # E.g. => 12
+#
+# @example A customised PRNG, seeded with some user data, using webcam for "true" randomness
+#  prng = PoolOfEntropy.new :size => 4, :blank => true, :seeds = [ 'My Name' ]
+#  loop do
+#    prng.add_to_pool( Webcam.image.bytes ) # Imagined Webcam interface
+#    prng.rand( 20 )
+#    # E.g. => 12
+#    sleep 5
+#  end
+#
+
+class PoolOfEntropy
+
+  # Creates a new random number source. All parameters are optional.
+  # @param [Hash] options
+  # @option options [Integer] :size, number of 512-bit (64 byte) blocks to use as internal state, defaults to 1
+  # @option options [Boolean] :blank, if true then initial state is all zeroes, otherwise use SecureRandom
+  # @option options [Array<String>] :seeds, if provided these are sent to #add_to_pool during initialize
+  # @return [PoolOfEntropy]
+  def initialize options = {}
+    unless options.is_a? Hash
+      raise TypeError, "Expecting an options hash, got #{options.inspect}"
+    end
+
+    size = 1
+    if options[:size]
+      size = Integer( options[:size] )
+      if size < 1 || size > 256
+        raise ArgumentError, "Size of pool must be in Range 1..256, got #{size}"
+      end
+    end
+
+    initial_state = if options[:blank]
+      "\x0" * size * 64
+    else
+      SecureRandom.random_bytes( size * 64 )
+    end
+
+    @core_prng = CorePRNG.new( size, initial_state )
+
+    if options[:seeds]
+      unless options[:seeds].is_a? Array
+        raise TypeError, "Expected value for :seeds to be an Array, got #{options[:seeds].inspect}"
+      end
+      options[:seeds].each do |seed|
+        add_to_pool( seed )
+      end
+    end
+
+    @next_modifier_queue = []
+    @fixed_modifier = nil
+  end
+
+  # Cloning creates a deep copy with identical PRNG state and modifiers
+  # @return [PoolOfEntropy]
+  def clone
+    Marshal.load( Marshal.dump( self ) )
+  end
+
+  # Same functionality as Kernel#rand or Random#rand, but using
+  # current pool state to generate number, and including zero, one or
+  # two modifiers that are in effect.
+  # @param [Integer,Range] max if 0 then will return a Float
+  # @return [Float,Fixnum,Bignum] type depends on value of max
+  def rand max = 0
+    if max.is_a? Range
+      bottom = max.first
+      top = max.last
+      return( nil ) if top < bottom
+      return bottom + generate_integer( ( top - bottom + 1 ) )
+    else
+      effective_max = max.to_i.abs
+      if effective_max == 0
+        return generate_float
+      else
+        return generate_integer( effective_max )
+      end
+    end
+  end
+
+  # Stores the hash of one or more string modifiers that will be used
+  # just once each to modify results of calls to #rand. Temporary "next"
+  # modifiers and the "all" modifier are combined if both are in effect.
+  # Modifiers change the end result of a call to #rand(), but do *not*
+  # affect the internal state of the data pool used by the generator.
+  # @param [Array<String>] modifiers
+  # @return [PoolOfEntropy] self
+  def modify_next *modifiers
+    modifiers.each do |modifier|
+      if modifier.nil?
+        @next_modifier_queue << nil
+      else
+        @next_modifier_queue << Digest::SHA512.digest( modifier.to_s )
+      end
+    end
+    self
+  end
+
+  # Stores the hash of a single string modifier that will be used
+  # to modify results of calls to #rand, until this modifier is
+  # reset. Temporary "next" modifiers and the "all" modifier are
+  # combined if both are in effect.  Modifiers change the end result
+  # of a call to #rand(), but do *not*
+  # affect the internal state of the data pool used by the generator.
+  # @param [String,nil] modifier
+  # @return [PoolOfEntropy] self
+  def modify_all modifier
+    @fixed_modifier = modifier
+    unless @fixed_modifier.nil?
+      @fixed_modifier = Digest::SHA512.digest( @fixed_modifier.to_s )
+    end
+    self
+  end
+
+  # Changes the internal state of the data pool used by the generator,
+  # by "mixing in" user-supplied data. This affects all future values
+  # from #rand() and cannot be undone.
+  # @param [String] data
+  # @return [PoolOfEntropy] self
+  def add_to_pool data
+    @core_prng.update( data )
+    self
+  end
+
+  # Empties the "next" modifier queue and clears the "all" modifier.
+  # @return [PoolOfEntropy] self
+  def clear_all_modifiers
+    @next_modifier_queue = []
+    @fixed_modifier = nil
+    self
+  end
+
+  private
+
+  def use_adjustments
+    [ @fixed_modifier, @next_modifier_queue.shift ].compact
+  end
+
+  def generate_float
+    @core_prng.read_float( *use_adjustments )
+  end
+
+  def generate_integer max
+    @core_prng.generate_integer( max, *use_adjustments )
+  end
+
+end