vault-tree 0.1.0 → 0.3.3

data/.gitignore

@@ -19,8 +19,12 @@ pkg
 .vagrant/
 package.box
 
-# ignore contracts directory
-contracts/
-
 # ignore built gem
 *.gem
+
+# ignore .spec_in
+# for custom spec runs
+.spec_in
+
+# ignore mruby dir
+mruby/

data/CHANGE_LOG.md

@@ -0,0 +1,15 @@
+## 0.3.3
+
+* Update to RbNaCl 2.0.
+* Major changes to crypto lib interface
+* Now Require Libsodium >= 0.4.3
+
+## 0.2.3
+
+* Reorganize features dir to work with Relish
+* Modify some Cucumber features to explicitly take a hard coded contract
+
+## 0.2.1
+
+* First pass implementation of GENERATED_SHAMIR_KEY and ASSEMBLED_SHAMIR_KEY
+* Using version 0.3 of https://github.com/grempe/secretsharing

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    vault-tree (0.1.3)
-      rbnacl (= 1.1.0)
-      require_all
+    vault-tree (0.1.0)
+      rbnacl (= 2.0.0)
+      secretsharing (= 0.3)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    archive-tar-minitar (0.5.2)
     builder (3.2.2)
     cucumber (1.3.8)
       builder (>= 2.1.2)
@@ -19,11 +20,18 @@ GEM
     ffi (1.9.3)
     gherkin (2.12.2)
       multi_json (~> 1.3)
+    json (1.8.1)
+    mime-types (2.0)
     multi_json (1.8.1)
     multi_test (0.0.2)
-    rbnacl (1.1.0)
+    rbnacl (2.0.0)
       ffi
-    require_all (1.3.2)
+    relish (0.7)
+      archive-tar-minitar (>= 0.5.2)
+      json (>= 1.4.6)
+      rest-client (>= 1.6.1)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (2.14.1)
       rspec-core (~> 2.14.0)
       rspec-expectations (~> 2.14.0)
@@ -32,6 +40,7 @@ GEM
     rspec-expectations (2.14.3)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.3)
+    secretsharing (0.3)
 
 PLATFORMS
   ruby
@@ -39,5 +48,6 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.3)
   cucumber
+  relish
   rspec
   vault-tree!

data/README.md

@@ -6,7 +6,7 @@ Vault Tree is a collection of tools for building and executing distributed crypt
 
 Before you begin make sure you checkout the [Vault Tree Homepage] for an overview of the project.
 
-[Vault Tree Homepage]: http://www.vault-tree.org
+[Vault Tree Homepage]: http://vault-tree.org
 
 ### Welcome!
 
@@ -14,23 +14,19 @@ The Vault Tree Project consists of:
 
 * A JSON based DSL for building Distributed Crytographic Contracts
 * A a Ruby library to execute these contracts
-* A Github [Contracts Repository] that acts as a focal point of collaboration for developers writing and testing interesting crytographic contracts
+* A focal point of collaboration for developers writing and testing interesting crytographic contracts
 
-[Contracts Repository]: https://github.com/VaultTree/contracts
 
 ### Install
 
 Before you start:
 
-* If you just want to use Vault Tree to build and execute contracts go to the [Contracts Repository].
 * To use the library in your application or want to contribute code, you're in the right place.
 * Before you pull the trigger on the install remember we have a Vagrant Box.
 
-[Contracts Repository]: https://github.com/VaultTree/contracts
-
 Okay, lets begin.
 
-As a prerequisite get [libsodium] on you machine. This is the underlying cryptographic library that Vault Tree depends on.
+As a prerequisite get [libsodium] (>= 0.4.3) on you machine. This is the underlying cryptographic library that Vault Tree depends on.
 
 [libsodium]: https://github.com/jedisct1/libsodium
 
@@ -57,7 +53,7 @@ Now that you have libsodium, if you're a Ruby developer you know the drill from
 gem install vault-tree
 ```
 
-and then 
+and then
 
 ```
 require 'vault-tree'
@@ -89,18 +85,18 @@ Now you just need to Vagrant Up!
 This will download and boot a pre-packaged Linux virtual machine with Vault-Tree and all dependencies already installed.
 
 Once your VM is downloaded and built. You can go inside with:
- 
+
 ```
-  vagrant shh
+  vagrant ssh
 ```
 
 As a developer working on Vault Tree you can now go to the VM's directory:
 
 ```
-/vagrant 
+/vagrant
 ```
 
-and run `rake`. This will run all the tests and put you in a good spot to start exploring the code.
+and run `bundle` then `rake`. This will grab your dependincies, run all the tests, and leave you in a good spot to start exploring the code.
 
 If you're not already familiar, take a few minutes to learn about how Vagrant will [sync your files] to and from the guest machine.
 
@@ -108,11 +104,12 @@ If you're not already familiar, take a few minutes to learn about how Vagrant wi
 
 ### Is it production ready?
 
-Absolutely not. We have a long way to go.
+Are you serious? This project has like ... 1 fork and 1 star (Thanks Eric!).
+We have a long way to go.
 
-Here are some of the big issues that I could use your help on as we move to version 1.0:
+Here are some of the big issues that I'm thinking about as we move to version 1.0:
 
 * This is a crypto application so vulnerabilities need to be identified and corrected. We need more eyes in this area.
 * We we need to figure out if the supported keywords are sufficient to implement basic secure computation schemes.
-  - For example, Digital Signatures and HMACs are not implemented but could be.
+  - For example, Digital Signatures are not implemented but could be.
   - Should they be implemented? What is the use case? Ect. We need to have these conversations.

data/Rakefile

@@ -4,14 +4,29 @@ require 'cucumber/rake/task'
 require 'rspec/core/rake_task'
 require "bundler/gem_tasks"
 
-task :default => 'spec'
+task :default do
+  Rake::Task["cuke"].invoke
+  Rake::Task["contracts"].invoke
+  Rake::Task["spec"].invoke
+end
 
-Cucumber::Rake::Task.new('cuke') do |t|
+Cucumber::Rake::Task.new(:cuke) do |t|
   # -r means you require all support files first
   # this allows you to organize and run by subdirectory
   t.cucumber_opts = "-r features features --format pretty"
 end
 
-task :spec => 'cuke' do
-  STDOUT.write %x[rspec --format doc]
+Cucumber::Rake::Task.new(:contracts) do |t|
+  # -r means you require all support files first
+  # this allows you to organize and run by subdirectory
+  t.cucumber_opts = "-r features features/contracts --format pretty"
+end
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format doc"
+end
+
+desc 'Upload Features and Markdown to Relish'
+task :relish do
+  puts `relish push vault-tree/vault-tree`
 end

data/features/.nav

@@ -0,0 +1,11 @@
+- what_is_vault_tree.md (What is Vault Tree?)
+- enforcement_problem.md (Enforcement Problem)
+- decision_tree.md (Decision Trees)
+- contracts_and_vaults.md (Contracts and Vaults)
+- install_and_usage.md (Install and Usage)
+- manipulating_contracts.md (Manipulating Contracts)
+- keywords (Keywords):
+- exceptions.feature (Runtime Exceptions)
+- contracts (Example Contracts):
+- contributing_to_vault_tree.md (Contributing to Vault Tree)
+- native (Native Apps):

data/features/contracts/asymmetric_vault.feature

@@ -0,0 +1,23 @@
+Feature: Asymmetric Vaults
+
+  Goals:
+    * Illustrate the use of an Asymmetric Vault
+    * Understand the DH_KEY reserved word
+    * Illustrate an implementation of Public Key Encryption with Mutual Authentication
+      via the ECDH algorithm
+
+  Ideas:
+    * Notice in the contract that the Locking DH_KEY is formed with
+      a private key, and the public key of the reciprocal party
+    * The cooresponding Unlocking DH_KEY is built and authenticated with a private
+      key and the reciprocal public key
+
+Scenario: Bob Locks and Alice Unlocks with a Shared Key
+  Given Alice has the blank asymmetric vault contract
+  When she locks all of her public and private keys
+  And she sends the contract to Bob over the internet
+  Then Bob can access of her public keys but not her private keys
+  When Bob locks his public and private keys
+  And He fills and locks the vault containing the message using a DH_KEY
+  And he sends the contract back to Alice over the internet
+  Then Alice can unlock the message with a DH_KEY

data/features/contracts/block_chain_key_transfer.feature

@@ -0,0 +1,34 @@
+Feature: Block Chain Key Transfer
+
+  This contract introduces the idea of a Bitcoin key transfer.
+
+  Goal:
+    * Two parties wish to transfer the BTC signing key associated with a particular wallet address
+    * To effect this transfer they want to use only a Vault Tree JSON files and the BTC Block Chain
+    * The transfering party wants to maintain control over the precise moment the signing key is
+      released to the receiving party.
+
+  Ideas:
+    * The sending party can use a Block Chain wallet address as the locking key to a symmetric vault.
+    * After generating a hidden wallet address, the sender can use the address to lock the BTC signing
+      key in the vault.
+    * By spending Bitcoins from an origin wallet address (that is know the receiver) to the hidden
+      destination wallet address, the sending party is able to Reveal the encryption key needed to
+      unlock the symmetric vault.
+
+  Notes:
+    * This transfer could prove useful as a step in a more sophisticated contract.
+    * Here we are transfering a BTC Signing Key. This approach could work to transfer any
+      type of private information.
+    * Transfering Signed but Unbroadcasted transactions with this mechanism could open up
+      many new possibilities.
+
+Scenario: SENDER Transfers a BTC Signing Key to the RECEIVER
+
+  Given the SENDER has the blank contract template
+  And the SENDER chooses an origin address and a concealed destination address
+  And he locks away the secret BTC signing key
+  When the SENDER transfers the contract to the RECEIVER
+  Then the RECEIVER can access the origin wallet address
+  When the SENDER reveals the hidden wallet address by transfering bitcoins from the origin address
+  Then the RECEIVER can unlock the vault to recover the transfered signing key

data/features/contracts/one_two_three.feature

@@ -0,0 +1,22 @@
+Feature: One-Two-Three Contract
+
+  Goal:
+    * Used to demonstrate and test basic Vault Tree functionality
+    * It nicely illustrates how vault keys can be arranged to enforce the terms of a contract 
+    * If you are new to the Vault Tree Library it may be helpful to study the details of this contract
+      to gain a better understanding of the core concepts.
+
+  Ideas:
+    * Bob sets up a simple Scavenger Hunt for Alice
+    * He locks a Congratulations Message in the final vault
+    * In order to get to the final message Alice needs to unlock the preceeding vaults with the
+      appropriate keys
+
+Scenario: Alice and Bob Execute the One Two Three Contract
+  Given Alice has the blank contract
+  When she locks all of her attributes
+  And she sends the contract to Bob
+  Then Bob can access all of her public attributes
+  When Bob locks his attributes
+  And He fills and locks each of the three main vaults
+  Then Alice can execute the contract to recover the final message

data/features/contracts/readme.md

@@ -0,0 +1,111 @@
+Contracts are a central part of the [Vault Tree Project]. Here is what you
+need to know:
+
+* A Vault Tree Contract is simply a [JSON] text file
+* Every contract is composed of two parts:
+  - The **Header** section, which includes helpful meta data
+  - The **Vaults** section, which can be any collection of _vaults_ that form the
+    contract.
+* The way in which you, the contract author, organize the vaults will determine the **Self-Enforcing Terms** of your contract.
+* Each vault will typically contain either an **external data** string that is provided by one of the contract
+  participants, or a key to anther vault.
+
+### Writing and Simulating Contracts
+
+If you've made it to this far, then you're ready to build something. You're
+thinking to yourself:
+
+* For my Vault Tree Contract to be useful it probably needs to involve more than one person.
+* I think I can write a contract, but I really need a way to test it out and think through all the different scenarios.
+* When my final contract is complete it might involve network calls to pass it
+  between parties, queries the Bitcoin Block Chain, or some other crazy step involving the outside world.
+
+What I really need is a way to **Simulate** how the contract will be used in real life ...
+
+Enter [Cucumber].
+
+[Cucumber]: https://github.com/cucumber/cucumber
+
+Cucumber is a tool designed to test complicated full stack web applications. However, we are going to use it for a slightly different purpose.
+
+Take a look at this simple example:
+
+```Gherkin
+Scenario: Alice and Bob Execute the One Two Three Contract
+  Given Alice has the blank contract
+  When she locks all of her attributes
+  And she sends the contract to Bob
+  Then Bob can access all of her public attributes
+  When Bob locks his attributes
+  And He fills and locks each of the three main vaults
+  Then Alice can execute the contract to recover the final message
+```
+
+Great. So we wrote down how the contract is used in some funny looking format  ... so what.
+
+Well, what if we associate each one of these steps in the scenario with some simple Ruby code that interacts with the Vault Tree API. Here are the first three step definitions:
+
+```Ruby
+# This file: "features/core/one_two_three/one_two_three.steps.rb"
+# Associated Contract: "core/one_two_three.0.7.0.json"
+
+Given(/^Alice has the blank contract$/) do
+  contract_path = VaultTree::ContractsRepo::PathHelpers.core_contracts('one_two_three.0.7.0.json')
+  @contract_json = File.read(contract_path)
+end
+
+When(/^she locks all of her attributes$/) do
+  @contract = VaultTree::Contract.new(@contract_json, master_passphrase: 'ALICE_SECURE_PASS', external_data: {})
+  @contract = @contract.close_vault('alice_decryption_key')
+  @contract = @contract.close_vault('alice_public_encryption_key')
+end
+
+When(/^she sends the contract to Bob$/) do
+  @contract_json = @contract.as_json
+  @bobs_external_data = {"congratulations_message" => "CONGRATS! YOU OPENED THE THIRD VAULT."}
+  @contract = VaultTree::Contract.new(@contract_json, master_passphrase: 'BOB_SECURE_PASS', external_data: @bobs_external_data)
+end
+```
+
+Not only can we easily run the contract throught the library to test that it
+works, we have a straight forward mechanism for simulating otherwise complicated
+steps like sending the JSON representation of the contact _over the wire_.
+
+Some items to keep in mind when you run Cucumber scenarios:
+
+* Run `rake` instead of `cucumber` when in the VM `/vagrant` dir
+* This will:
+  - Take care of the wierd cucumber configuration flags needed to handle the unconventional directory structure.
+  - Execute all cucumber scenarios associated with contracts in the `/core` directory
+
+### Design Opinions
+
+Vault Tree was written to give contract authors a large amount of flexibilty.
+There are however some design constraints that were put in place to get the
+community off to a good start.
+
+I'll update these in the coming months as we get some more experience writing simple contracts.
+
+* The Vault Tree interpreter is stateless and always takes a contract as an input
+* All external data required for contract execution must be provided to the
+interpreter by the run time that is invoking the API. For example, there are no
+plans for the interpreter to make any network requests or do file IO.
+
+
+##### Notes for Developers
+
+* Let's practice strict [semantic versioning] in managing our contracts.
+* Edit contracts with the help of an application like [js beatifier].
+* Ensure proper JSON format with a tool like this [json parser].
+* Changes to core contracts should produce clean Git diffs.
+
+[lab]: https://github.com/VaultTree/contracts/tree/master/lab
+[core]: https://github.com/VaultTree/contracts/tree/master/core
+[Contracts Repository]: https://github.com/VaultTree/contracts 
+[JSON]: http://www.json.org 
+[Vault Tree Homepage]: http://www.vault-tree.org
+[Vault Tree Project]: http://www.vault-tree.org
+[semantic versioning]: http://semver.org
+[js beatifier]: http://jsbeautifier.org 
+[json parser]: http://json.parser.online.fr
+[json]: http://json.org

data/features/contracts_and_vaults.md

@@ -0,0 +1,134 @@
+### Contracts
+
+Now that we've explored the ideas of a **Contract**, **Contract Enforcement**, and a **Decision Tree**, we can better understand what makes a Vault Tree Contract unique.
+
+#### Vaults
+
+Vault Tree Contracts are made by assembling simple structures called **Vaults**.
+
+A vault is like a digital lock box that stores a single unambiguous piece of information. This piece of information is needed to continue the execution of a contract beyond a certain event.
+
+The light bulb should turn on when you realize that vaults can hold not only valuable external information, but the **keys to other vaults**.
+
+#### Contract Properties
+
+Like regular contracts, Vault Tree Contracts are still modeled as a Decision
+Tree of events and outcomes. Unlike regular contracts, they have the added
+benefit of being a **Distributed Cryptographic Contract**. This means: 
+
+* To each event in the contract we add a corresponding vault 
+* A contract becomes a structured collection of vaults
+* Each Vault encrypts a piece of secret information. This can be external
+information such as a _URL_ or a _Bitcoin Wallet Address_. More often, a vault will contain the unlocking key to another vault in the contract.
+* The way in which the contract author **chooses to structure** the releationship between vaults, will determine how the contract is **Enforced**.
+
+#### Complete Contracts
+
+Because Vault Tree Contracts should be **self-enforcing** and **programatically executable**, they are by convention [complete contracts].
+
+In the context of the interpreting library this means the following:
+
+* Each **Leaf Vault** in the graph should unlock a set of conditions that represents an acceptable contract **Outcome**.
+* There does not exist any combination of conditions that would ultimately fail to unlock a leaf vault.
+
+[complete contracts]: http://en.wikipedia.org/wiki/Complete_contract
+
+#### Contracts as JSON Files
+
+Just as a common contract is often written on a piece of paper, a Vault Tree contract is typed into a single text file that can be copied and distributed to anyone.
+
+We chose the [JSON] file format for respresenting contracts. JSON is becoming the mainstream internet serialization format and can be easily read by both humans and computers.
+
+[JSON]: www.json.org
+
+
+### Vaults
+
+We discussed earlier how Vault Tree contracts are just a collection of vaults
+arranged to enforce the terms of the contract.
+
+Let's take a look at an example vault:
+
+```javascript
+"bob_random_vault_key": {
+  "fill_with": "RANDOM_NUMBER",
+  "lock_with": "KEY['bob_vault_key']",
+  "unlock_with": "KEY['alice_vault_key']",
+  "contents": "rSGrWGL4mEYtpuIaWO/iVGXAA5UUyLeeImSV3SBXzb+C7DW3"
+}
+```
+
+It's important to keep in mind that, **every** vault follows this format. This convention for representing a vault should be sufficient to build any type of simplistic or sophisticated contract.
+
+#### Vault Id
+
+The **Vault Id** can be thought of as both the name and the **Unique** identifier of the vault.
+
+In this case we have:
+
+```
+"bob_random_vault_key"
+```
+
+Try to give meaningful names that give insight into the locked contents held within the vault. Also, by convention vault names should begin with the name of the vault owner.
+
+A vault owner is the contract party that is responsibily for filling and locking the vault. In this simple case we have **bob**, but in an employment contract for example, we may have vault owners named **employer** and **employee**.
+
+It is the responsibility of the contract author to assign vault owners in such a way that there are no contract [moral hazards] or [perverse incentives].
+
+[moral hazards]: http://en.wikipedia.org/wiki/Moral_hazard
+[perverse incentives]: http://en.wikipedia.org/wiki/Perverse_incentive
+
+#### Fill With
+
+The **fill_with** field identifies the source of the [Plaintext] contents of the
+vault. It can be:
+
+* a value generated by the Vault Tree library.
+* external information that is brought into the contract.
+* the contents of anther vault.
+
+In the example above, the Vault Tree interpreter knows to generate a simple random number, and place it into the vault.
+
+[Plaintext]: http://en.wikipedia.org/wiki/Plaintext 
+
+#### Lock With
+
+The **lock_with** field identifies the source of the vault's **Locking Key**. 
+
+
+#### Unlock With
+
+The **unlock_with** field naturally identifies the source of the vault's **Unlocking Key**.
+
+It may not be obvious, but the reference to the Unlocking key does not necessarily need to be the same as the reference to the **Locking Key**. Here are some examples of where this could be the case: 
+
+* The same key is used to lock and unlock the vault, but copies of this key are
+* held in two separate vaults. Take a look at the **Block Chain Key Transfer**
+* contract to see a good example of this.
+* Vault Tree supports the notion of an **Asymmetric Vault** through the _DSL Keyword_
+
+```
+DH_KEY
+```
+
+An Asymmetric Vault is locked and unlocked with the help of a [Public-Private](http://en.wikipedia.org/wiki/Public-key_cryptography) keypair. Vault Tree's underlying cryptographic library makes this possible by implementing a cutting edge variant of the [ECDH] key exchange protocol.  
+
+[ECDH]: http://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman
+
+#### Contents
+
+As you would expect, this field references the encrypted contents of the vault. In the example above you can see the _Base 64_ encoded ciphertext:
+
+```
+"contents": "rSGrWGL4mEYtpuIaWO/iVGXAA5UUyLeeImSV3SBXzb+C7DW3"
+```
+Here are some items to keep in mind:
+
+* Vaults are either **Empty** or **Closed**, this corresponds to either a **Blank Value** or a **Ciphertext Value**
+* If we want everyone to have access to the contents we simply lock the closed vault with a known public value. For a description on how to do this in practice see the _DSL Keyword_
+
+```
+UNLOCKED
+```
+