tss 0.1.1 → 0.2.0

data/README.md

@@ -1,9 +1,14 @@
 # TSS - Threshold Secret Sharing
 
 [![Gem Version](https://badge.fury.io/rb/tss.svg)](https://badge.fury.io/rb/tss)
+[![Dependency Status](https://gemnasium.com/badges/github.com/grempe/tss-rb.svg)](https://gemnasium.com/github.com/grempe/tss-rb)
 [![Build Status](https://travis-ci.org/grempe/tss-rb.svg?branch=master)](https://travis-ci.org/grempe/tss-rb)
 [![Coverage Status](https://coveralls.io/repos/github/grempe/tss-rb/badge.svg?branch=master)](https://coveralls.io/github/grempe/tss-rb?branch=master)
 [![Code Climate](https://codeclimate.com/github/grempe/tss-rb/badges/gpa.svg)](https://codeclimate.com/github/grempe/tss-rb)
+[![Inline docs](http://inch-ci.org/github/grempe/tss-rb.svg?branch=master)](http://inch-ci.org/github/grempe/tss-rb)
+
+Ruby Docs : [http://www.rubydoc.info/gems/tss](http://www.rubydoc.info/gems/tss)
+
 
 ## WARNING : BETA CODE
 
@@ -46,54 +51,46 @@ advanced error correction schemes. These extras are not currently implemented.
 
 ## TL;DR
 
-No time for docs? Here is how to get going in 10 seconds or less with the
-CLI or in Ruby. The CLI defaults to using `human` shares, and Ruby defaults
-to a binary octet string representation. The default is `3 out of 5` threshold
-sharing.
-
-### CLI (Human Shares)
-
-```text
-~/src$ gem install tss
-Successfully installed tss-0.1.0
-1 gem installed
-~/src$ tss split
-Enter your secret:
-secret >  my deep dark secret
-tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQBDoW7GJ66g6nQHQZVM_iUxMVEO7NHlwDaEM5FYsVwhBSfio-WF-w2gqSKRjBp6YyqTQKR
-tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQCxKBLxPsXuW4e7xE0zKiso49aEyuMKNIhjISe7ga865KDnBBpE1iZ6ESUkaWojKE3yNbc
-tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQDp1zQuADISueqk2UK3yNdBDh7XGlyoD2R6X9y-BCoI7iwAE02A8aj8vKO9ticeJpQMvDi
-tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQEgzj1RJXwKbu0pa5Z5qssmoX0cz22gVg8UCc6tasiqbDNi7bq_xKUczpYuc7utwDyPxV1
-tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQF4MRuOG4v2jIA2dpn9SDdPTLVPH9ICbeMNdzWo702YZr-F-u174yuaYxC3rPaQzuVxTNL
-~/src$ tss combine
-Enter shares, one per line, blank line or dot (.) to finish:
-share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQBDoW7GJ66g6nQHQZVM_iUxMVEO7NHlwDaEM5FYsVwhBSfio-WF-w2gqSKRjBp6YyqTQKR
-share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQCxKBLxPsXuW4e7xE0zKiso49aEyuMKNIhjISe7ga865KDnBBpE1iZ6ESUkaWojKE3yNbc
-share>  tss~v1~4a993275528d5ec7~3~NGE5OTMyNzU1MjhkNWVjNwIDADQDp1zQuADISueqk2UK3yNdBDh7XGlyoD2R6X9y-BCoI7iwAE02A8aj8vKO9ticeJpQMvDi
-share>  .
+No time for docs? Here is how to get going in a minute, using the
+command line or Ruby, with the default `3 out of 5` secret sharing.
 
-Secret Recovered and Verified!
+### Command Line Interface (CLI)
 
-identifier : 4a993275528d5ec7
+```sh
+$ echo 'secret unicode characters ½ ♥ 💩' | bundle exec bin/tss split -O /tmp/shares.txt
+$ bundle exec bin/tss combine -I /tmp/shares.txt
+
+RECOVERED SECRET METADATA
+*************************
+hash : 6d1bc4242998bc170d35d374ebdf39295b271db900de25d249563a4622f113e0
+hash_alg : SHA256
+identifier : 6b02cfcfc24a2b50
+process_time : 0.55ms
 threshold : 3
-processing time (ms) : 0.64
 secret :
-**************************************************
-my deep dark secret
-**************************************************
+secret unicode characters ½ ♥ 💩
 ```
 
-### Ruby (Binary Octet Shares)
+### Ruby
 
-```text
-~/src$ irb
-irb(main):001:0> require 'tss'
-=> true
-irb(main):002:0> shares = TSS.split(secret: 'my deep dark secret')
-=> ["ab87eb60ae14dd87\x02\x03\x004\x01\xC6+\xC8\x9F\xE4\x7F\x85\x17\xBD\xF6\xE6\xE3m\xB9\xFF\x8CGoS\x90\xB0{\xAB\x04N\xE2\x8F\xA0\xDC\x06\xC7Y\xBE\xCD?\xBDe9\xF3\xDF\xEA\xC9s\x105\xA4\xD8TZw\x9E", "ab87eb60ae14dd87\x02\x03\x004\x02T\xBB\xEF\x12\x81\xE2\xD2\x8Et\x95\x8Eg\xE6x=HD8\xAD\xE5\xF2'OdBO4vL\xF90\xA5c\x82\xE8\x11\x94\x8E\xEEV\xB3\xAFh\xB7\x80Ac\x15\xD9\xC7\x93", "ab87eb60ae14dd87\x02\x03\x004\x03\xFF\xE9\a\xE9\x00\xF8'\xB9\xAD\x02\x1A\xEF\xAB\xB2\xA7\xA7q2\x8A\x84\xFBC\v\ny\x98\x12\xA2C\x9B\xBB\xC2qY\x05e\xF6\xC5\x11\x11K\xF6:\xEA\xE8\xF8\f\x8C4\x94\xA2", "ab87eb60ae14dd87\x02\x03\x004\x04\xD4e\xB5\xD2o\x8AxJ\x96\xBB\x80o\xDCC\x12\xA0u\xE0\xB7\xACP\x82\x14\x13\x04\xD0\xE1\x82\xC4:k\\\xA8\xC1g\xA2}\"\xCF\x04x\xEC*\xB9\xC8q,\x8F\xE1\xF6\xB4", "ab87eb60ae14dd87\x02\x03\x004\x05\x7F7])\xEE\x90\x8D}O,\x14\xE7\x91\x89\x88O@\xEA\x90\xCDY\xE6P}?\a\xC7V\xCBX\xE0;\xBA\x1A\x8A\xD6\x1Fi0C\x80\xB5x\xE4\xA0\xC8C\x16\f\xA5\x85"]
-irb(main):003:0> secret = TSS.combine(shares: shares)
-=> {:hash_alg=>"SHA256", :identifier=>"ab87eb60ae14dd87", :num_shares_provided=>5, :num_shares_used=>3, :processing_started_at=>"2016-04-13T19:37:14Z", :processing_finished_at=>"2016-04-13T19:37:14Z", :processing_time_ms=>0.63, :secret=>"my deep dark secret", :shares_select_by=>"first", :combinations=>nil, :threshold=>3}
-irb(main):004:0> puts secret[:secret]
+```ruby
+$ bundle exec bin/console
+[1] pry(main)> require 'tss'
+=> false
+[2] pry(main)> shares = TSS.split(secret: 'my deep dark secret')
+=> ["tss~v1~72e84cd688bf24fc~3~NzJlODRjZDY4OGJmMjRmYwIDADQBVLUhLlOvz_VWjEge2gH7PtqTsnSCpbfmMSFX98XUp0BmQAeeOTGDL0GVeGATWjbBZvOm",
+ "tss~v1~72e84cd688bf24fc~3~NzJlODRjZDY4OGJmMjRmYwIDADQCmlZ_CZSBPk6m2-0WMEmcdzCsB8lH1oDalELd9VhlFPqby08kjm9tZBtONqXucgcnuFlQ",
+ "tss~v1~72e84cd688bf24fc~3~NzJlODRjZDY4OGJmMjRmYwIDADQDo5p-Q6JLgZuUNtdjyjsCKphawUx8bNhW0FYjdk7V_4RRnZpzsCzi00hLb4igNYYraY5Z",
+ "tss~v1~72e84cd688bf24fc~3~NzJlODRjZDY4OGJmMjRmYwIDADQEuqHxd94BQK1V-db70VLZxdIULyVIOGDrE7w7K3SVnk0UaEMf9xJFaYpKrXical7nR9PT",
+ "tss~v1~72e84cd688bf24fc~3~NzJlODRjZDY4OGJmMjRmYwIDADQFg23wPejL_3hnFOyOKyBHmHri6aBzgjhnV6jFqGIldTPePpZIyVHK3tlP9FXSLd_rlgTa"]
+[3] pry(main)> secret = TSS.combine(shares: shares)
+=> {:hash=>"f1b91fef6a7535a974d3644c3eac16d2c907720c981290214d5d1db7cdb724af",
+ :hash_alg=>"SHA256",
+ :identifier=>"72e84cd688bf24fc",
+ :process_time=>0.58,
+ :secret=>"my deep dark secret",
+ :threshold=>3}
+[4] pry(main)> puts secret[:secret]
 my deep dark secret
 => nil
 ```
@@ -143,6 +140,14 @@ or [TweetNaCl.js](https://github.com/dchest/tweetnacl-js).
 * Put careful thought into how you want to distribute shares. It often makes
 sense to give individuals more than one share.
 
+## Documentation
+
+There is pretty extensive inline documentation. You can view the latest
+auto-generated docs at [http://www.rubydoc.info/gems/tss](http://www.rubydoc.info/gems/tss)
+
+You can check my documentation quality score at
+[http://inch-ci.org/github/grempe/tss-rb](http://inch-ci.org/github/grempe/tss-rb?branch=master)
+
 ## Supported Platforms
 
 TSS is continuously integration tested on the following Ruby VMs:
@@ -190,7 +195,7 @@ if any signed gem does not match its signature.
 
 ```
 # All dependent gems must be signed and verified.
-gem install tss -P MediumSecurity
+gem install tss -P HighSecurity
 ```
 
 ```
@@ -219,108 +224,149 @@ You can also clone the repository and verify the signatures locally using your
 own GnuPG installation. You can find my certificates and read about how to conduct
 this verification at [https://www.rempe.us/keys/](https://www.rempe.us/keys/).
 
-## Command Line Interface
+## Command Line Interface (CLI)
 
 When you install the gem a simple `tss` command-line interface (CLI)
-is also installed and should be available on your PATH.
+is also installed and should be available on your `$PATH`.
 
-The CLI is a simple interface for splitting and combining secrets. You can
-see the options available with `tss help`, `tss help split`, or `tss help combine`.
+The CLI is a user interface for splitting and combining secrets. You can
+see the full set of options available with `tss help`, `tss help split`,
+or `tss help combine`.
 
 ### CLI Secret Splitting
 
-```
-$ tss help split
-Usage:
-  tss split SECRET
-
-Options:
-  -t, [--threshold=threshold]          # # of shares, of total, required to reconstruct a secret
-  -n, [--num-shares=num_shares]        # # of shares total that will be generated
-  -i, [--identifier=identifier]        # A unique identifier string, 0-16 Bytes, [a-zA-Z0-9.-_]
-  -h, [--hash-alg=hash_alg]            # A hash type for verification, NONE, SHA1, SHA256
-  -f, [--format=format]                # Share output format, binary or human
-                                       # Default: human
-  -p, [--pad-blocksize=pad_blocksize]  # Block size # secrets will be left-padded to, 0-255
-
-Description:
-  `tss split` will generate a set of Threshold Secret Sharing shares from the SECRET provided. To protect your secret from being saved in
-  your shell history you will be prompted for the single-line secret.
+A secret to be split can be provided using one of three
+different input methods; `STDIN`, a path to a file, or when prompted
+interactively. In all cases the secret should be `UTF-8` or
+`US-ASCII` encoded text and be no larger than 65,535 Bytes
+(including header and hash verification bytes).
 
-  Optional Params:
+Each method for entering a secret may have pros and cons from a security
+perspective. You need to understand what threat model you want to protect
+against in order to choose wisely. Here are a few examples for how to
+split a secret.
 
-  num_shares : The number of total shares that will be generated.
+**Example : `STDIN`**
 
-  threshold : The threshold is the number of shares required to recreate a secret. This is always a subset of the total shares.
+Can read the secret from `STDIN` and write the split shares to a file. Be
+cautioned that this method may leave command history which may contain your
+secret.
 
-  identifier : A unique identifier string that will be attached to each share. It can be 0-16 Bytes long and use the characters
-  [a-zA-Z0-9.-_]
+```text
+echo 'a secret' | bundle exec bin/tss split -O /tmp/shares.txt
+```
 
-  hash_alg : One of NONE, SHA1, SHA256. The algorithm to use for a one-way hash of the secret that will be split along with the secret.
+**Example : `--input-file`**
 
-  pad_blocksize : An Integer, 0-255, that represents a multiple to which the secret will be padded. For example if pad_blocksize is set to
-  8, the secret 'abc' would be left-padded to '00000abc' (the padding char is not zero, that is just for illustration).
+Can read the secret from a file and write the split shares to `STDOUT`. Be
+cautioned that storing the secret on a filesystem may expose you to certain
+attacks since it can be hard to fully erase files once written.
 
-  format : Whether to output the shares as a binary octet string (RTSS), or the same encoded as more human friendly Base 64 text with some
-  metadata prefixed.
+```text
+$ bundle exec bin/tss split -I /tmp/secret.txt
+tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsBvAVAo1dH3QrsYl0S30j2VVTu6dZLRe9EEk6zLtPTwZNYk-t1e4SAA41D
+tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsCMfy6YlI-CQrd-l93Xtw8YqOWSP5ToolKTaZyO2fPYzceaaVmB30ycdVr
+tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsD4IDasmAapmVFkuYPMvuavCtXiJgPZsaBHglGm4FU_U2rGZzfapRk-ZNN
+tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsEbId8z1yNfEkDcezJpstkYenGLhJCMRglx2c0arPDS-YuXyiiNQQ-jYlq
+tss~v1~3f784d9d04dff796~3~M2Y3ODRkOWQwNGRmZjc5NgIDACsFvfscH26p0yabGVWxyuzCv2EH7nQe9VfulMgAylVY1ZybLxEbWO1oBc9M
+```
 
-  Example using all options:
+**Example : `interactive`**
 
-  $ tss split -t 3 -n 6 -i abc123 -h SHA256 -p 8 -f human
+Can read the secret interactively from a terminal and write the split shares
+to `STDOUT`. This method is more secure since the secret will not be stored
+in the command shell history or in a file on a filesystem that is hard to
+erase securely. It does not protect you from simple keylogger attacks though.
 
-  Enter your secret:
+```text
+$ bundle exec bin/tss split
+Enter your secret, enter a dot (.) on a line by itself to finish :
+secret >  the vault password is:
+secret >  V0ulT!
+secret >  .
+tss~v1~546604c0b5e9138b~3~NTQ2NjA0YzBiNWU5MTM4YgIDAD8BK-9qlyxRFFQypFLwzM_tLWOv-NRziwnc6blqFP8eh8wLro4qiQwBKfI0KuuvM0u1C6th1vxsyW8vyolXQ-4=
+tss~v1~546604c0b5e9138b~3~NTQ2NjA0YzBiNWU5MTM4YgIDAD8CEjeK01kAwE1wb7-wvLLlHoe6FGzhl7Hg9TCz_Npw7u0b31OpijFIKdxELfbnhvius7vGqn6KqQKqq69s4Co=
+tss~v1~546604c0b5e9138b~3~NTQ2NjA0YzBiNWU5MTM4YgIDAD8DTbCFZAMwoXU2650hAw5_XJZxzNHhJrJqLPy1vARk8APzWkgP7K79AtbVn1C49HpBSP2OL-BLumaZZWbU7YI=
+tss~v1~546604c0b5e9138b~3~NTQ2NjA0YzBiNWU5MTM4YgIDAD8E9eVJ83Knw3Fq1e9VaFSKdPKUAugyBqXzCsqov6etQIfEYe8Vt-ZVu3Ax7L1MWBNt-AQLN7YtczAG4QZ_7wI=
+tss~v1~546604c0b5e9138b~3~NTQ2NjA0YzBiNWU5MTM4YgIDAD8FqmJGRCiXokksUc3E1-gQNuNf2lUyt6Z50wau_3m5Xmks5PSz0XngkHqgXhsTKpGCA0JDsijsYFQ1L8_H4qo=
+```
 
-  secret > my secret
+### CLI Share Combining
 
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADEBQ-AQG3PuU4oT4qHOh2oJmu-vQwGE6O5hsGRBNtdAYauTIi7VoIdi5imWSrswDdRy
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADECM0OK5TSamH3nubH3FJ2EGZ4Yux4eQC-mvcYY85oOe6ae3kpvVXjuRUDU1m6sX20X
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADEDb7yF4Vhr1JqNe2Nc8IXo98hmKAxsqC3c_Mn3r3t60NxQMC22ate51StDOM-BImch
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADEEIXU0FajldnRtEQMLK-ZYMO2MRa0NmkBFfNAOx7olbgXLkVbP9txXMDsdokblVwke
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADEFfYo7EcQUOpMH09Ggz_403rvy1r9_ckI_Pd_hm1tRxX8FfzEWyXMAoFCKTOfIKgMo
-  tss~v1~abc123~3~YWJjMTIzAAAAAAAAAAAAAAIDADEGDSmh74Ng8WTziMGZXAm5XcpFLqDl2oP4MH24XhYf33IIg1WsPIyMAznI0DJUeLpN
+You can use the CLI to enter shares in order to recover a secret. Of course
+you will need at least the number of shares necessary as determined
+by the threshold when your shares were created. The `threshold` is visible
+as the third field in every `human` formatted share.
 
-```
+As with splitting a secret, there are also three methods of getting the shares
+into the CLI. `STDIN`, a path to a file containing shares, or interactively.
 
-**Example CLI Split Usage**
+Here are some simple examples of using each:
 
-For security purposes you will be prompted for your secret and cannot enter it
-on the command line.
+**Example : `STDIN`**
 
+```text
+$ echo 'a secret' | bundle exec bin/tss split | bundle exec bin/tss combine
+
+RECOVERED SECRET METADATA
+*************************
+hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
+hash_alg : SHA256
+identifier : fff58c38b14734f3
+process_time : 0.34ms
+threshold : 3
+secret :
+a secret
 ```
-$ tss split -i abc
-Enter your secret:
-secret >  abc
-tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQB4zjuAvBL1P2AJciAHdicf6I2qxMkLGo2Hhr4dhI_v1CSKrE=
-tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQCNAFhHSQd8nDgihYUrdM_IsMJqYZicLuk8jBS06kUJLZTU2g=
-tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQDtlvspaxAmQJhYDTV8Ut9AM8dISVFPXIE-1A2EavU-hTBbHQ=
-tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQE-NVr8ofyfwYVW9_2yauIT7t4Hmt9WeFNN_ADt7vpThYNeeU=
-tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQFeo_mSg-vFHSUsf03lTPKbbdslshaFCjtPpBndbkpkLSfRvk=
-```
-
-### CLI Share Combining
 
-**Example CLI Combine Usage**
+**Example : `--input-file`**
 
-For security purposes you will be prompted for your shares and cannot them
-on the command line.
+```text
+$ echo 'a secret' | bundle exec bin/tss split -O /tmp/shares.txt
+$ bundle exec bin/tss combine -I /tmp/shares.txt
+
+RECOVERED SECRET METADATA
+*************************
+hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
+hash_alg : SHA256
+identifier : ae2983e30e0471fe
+process_time : 0.47ms
+threshold : 3
+secret :
+a secret
+```
 
-```sh
-tss combine
-Enter shares, one per line, blank line or dot (.) to finish:
-share> tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQB4zjuAvBL1P2AJciAHdicf6I2qxMkLGo2Hhr4dhI_v1CSKrE=
-share> tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQCNAFhHSQd8nDgihYUrdM_IsMJqYZicLuk8jBS06kUJLZTU2g=
-share> tss~v1~abc~3~YWJjAAAAAAAAAAAAAAAAAAIDACQDtlvspaxAmQJhYDTV8Ut9AM8dISVFPXIE-1A2EavU-hTBbHQ=
-share>
+**Example : `interactive`**
 
-Secret Recovered and Verified!
+```text
+$ cat /tmp/shares.txt
+# THRESHOLD SECRET SHARING SHARES
+# 2016-04-19T23:57:17Z
+# https://github.com/grempe/tss-rb
+
+
+tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoBRjAH7wA0ncxJr3GliBqKxedf3bGaQH6AscuLqxtrKxxtxuC7A7a5Sqk=
+tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoClWVu75w-XHhoUgkbV5XaJ11stZCB5Z8HTArpv4QsIYDBpNO9DHQTbQ4=
+tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoDsnUaZf94pMArKZL7jmavzk9Qa6ZAvOB8e8nEAt0nyS6ga0XBucQOyGc=
+tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoETCWwSGLHcutzGCLb1yOkH7i6MF7j2b0wr0ZsUh6LuBmx6FkN2MbTkTc=
+tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoFazXEwgGBilMwY7k7DtDR9qqG7mgigMJLmIVB70eAULfQJ89xbXbONF4=
+
+$ bundle exec bin/tss combine
+Enter shares, one per line, and a dot (.) on a line by itself to finish :
+share>  tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoBRjAH7wA0ncxJr3GliBqKxedf3bGaQH6AscuLqxtrKxxtxuC7A7a5Sqk=
+share>  tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoClWVu75w-XHhoUgkbV5XaJ11stZCB5Z8HTArpv4QsIYDBpNO9DHQTbQ4=
+share>  tss~v1~ae2983e30e0471fe~3~YWUyOTgzZTMwZTA0NzFmZQIDACoDsnUaZf94pMArKZL7jmavzk9Qa6ZAvOB8e8nEAt0nyS6ga0XBucQOyGc=
+share>  .
 
-identifier : abc
+RECOVERED SECRET METADATA
+*************************
+hash : d4ea4551e9ff2cf56303875b1901fb8608a6164260c3b20c0976c7b606a4efc0
+hash_alg : SHA256
+identifier : ae2983e30e0471fe
+process_time : 0.7ms
 threshold : 3
-processing time (ms) : 0.48
 secret :
-**************************************************
-abc
-**************************************************
+a secret
 ```
 
 ## Ruby : Splitting a Secret
@@ -352,10 +398,9 @@ of Bytes. e.g. `'foo'.bytes.to_a`
 The `num_shares` and `threshold` values are Integers representing the total
 number of shares desired, and how many of those shares are required to
 re-create a `secret`. Both arguments must be Integers with a value
-between `1-255` inclusive. They can be Strings if directly coercible to Ints.
-The `num_shares` value must be greater-than-or-equal-to the `threshold` value.
-If you don't pass in these options they will be set to `threshold = 3` and
-`num_shares = 5` by default.
+between `1-255` inclusive. The `num_shares` value must be
+greater-than-or-equal-to the `threshold` value. If you don't pass in
+these options they will be set to `threshold = 3` and `num_shares = 5` by default.
 
 The `identifier` is a `0-16` Byte String that will be embedded in
 each output share and should uniquely identify a secret. All shares output
@@ -375,15 +420,14 @@ and then combined with it prior to secret splitting. This means that the hash
 is protected the same way as the secret. The algorithm used is
 `secret || hash(secret)`. You can use one of `NONE`, `SHA1`, or `SHA256`.
 
-The `format` arg takes a String Enum with either `'binary'` or `'human'` values.
-This instructs the output of a split to either provide an array of binary octet
-strings (standard RTSS format for interoperability), or a human friendly
-URL Safe Base 64 encoded version of that same binary output. The `human` format
-can be easily shared in a tweet, email, or even a URL. The `human` format is
-prefixed with `tss-VERSION-IDENTIFIER-THRESHOLD-` to make it easier to visually
-compare shares and see if they have matching identifiers and if you have
-enough shares to reach the threshold. Note, this prefix is not parsed
-or used by the `tss` combiner code at all. It is only for user convenience.
+The `format` arg takes a String Enum with either `'human'` (default) or
+`'binary'` values. This instructs the output of a split to either provide an
+array of binary octet strings (a standard RTSS format for interoperability), or
+a human friendly URL Safe Base 64 encoded version of that same binary output.
+The `human` format can be easily shared in a tweet, email, or even a URL. The
+`human` format is prefixed with `tss~VERSION~IDENTIFIER~THRESHOLD~` to make it
+easier to visually compare shares and see if they have matching identifiers and
+if you have enough shares to reach the threshold.
 
 The `pad_blocksize` arg takes an Integer between 0..255 inclusive. Your secret
 **MUST NOT** *begin* with this character (which was chosen to make less likely).
@@ -432,27 +476,25 @@ threshold  = 3
 num_shares = 5
 identifier = SecureRandom.hex(8)
 hash_alg   = 'SHA256'
+format     = 'human'
 
-s = TSS.split(secret: secret, threshold: threshold, num_shares: num_shares, identifier: identifier, hash_alg: 'SHA256', pad_blocksize: 16)
+s = TSS.split(secret: secret, threshold: threshold, num_shares: num_shares, identifier: identifier, hash_alg: 'SHA256', pad_blocksize: 16, format: format)
 
-=> ["c70963b2e20fccfd\x02\x03\x001\x01\x1Fg4\xDC\xAA\x96\x9D3\xCB\xFB\xF7\xB0\x91}\xCA\xB7\x0E\xB0\xF3.}O\xD0&Z\x11\xB0\xAB\xF48f#*\xBA\xB7)l\x05\xAF4\xFA\x95\x9C\xF2\x8E\xA6\xB9=",
- "c70963b2e20fccfd\x02\x03\x001\x02Y|\x1F\x1Co\x8BW\f^\xFE\xA5\x92G\xA4\xD0K\xC6@G\xDC\x02\xBF\xF1\xAE\xE7\vP\xF1*\x9C\xA5$\edM#\xB0\xEBy\a}\xA18\rBZ\x8A\xEE",
- "c70963b2e20fccfd\x02\x03\x001\x03Y\x044\xDF\xDA{\xA5P\xB5g3P\xF6\xBB{\x86\x13#\xAC3\xBB\x92\x8F`\xCF\xEE\xF1Sz{\x10\x03\xB9\xAFZ71>(=\xF2HI\xA8\x16*\xC1\x04",
- "c70963b2e20fccfd\x02\x03\x001\x04\x90\xA3\\W\xFB\xFF.\xE8&\xA3\x13N\x968\xC5\xEEg\xA1\xD8\xB6\xD9\xE9\xAAMz\xA9\xF3H\e7#\xE7\xA8\r@\xD9\\\xB8\x7F\xF3Q\x8D\x80\xCF1~\x97P",
- "c70963b2e20fccfd\x02\x03\x001\x05\x90\xDBw\x94N\x0F\xDC\xB4\xCD:\x85\x8C''n#\xB2\xC23Y`\xC4\xD4\x83RLR\xEAK\xD0\x96\xC0\n\xC6W\xCD\xDDm.\xC9\xDEd\xF1je\x0E\xDC\xBA"]
+=> ["tss~v1~9fdfe2516240737e~3~OWZkZmUyNTE2MjQwNzM3ZQIDADEBe1METAFZDbpq7yHIFRvxr1PjBOLRnHzDyzDGrnDvYp90jMKPLWwo3eiWiuafRaYJ",
+ "tss~v1~9fdfe2516240737e~3~OWZkZmUyNTE2MjQwNzM3ZQIDADECOeQaLXYx99N2SDKutj0_smSonMdMMzeJc_CWPRT8nppHkdsUc7hW6cSw_RDcaKMF",
+ "tss~v1~9fdfe2516240737e~3~OWZkZmUyNTE2MjQwNzM3ZQIDADEDXagBfmgOlQY8xXIUg0SvZ-yYgORZzeWiyjRBmsDMLwG7bLmmswSAOllamqGZ-_fb",
+ "tss~v1~9fdfe2516240737e~3~OWZkZmUyNTE2MjQwNzM3ZQIDADEExmXZHYJsLzipmqYryl5SDlhJzdZxLh_2y5bM_tOOmdm9rpws3izJqHrzmCHQi5mn",
+ "tss~v1~9fdfe2516240737e~3~OWZkZmUyNTE2MjQwNzM3ZQIDADEFoinCTpxTTe3jF-aR_yfC29B50fVk0M3dclIbWQe-KEJBU_6eHpAfe-cZ_5CVGM15"]
 
  secret = TSS.combine(shares: s)
- => {:identifier=>"c70963b2e20fccfd",
-  :num_shares_provided=>5,
-  :num_shares_used=>3,
-  :processing_started_at=>"2016-04-10T00:58:04Z",
-  :processing_finished_at=>"2016-04-10T00:58:04Z",
-  :processing_time_ms=>0.37,
-  :secret=>"foo bar baz",
-  :shares_select_by=>"first",
-  :combinations=>nil,
-  :threshold=>3}
-  ```
+
+ => {:hash=>"dbd318c1c462aee872f41109a4dfd3048871a03dedd0fe0e757ced57dad6f2d7",
+ :hash_alg=>"SHA256",
+ :identifier=>"9fdfe2516240737e",
+ :process_time=>0.77,
+ :secret=>"foo bar baz",
+ :threshold=>3}
+ ```
 
 ## Ruby : Combining Shares to Recreate a Secret
 
@@ -506,28 +548,43 @@ in many times the life of the Universe. This option can only be used if the
 possible combinations for the number of shares and the threshold needed to
 reconstruct a secret result in a number of combinations that is small enough
 to have a chance at being processed. If the number of combinations will be too
-large then the an Exception will be raised before processing has started.
+large an Exception will be raised before processing has even started. The default
+maximum number of combinations that will be tried is 1,000,000.
+
+**Fun Fact**
+
+If 255 total shares are available, and the threshold value is 128, it would result in
+`2884329411724603169044874178931143443870105850987581016304218283632259375395`
+possible combinations of 128 shares that could be tried. That is *almost* as
+many combinations (`2.88 * 10^75`) as there are Atoms in the Universe (`10^80`).
 
 If the combine operation does not result in a secret being successfully
 extracted, then a `TSS::Error` exception will be raised.
 
+A great short read on this is
+[On the (Small) Number of Atoms in the Universe](http://norvig.com/atoms.html)
+
 ### Exception Handling
 
 Initial validation of options is done when the `TSS.split` or `TSS.combine`
 methods are called. If the arguments passed are of the wrong Type or value
-a `Dry::Types::ConstraintError` Exception will be raised.
+a `TSS::ArgumentError` Exception will be raised.
 
-The splitting and combining operations may also raise `TSS::ArgumentError`
-or `TSS::Error` exceptions as they are run.
+The splitting and combining operations may also raise the following
+exception types:
 
-All Exception messages should include hints as to what went wrong in the
-`ex.messages` attribute.
+`TSS::NoSecretError`, `TSS::InvalidSecretHashError`,
+`TSS::ArgumentError`, `TSS::Error`
+
+All Exceptions should include hints as to what went wrong in the
+`#message` attribute.
 
 ## Share Data Formats
 
 ### RTSS Binary
 
-TSS provides shares in a binary data format with the following fields:
+TSS provides shares in a binary data format with the following fields, and
+by default this binary data is wrapped in a `'human'` text format:
 
 `Identifier`. This field contains 16 octets. It identifies the secret
 with which a share is associated.  All of the shares associated
@@ -574,20 +631,21 @@ octets. It contains the actual share data.
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
-This code has been tested for binary compatibility with the
+This data format has been tested for binary compatibility with the
 [seb-m/tss](https://github.com/seb-m/tss) Python implementation of TSS. There
 are test cases to ensure it remains compatible.
 
 ### RTSS Human Friendly Wrapper
 
-To make `tss` more friendly to use when sending shares to others an enhanced
-version of the RTSS binary data format is provided that is more human friendly.
+To make `tss` friendlier to use when sending shares to others, an enhanced
+text wrapper around the RTSS binary data format is provided.
 
-Shares formatted this way can easily be shared via any communication channel.
+Shares formatted this way can easily be shared via most any communication channel.
 
 The `human` data format is simply the same RTSS binary data, URL Safe Base64
-encoded, and prefixed with a String thet contains the following tilde `~`
-separated elements. The `~` is used to ensure the share remains URL Safe.
+encoded, and prefixed with a String thet contains tilde `~` separated elements.
+The `~` is used as it is compatible with the URL Safe data and the allowed
+characters in the rest of the human format string.
 
 ```text
 tss~VERSION~IDENTIFIER~THRESHOLD~BASE64_ENCODED_BINARY_SHARE
@@ -624,15 +682,13 @@ After checking out the repo, run `bin/setup` to install dependencies. Then,
 run `rake test` to run the tests. You can also run `bin/console` for an
 interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then
-run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and tags, and push the `.gem` file
-to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 You can run the Command Line Interface (CLI) in development
 with `bundle exec bin/tss`.
 
+The formal release process can be found in [RELEASE.md](https://github.com/grempe/tss-rb/blob/master/RELEASE.md)
+
 ### Contributing
 
 Bug reports and pull requests are welcome on GitHub

data/RELEASE.md

@@ -0,0 +1,105 @@
+# Gem Release Process
+
+Don't use the `bundle exec rake release` task. It is more convenient,
+but it skips the process of signing the version release task.
+
+## Run Tests
+
+```sh
+$ rake test_all
+```
+
+## Git Push
+
+```sh
+$ git push
+```
+
+Check for regressions in automated tests:
+
+* [https://travis-ci.org/grempe/tss-rb](https://travis-ci.org/grempe/tss-rb)
+* [https://coveralls.io/github/grempe/tss-rb?branch=master](https://coveralls.io/github/grempe/tss-rb?branch=master)
+* [https://codeclimate.com/github/grempe/tss-rb](https://codeclimate.com/github/grempe/tss-rb)
+* [http://inch-ci.org/github/grempe/tss-rb](http://inch-ci.org/github/grempe/tss-rb)
+
+## Bump Version Number and edit CHANGELOG.md
+
+```sh
+$ vi lib/tss/version.rb
+$ git add lib/tss/version.rb
+$ vi CHANGELOG.md
+$ git add CHANGELOG.md
+```
+
+## Local Build and Install w/ Signed Gem
+
+The `build` step should ask for PEM passphrase to sign gem. If it does
+not ask it means that the signing cert is not present.
+
+Build:
+
+```sh
+$ rake build
+Enter PEM pass phrase:
+tss 0.1.1 built to pkg/tss-0.1.1.gem.
+```
+
+Install locally w/ Cert:
+
+```sh
+$ gem uninstall tss
+$ rbenv rehash
+$ gem install pkg/tss-0.1.1.gem -P MediumSecurity
+Successfully installed tss-0.1.1
+1 gem installed
+```
+
+## Git Commit Version and CHANGELOG Changes, Tag and push to Github
+
+```sh
+$ git add lib/tss/version.rb
+$ git add CHANGELOG.md
+$ git commit -m 'Bump version v0.1.1'
+$ git tag -s v0.1.1 -m "v0.1.1" SHA1_OF_COMMIT
+```
+
+Verify last commit and last tag are GPG signed:
+
+```
+$ git tag -v v0.1.0
+...
+gpg: Good signature from "Glenn Rempe (Code Signing Key) <glenn@rempe.us>" [ultimate]
+...
+```
+
+```
+$ git log --show-signature
+...
+gpg: Good signature from "Glenn Rempe (Code Signing Key) <glenn@rempe.us>" [ultimate]
+...
+```
+
+Push code and tags to GitHub:
+
+```
+$ git push
+$ git push --tags
+```
+
+## Push gem to Rubygems.org
+
+```sh
+$ gem push pkg/tss-0.1.1.gem
+```
+
+Verify Gem Push at [https://rubygems.org/gems/tss](https://rubygems.org/gems/tss)
+
+## Create a GitHub Release
+
+Specify the tag we just pushed to attach release to. Copy notes from CHANGELOG.md
+
+[https://github.com/grempe/tss-rb/releases](https://github.com/grempe/tss-rb/releases)
+
+## Announce Release on Twitter
+
+The normal blah, blah, blah.

data/Rakefile

@@ -1,16 +1,21 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'wwtd/tasks'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = false
+  t.warning = false
 end
 
 Rake::TestTask.new(:bench) do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_benchmark.rb']
+  t.verbose = false
+  t.warning = false
 end
 
 # a long running brute force burn-in test
@@ -18,6 +23,10 @@ Rake::TestTask.new(:burn) do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_brute.rb']
+  t.verbose = false
+  t.warning = false
 end
 
+task :test_all => [:test, :bench, :burn]
+
 task default: :test