pool_of_entropy 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 455d13c29630cf9a7255e9d4f76d1ee8ac7dd32b
-  data.tar.gz: 4b61829c13593ed3aa534d6ca462b04ca7139b66
+  metadata.gz: 4bfa3a0e0d42e79d2af5b13539692da02db0d33c
+  data.tar.gz: 97f2e7d2a51605afeb88dbf2c1560e8829b91595
 SHA512:
-  metadata.gz: f14bf6fdfc0466312c67608ca9bbb966ce5fbef1166d690d8baef622d4311fa9d8fa473bf5f5d292fdef38da9e8e08a5f2ef39ca20de677d59a9bb8ba9e6233f
-  data.tar.gz: acc6a94d9bd4f2e436d783489863fcf0e9bd97c3be5f25033b676aefdde9f6136f7e3c58bfd7013e845f3530a4cfa6aa718b3c9261683f88d1f68c972af959d2
+  metadata.gz: 2a67971cfcae21b459bd249154c7b3ab74ec94f36c7b08c146928196084840a074a83c01faad59fd4e8eb23be888e02a74945c9b01b77a2264e44d908723d5e9
+  data.tar.gz: 73db8b9f6f8d8c8db1873a4d3be54eecf41793f0b7a6ab60a3c8225a2526de41d7508c07e7844b1adb60479dd155fa647511a08a9488d3695bb89a9499cfce99

data/.yardopts

@@ -0,0 +1,7 @@
+lib/**/*.rb
+--exclude ext
+--no-private
+-
+README.md
+LICENSE.txt
+DIEHARDER_TEST.md

data/DIEHARDER_TEST.md

@@ -8,15 +8,28 @@ 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
+All modern cryptographic PRNGs should be expected to pass Dieharder. Although
+passing the test does not imply a secure random number generator, failing
+it consistently implies an insceure one, that could be predicted.
+Ruby's built-in rand(), an implementation of the Mersenne Twister algorithm,
+should also pass.
+
+Note that there are over 100 tests, and a test that scores a p-value below
+0.01 would be marked "WEAK". For a perfect PRNG it is reasonable to expect
+maybe one to five "WEAK" results in a single run. It was just chance -
+there is roughly a 32% chance that a perfect PRNG gets all Dieharder tests to
+cleanly pass. The usual way to deal with WEAK results is to repeat the offending
+tests and show that other p-values are just as likely.
+
+Generally, when a PRNG fails a Dieharder test systematically, you see a
+very strong signal, p-value below 0.00001 for several related tests.
+
+The test report below 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.
+statistically random numbers. As it happens, there were no "WEAK" results
+this time.
 
-## Date run: 9 May 2014
+## Date run: 9-12 May 2014
 
 Completing all the tests took roughly 3 days.
 

data/RATIONALE.md

@@ -0,0 +1,74 @@
+# Rationale for PoolOfEntropy
+
+## 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 an impact. Quantum mechanics, which
+as far as we know is inherently probability-based, may also have an impact if a die collides
+and bounces enough. Also, a big influence, mechanically and philosophically, 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 is 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.

data/README.md

@@ -12,9 +12,10 @@ to each die in a game, and it can be influenced (similar to throwing a die diffe
 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.
+PoolOfEntropy is *probably* secure when used appropriately, and in a very limited sense.
+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.
@@ -43,108 +44,86 @@ Create a new generator:
 
     pool = PoolOfEntropy.new
 
-Get a random number:
+Get a random number. Not feeding the generator with any customisation
+means it is completely deterministic based on current internal state. The
+analogy here might be "trusting to Fate":
 
     pool.rand( 20 )
 
-Influence the next random number (but not any others):
+Influence the next random number (but not any others). This is analogous to
+shaking or throwing dice in a certain way. Only the next result from rand()
+is affected:
 
-    pool.modify_next( 'I hope this works! Whatever!' )
+    pool.modify_next( 'Shake the die.' )
     pool.rand( 20 )
 
     # Also
-    pool.modify_next( 'I hope this works! Whatever!' ).rand( 20 )
+    pool.modify_next( 'Shake the die.' ).rand( 20 )
 
-Influence all random numbers until change mind (but do not alter internal state):
+    # This next result will not be influenced,
+    # we re-join the deterministic sequence of the PRNG:
+    pool.rand
+
+Influence the next three random numbers. Data supplied to modify_next is
+put in a queue, first in, first out:
+
+    pool.modify_next( 'Shake the die lots.' )
+    pool.modify_next( 'Roll the die cautiously.' )
+    pool.modify_next( 'Drop the die from a great height and watch it bounce.' )
+
+    pool.rand  # influenced by 'Shake the die lots.'
+    pool.rand  # etc
+    pool.rand
+
+    pool.rand #  . . . and back to main sequence
+
+Influence all random numbers from this point forward. This is analogous to
+having a personal style of throwing dice, or perhaps a different environment
+to throw them in.
 
     pool.modify_all( 'Gawds help me in my hour of need!' )
 
-    # All these are modified in same way, the two modifier types "stack"
+    # All these are modified in same way
     pool.rand( 20 )
     pool.rand( 20 )
+
+    # The two modifier types "stack", and this is modified twice
     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.
+Remove modfiers:
+
+    # Just the "all" modifier
+    pool.modify_all( nil )
+
+    # Insert a pause into the "next" queue
+    pool.modify_next( nil )
+
+    # Re-set "next" and "all" modifiers
+    pool.clear_all_modifiers
+
+Alter internal state of pool. This mixes in any entropy in the supplied
+data, and changes the deterministic sequence going forward. This is
+analogous to long-term alterations to dice, the environment, or
+person throwing the dice.
+
+    pool.add_to_pool( 'Purple is my favourite colour.' )
+
+All the inputs can be any length String, from any source. If the data
+contains *any* "true randomness" (however you want to define it, and however
+the String is formatted), then PoolOfEntropy
+will process that (using SHA-512) into unbiased results. If you care
+about your own source of randomness being more "important" than
+the initial state of the PRNG, or its continued deterministic ticking,
+then make use of the modifiers and/or add data to the pool frequently.
+
+## More information
+
+ * [Rationale](RATIONALE.md)
+ * [Dieharder test of statistical randomness](DIEHARDER_TEST.md)
 
 ## Contributing
 
-1. Fork it ( http://github.com/<my-github-username>/pool_of_entropy/fork )
+1. Fork it ( http://github.com/neilslater/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`)

data/lib/pool_of_entropy.rb

@@ -35,30 +35,13 @@ class PoolOfEntropy
       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
+    size = size_from_options( options )
 
-    initial_state = if options[:blank]
-      "\x0" * size * 64
-    else
-      SecureRandom.random_bytes( size * 64 )
-    end
+    initial_state = state_from_options( options, size )
 
     @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
+    seed_from_options( options )
 
     @next_modifier_queue = []
     @fixed_modifier = nil
@@ -157,4 +140,33 @@ class PoolOfEntropy
     @core_prng.generate_integer( max, *use_adjustments )
   end
 
+  def state_from_options( options, size )
+    if options[:blank]
+      "\x0" * size * 64
+    else
+      SecureRandom.random_bytes( size * 64 )
+    end
+  end
+
+  def size_from_options( options )
+    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
+    size
+  end
+
+  def seed_from_options( options )
+    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
+  end
 end

data/lib/pool_of_entropy/core_prng.rb

@@ -33,20 +33,8 @@ class PoolOfEntropy::CorePRNG
   # @param [Integer] mix_block_id
   # @return [PoolOfEntropy::CorePRNG]
   def initialize size = 1, initial_state = SecureRandom.random_bytes( 64 * Integer(size) ), mix_block_id = 0
-    @size = Integer( size )
-    if @size < 1 || @size > 256
-      raise ArgumentError, "Size of pool must be in Range 1..256, got #{@size}"
-    end
-    unless initial_state.is_a? String
-      raise TypeError, "Initial state must be a String, got #{initial_state.inspect}"
-    end
-    @state = initial_state.clone
-    @state.force_encoding( 'BINARY' )
-
-    if @state.size != size * 64
-      raise ArgumentError, "Initial state bad size - expected #{size * 64} bytes, got #{@state.size} bytes"
-    end
-
+    @size = validate_size( size )
+    @state = validate_state( initial_state, size )
     @mix_block_id = Integer( mix_block_id ) % @size
   end
 
@@ -129,7 +117,6 @@ class PoolOfEntropy::CorePRNG
   def generate_integer top, *adjustments
     power = 1
     sum = 0
-    lower_bound = 0
     words = []
 
     loop do
@@ -137,11 +124,8 @@ class PoolOfEntropy::CorePRNG
       sum = 2**32 * sum + words.shift
       power *= 2**32
       lower_bound = sum * top / power
-      upper_bound = ( (sum + 1) * top ) / power
-      break if lower_bound == upper_bound
+      break lower_bound if lower_bound == ( (sum + 1) * top ) / power
     end
-
-    lower_bound
   end
 
   private
@@ -158,4 +142,24 @@ class PoolOfEntropy::CorePRNG
     folded_32bits.pack('L>*')
   end
 
+  def validate_size i
+    size = Integer( i )
+    if size < 1 || size > 256
+      raise ArgumentError, "Size of pool must be in Range 1..256, got #{size}"
+    end
+    size
+  end
+
+  def validate_state( initial_state, size )
+    unless initial_state.is_a? String
+      raise TypeError, "Initial state must be a String, got #{initial_state.inspect}"
+    end
+    state = initial_state.clone
+    state.force_encoding( 'BINARY' )
+
+    if state.size != size * 64
+      raise ArgumentError, "Initial state bad size - expected #{size * 64} bytes, got #{state.size} bytes"
+    end
+    state
+  end
 end

data/lib/pool_of_entropy/version.rb

@@ -1,3 +1,3 @@
 class PoolOfEntropy
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/core_prng_spec.rb

@@ -35,6 +35,8 @@ describe PoolOfEntropy::CorePRNG do
       end
 
       it "should fail with bad state data" do
+        expect { PoolOfEntropy::CorePRNG.new( 1, :boo ) }.to raise_error TypeError
+        expect { PoolOfEntropy::CorePRNG.new( 1, [] ) }.to raise_error TypeError
         expect { PoolOfEntropy::CorePRNG.new( 1, '' ) }.to raise_error ArgumentError
         expect { PoolOfEntropy::CorePRNG.new( 1, "\x0" * 63 ) }.to raise_error ArgumentError
         expect { PoolOfEntropy::CorePRNG.new( 1, "\x0" * 200 ) }.to raise_error ArgumentError

data/spec/pool_of_entropy_spec.rb

@@ -20,6 +20,12 @@ describe PoolOfEntropy do
         end
       end
 
+      it "should fail when param is not a hash" do
+        expect { PoolOfEntropy.new( [:size,12] ) }.to raise_error TypeError
+        expect { PoolOfEntropy.new( '' ) }.to raise_error TypeError
+        expect { PoolOfEntropy.new( :size ) }.to raise_error TypeError
+      end
+
       it "should fail with incorrect :size param" do
         expect { PoolOfEntropy.new( :size => -12 ) }.to raise_error ArgumentError
         expect { PoolOfEntropy.new( :size => -1 ) }.to raise_error ArgumentError
@@ -48,7 +54,7 @@ describe PoolOfEntropy do
         (10..20).map { |x| pool.rand(x) }.should == [8, 3, 0, 12, 11, 2, 4, 8, 1, 11, 18]
       end
 
-      it "should accept and use :seed array" do
+      it "should accept and use :seeds array" do
         pool = PoolOfEntropy.new( :blank => true, :seeds => ['foo'] )
         pool.should be_a PoolOfEntropy
         (10..20).map { |x| pool.rand(x) }.should == [9, 1, 3, 7, 8, 12, 14, 5, 11, 5, 6]
@@ -57,10 +63,15 @@ describe PoolOfEntropy do
         pool.should be_a PoolOfEntropy
         (10..20).map { |x| pool.rand(x) }.should == [8, 1, 5, 8, 2, 7, 11, 8, 8, 13, 14]
       end
+
+      it "should fail if :seeds param is not an array" do
+        expect { PoolOfEntropy.new( :seeds => -12 ) }.to raise_error TypeError
+        expect { PoolOfEntropy.new( :seeds => { :seeds => [2] } ) }.to raise_error TypeError
+        expect { PoolOfEntropy.new( :seeds => 'more_seeds' ) }.to raise_error TypeError
+      end
     end
   end
 
-
   describe "instance methods" do
     pool_types = [
       [
@@ -239,6 +250,18 @@ describe PoolOfEntropy do
               pool_copy.rand.should == pool.rand
             end
           end
+
+          it "treats a nil modifier as 'do not modify'" do
+            pool_copy = pool.clone
+            10.times do
+              pool_copy.modify_next( 'hello', nil, 'goodbye' )
+              pool_copy.rand.should_not == pool.rand
+              pool_copy.rand.should == pool.rand
+              pool_copy.rand.should_not == pool.rand
+              pool_copy.rand.should == pool.rand
+              pool_copy.rand.should == pool.rand
+            end
+          end
         end # modify_next
 
         describe "#modify_all" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pool_of_entropy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Neil Slater
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-13 00:00:00.000000000 Z
+date: 2014-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -91,9 +91,11 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- ".yardopts"
 - DIEHARDER_TEST.md
 - Gemfile
 - LICENSE.txt
+- RATIONALE.md
 - README.md
 - Rakefile
 - lib/pool_of_entropy.rb