pool_of_entropy 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4bfa3a0e0d42e79d2af5b13539692da02db0d33c
-  data.tar.gz: 97f2e7d2a51605afeb88dbf2c1560e8829b91595
+  metadata.gz: 9282759abb1c13fd70a45b27da5f58030107bc23
+  data.tar.gz: 88da59e58548d584b72df4640be40be61aef9b37
 SHA512:
-  metadata.gz: 2a67971cfcae21b459bd249154c7b3ab74ec94f36c7b08c146928196084840a074a83c01faad59fd4e8eb23be888e02a74945c9b01b77a2264e44d908723d5e9
-  data.tar.gz: 73db8b9f6f8d8c8db1873a4d3be54eecf41793f0b7a6ab60a3c8225a2526de41d7508c07e7844b1adb60479dd155fa647511a08a9488d3695bb89a9499cfce99
+  metadata.gz: b158c97ffc614e6f40c5f769812a5f1441877e96c429e525875639c18f3c1a6f8699341bf81c062981e7eac2a2e986120718029facdb8bfe135e5ad8fc140d7f
+  data.tar.gz: c68191705fce736800291804d24d30c46e74be13906cde6cae5e46983ae1afaeaeb6d72aa5b4e4cb72110b06d2d9751b32034c3e2424381378f13d8fdf08518a

data/.yardopts

@@ -3,5 +3,7 @@ lib/**/*.rb
 --no-private
 -
 README.md
+RECIPES.md
+RATIONALE.md
 LICENSE.txt
 DIEHARDER_TEST.md

data/RATIONALE.md

@@ -9,8 +9,8 @@ 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
+time and skill could predict the next output from Ruby's rand() method. However, when your really
+need secure numbers, 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.
@@ -44,8 +44,8 @@ Truly unpredictable sources are also easy enough to find. They make themselves u
 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.
+using one of these sources, even though it was fair in the sense that the outcomes were chosen
+with equal chances, 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
@@ -63,12 +63,32 @@ regular CSPRNGs used to protect your computer on the internet is how this "entro
 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.
+as entropy. Technically, if you were an attacker, this would not be called entropy at
+all (because you know the exact value) - 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.
+yourself you can switch off that default.
+
+## What PoolOfEntropy Does Not Do: Superstition
+
+PoolOfEntropy will happily eat any string data and use it to help generate random numbers. It
+cannot tell, and therefore does not care, what the *meaning* of that data is. It cannot
+tell what you wish for, it is not "lady luck" in code form.
+
+Superstition is a natural human feeling. We blow on dice before throwing them to encourage results
+that we want, we avoid saying things lest we "tempt fate", and perform a thousand other
+minor rites in order to get supposed good luck. This is true even when intellectually we
+understand that truly random events are unbiased and there is no predictable cause and effect.
+You cannot be a "lucky person" in the sense that random number generators will somehow
+favour you. But the feeling is persistent, it seems inherent to human nature.
+
+You can bring superstition into your interactions with a computer PRNG; you may already do,
+if you play any computer game that uses random numbers. In some ways this gem encourages that,
+by giving you the ability to set things up with data that is meaningful for you. But bear
+in mind, that like a well-rolled die, the computer doesn't understand or care. The difference
+between PoolOfEntropy and most other PRNGs is supposed to be the difference between you
+rolling a die and someone else rolling it for you.

data/README.md

@@ -6,7 +6,7 @@
 [![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
+intended to bring back the feeling of 'personal agency' 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).
@@ -40,17 +40,40 @@ Or install it yourself as:
 
 ## Usage
 
-Create a new generator:
+### Create a new generator:
 
     pool = PoolOfEntropy.new
 
-Get a random number. Not feeding the generator with any customisation
+Or
+
+    pool = PoolOfEntropy.new :size => 24
+
+Or
+
+    pool = PoolOfEntropy.new :size => 24, :blank => true
+
+The :size parameter sets the amount of randomness that the pool
+can store, in multiples of 512 bits (or 64 bytes). The default
+size of 1 is fastest, and has a good distribution of values
+statistically. Larger pool sizes (up to 256) will calculate a
+little slower, but can be used to buffer more entropy from
+the #add_to_pool method.
+
+Setting :blank to true starts the pool with the entire pool
+zero, so that repeatedly using the generator in exactly the
+same way will return the same values.
+
+### 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). This is analogous to
+### 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:
 
@@ -64,7 +87,9 @@ is affected:
     # we re-join the deterministic sequence of the PRNG:
     pool.rand
 
-Influence the next three random numbers. Data supplied to modify_next is
+### 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.' )
@@ -77,7 +102,9 @@ put in a queue, first in, first out:
 
     pool.rand #  . . . and back to main sequence
 
-Influence all random numbers from this point forward. This is analogous to
+### 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.
 
@@ -90,7 +117,7 @@ to throw them in.
     # The two modifier types "stack", and this is modified twice
     pool.modify_next( 'And I really mean it!' ).rand( 20 )
 
-Remove modfiers:
+### Remove modfiers.
 
     # Just the "all" modifier
     pool.modify_all( nil )
@@ -101,7 +128,9 @@ Remove modfiers:
     # Re-set "next" and "all" modifiers
     pool.clear_all_modifiers
 
-Alter internal state of pool. This mixes in any entropy in the supplied
+### 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.
@@ -111,14 +140,17 @@ person throwing the dice.
 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
+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,
+the initial state of the PRNG or its deterministic progression,
 then make use of the modifiers and/or add data to the pool frequently.
 
 ## More information
 
  * [Rationale](RATIONALE.md)
+ * [Recipes and Suggestions](RECIPES.md)
  * [Dieharder test of statistical randomness](DIEHARDER_TEST.md)
 
 ## Contributing

data/RECIPES.md

@@ -0,0 +1,70 @@
+# Uses for PoolOfEntropy
+
+## DO NOT USE FOR: Monte-Carlo Simulations
+
+Although PoolOfEntropy can be seeded for repeatable sequences, and produces random numbers of
+suitable quality, it is a lot slower than other equally good options. Use Ruby's built in
+rand() or the Random class instead.
+
+## DO NOT USE FOR: Communications Security
+
+Although PoolOfEntropy can produce numbers of suitable quality, and is based
+on a secure hash design, it is not proven secure and is never likely to be. In
+addition, it operates on the application level in a Ruby process, and direct access
+to that process would allow it to be compromised very easily. Use SecureRandom
+instead.
+
+## Dice for Play-by-Mail
+
+This was one of the original design goals for the gem. One problem with games
+played where events happen offline is that random numbers may be required when
+a player is not present. By assigning an instance of PoolOfEntropy to each
+player, and letting the player provide data for modifiers or the pool, it
+allows the game to simulate fair dice rolls, and for the players to have influenced
+those rolls in advance. In a philosophical sense you could say the players
+have rolled the dice themselves.
+
+To create and use a pool for a player:
+
+    # Depending on how many dice rolls will be made offline, I recommend
+    # a largish pool here. This 4KB pool, if completely filled with
+    # quality random data for a player, could generate over 6500 rolls of a d20
+    # that you might consider to be "rolled by the player" (in the sense that
+    # an infinitely powerful machine that knew the initial state before user
+    # data was added would need to see the results from that many rolls before it
+    # could figure out what the new state was)
+
+    freds_entropy = PoolOfEntropy.new :size => 64
+
+    # Add Fred's data, assuming freds_input is an Array of Strings. Ideally you
+    # have at least same number of strings as :size param above. You can split
+    # large files into chunks for processing e.g. images or videos
+
+    freds_input.each do |data|
+       freds_entropy.add_to_pool( data )
+    end
+
+    # Save the pool for later use (example to file, but binary blob in database
+    # is also fine). Note you should encrypt this if players have access to the
+    # data and would know how to use PoolOfEntropy themselves.
+
+    File.open( 'fred.pool', 'wb' ) { |file| file.write Marshal.dump( freds_entropy ) }
+
+    # Open the pool up later to use it
+
+    freds_entropy = File.open( 'fred.pool', 'rb' ) { |file| Marshal.load( file.read ) }
+
+    # During the game, Fred rolls a die:
+
+    result = freds_entropy.rand( 20 ) + 1
+
+The gem games_dice will accept a PoolOfEntropy object as a generator for a dice object:
+
+    require 'games_dice'
+
+    freds_attack = GamesDice.create '1d20 + 6', freds_entropy
+
+    freds_attack.roll
+    # => 21
+    freds_attack.explain_result
+    # => "1d20: 15. 15 + 6 = 21"

data/lib/pool_of_entropy/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pool_of_entropy
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Neil Slater
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-15 00:00:00.000000000 Z
+date: 2014-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -97,6 +97,7 @@ files:
 - LICENSE.txt
 - RATIONALE.md
 - README.md
+- RECIPES.md
 - Rakefile
 - lib/pool_of_entropy.rb
 - lib/pool_of_entropy/core_prng.rb