e3db 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b7bf7131fc6fa268b207dcb119dae692505324de
-  data.tar.gz: c1324d103c48feebdd69ed266d3065c518e7ac81
+  metadata.gz: dd02fa9da7066c7c8de9049f56669116450e33f7
+  data.tar.gz: e72007bf75159c71428f7da2f39665f007649551
 SHA512:
-  metadata.gz: 2a56500cfab1e2387d3dc134a88cdf23b7a4e94f13fd2825429d90f9cafa9236b8b342ea1cebd19418f415e5c2f5fde05f80a93a98aecd9444a59937e51ed1f5
-  data.tar.gz: 7747c79c983b51fbd32a933851a59c7445a5dbcb316dfb522ca6fd60ba974d4137a65f3f4738765f68f9bd8968dc11ba16b0ac079dfe65b8d706afa8527d2a59
+  metadata.gz: 1b4b44c6d5f1e2b13bcd2d87eee8123dd7283b7db2fdb2adf05ea268b958d86adb1755ebfac334fccff32e585570e60ae68b5deb94f1375bd1631e8565953d0b
+  data.tar.gz: b4ccc70e9e0ae565f64473d065555f486498484aa8a75c654de99955a13f190efba9dae21fa073fce90699b0a94c6b69ceb96fb7248bc1321e83dad29ce57f12

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 .integration-test.json
+*~

data/LICENSE.md

@@ -0,0 +1,255 @@
+TOZNY NON-COMMERCIAL LICENSE
+
+
+THIS TOZNY NON-COMMERCIAL LICENSE PERMITS USE OF THE SOFTWARE ONLY BY
+GOVERNMENT AGENCIES, SCHOOLS, UNIVERSITIES, NON-PROFIT ORGANIZATIONS
+OR INDIVIDUALS ON PROJECTS THAT DO NOT RECEIVE EXTERNAL FUNDING OTHER
+THAN GOVERNMENT RESEARCH GRANTS AND CONTRACTS. FOR THE SPECIFIC
+LIMITATIONS, SEE SECTION 1.12. ANY OTHER USE REQUIRES A COMMERCIAL
+LICENSE. PLEASE CONTACT US FOR DETAILS AT
+_info@tozny.com_.
+
+1. DEFINITIONS
+
+1.1. "Community" means the Initial Developer and each and every
+one of You.
+
+1.2. "Contributor" means each individual or legal entity that
+creates or contributes to the creation of Modifications.
+
+1.3. "Distribute" means to transfer, publish, or otherwise provide
+or make available a copy of software to any third party.
+
+1.4. "Distributor" means each individual or legal entity
+exercising a right to Distribute Licensed Software under this
+License.
+
+1.5. "Distributor Code" means, collectively, (a) the Original
+Source Code and (b) the Licensed Software that is Distributed by a
+particular Distributor.
+
+1.6. "Distributor IP" means all patent claims, copyright, and
+trade secrets owned or licensable by a Distributor that are
+embodied in or necessarily practiced by the Distributor Code of
+that particular Distributor.
+
+1.7. "Electronic Distribution Mechanism" means a mechanism
+generally accepted in the software development community for the
+electronic transfer of data.
+
+1.8. "Executable" means software in any form other than Source
+Code.
+
+1.9. "Initial Developer" means TOZNY LLC ("TOZNY"), an Oregon
+limited liability company with offices in Portland, Oregon.
+
+1.10. "Initial Developer IP" means all patent claims, copyright,
+and trade secrets owned or licensable by the Initial Developer
+which are embodied in or necessarily practiced by the unmodified
+Original Source Code.
+
+1.11. "License" means this TOZNY NON-COMMERCIAL LICENSE.
+
+1.12. "Licensed Purpose" means the exercise of rights under this
+License: (a) by an official governmental agency, strictly for
+non-commercial, public benefit purposes; or (b) by a school,
+university, non-profit organization, or individual solely for
+non-commercial teaching or research purposes in exchange for which
+no financially valuable consideration (including but not limited
+to sales or license revenue, service revenue, and advertising
+revenue, and further including but not limited to monetary,
+equity, and in-kind forms of consideration) is received, except
+for tuition, or research funding received from an official
+government agency sponsor.
+
+1.13. "Licensed Software" means any copy of the Original Source
+Code, the Modifications, and/or Executable versions thereof, as to
+which You are exercising any rights under this License.
+
+1.14. "Modifications" means any derivative work of either the
+Original Source Code or of existing Modifications, including
+header files or calls to Licensed Software library functions or
+Executable programs in an application program shall not in and of
+itself cause that application program to be deemed a Modification,
+provided that the Licensed Software so included shall in any case
+remain subject to the terms of this License.
+
+1.15. "Original Source Code" means the Source Code for the
+_E3DB Ruby SDK_ as made available for
+download by TOZNY from [https://github.com/tozny/e3db-ruby](https://github.com/tozny/e3db-ruby).
+
+1.16. "Source Code" means the preferred form of software for
+making modifications to it, including all modules it contains,
+plus any associated interface definition files, scripts used to
+control compilation and installation of an Executable, or a list
+of source code differential comparisons against either the
+Original Source Code or another well known, available Modification
+of the Contributor's choice. The Source Code can be in a
+compressed or archival form, provided the appropriate
+decompression or de-archiving software is widely available for no
+charge.
+
+1.17. "You" means an individual or a legal entity exercising
+rights under this License. For legal entities, "You" includes any
+entity that controls, is controlled by, or is under common control
+with You. For purposes of this definition, "control" means (a) the
+power, direct or indirect, to cause the direction or management of
+such entity, whether by contract or otherwise, or (b) ownership of
+fifty percent (50%) or more of the outstanding shares or
+beneficial ownership of such entity.
+
+2. SOFTWARE LICENSE GRANTS
+
+2.1. The Initial Developer Grant. The Initial Developer hereby
+grants You a worldwide, royalty-free, non-exclusive, solely for
+the Licensed Purpose and subject to the terms and conditions of
+this License (including without limitation the Contributor and
+Distributor grants set forth in Section 2 and the Distribution
+Obligations set forth in Section 3), as follows:
+
+(a) A license under the Initial Developer IP to modify, copy, use,
+and Distribute the Original Source Code and Modifications. (b) A
+license to copy, use and Distribute Executable versions of the
+Original Source Code and Modifications.
+
+2.2. Distributor Grant. If You are a Distributor, You hereby grant
+TOZNY a worldwide, royalty-free, non-exclusive license under the
+Distributor IP, solely for the Licensed Purpose and subject to the
+terms and conditions of this License, to modify, copy, use, and
+Distribute the Distributor Code and Modifications.
+
+2.3. Sublicenses. The license rights that are granted under this
+Section 2 may be sublicensed only by Distributing Licensed
+Software in compliance with all applicable terms and conditions of
+this License. No other sublicensing of intellectual property
+rights granted under this License is permitted.
+
+2.4. No Other Rights. Except as expressly set forth in this
+section 2, no other license rights are implied or otherwise
+granted under this License.
+
+3. DISTRIBUTION OBLIGATIONS
+
+The right to Distribute Licensed Software set forth above, whether to
+a government sponsor or to any other recipient, is subject to the
+following obligations:
+
+3.1. Notice of License to Recipients. Any publication or other
+Distribution of Licensed Software must be made expressly subject
+to this License. You must include a prominent copy of the notice
+set forth in Exhibit A with all Licensed Software that you
+Distribute: (a) in all notices or documentation in which You
+describe the origin or ownership of the software or the
+recipient's rights thereto, and (b) in each Source Code file. You
+hereby agree to indemnify the Initial Developer and every
+Contributor to the Licensed Software for any and all liability or
+damages they may incur if caused by Your violation of this
+Section. Except as expressly authorized by this License, no right
+is granted to use the name of Tozny in any advertising, news
+release, other publication, or product documentation, without the
+prior express written consent of Tozny.
+
+3.2. Required Availability of Source Code. If You Distribute
+Licensed Software for which you are a Contributor, You must make
+the Source Code for all Modifications to which you contribute
+publicly available to TOZNY or the Community, under the terms of
+this License and at no additional restriction or cost, via an
+accepted Electronic Distribution Mechanism for a period of at
+least twelve (12) months following the date You first Distribute
+the Licensed Software. You must also include with the Source Code
+a file documenting any changes You made to create each
+Modification, and the dates of such changes.
+
+3.3. Licensee Registration. Before You Distribute any Licensed
+Software under this License, You must first register by sending
+email to the Initial Developer addressed to _info@tozny.com_,
+including a statement confirming that you accept the terms and
+conditions of this License and describing the specific Electronic
+Distribution Mechanism you are using (e.g., identify the URL) to
+make Source Code available under Section 3.2 where applicable.
+
+4. DISCLAIMER OF WARRANTY
+
+LICENSED SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES
+THAT THE LICENSED SOFTWARE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A
+PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE
+QUALITY AND PERFORMANCE OF THE LICENSED SOFTWARE IS WITH YOU. SHOULD
+ANY LICENSED SOFTWARE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE
+INITIAL DEVELOPER OR ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY
+SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY
+CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY LICENSED
+SOFTWARE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
+
+5. LIMITATION OF LIABILITY
+
+UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT
+(INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE INITIAL
+DEVELOPER, ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF LICENSED SOFTWARE,
+OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO YOU OR ANY OTHER
+PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
+OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF
+GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND
+ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF
+LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY
+RESULTING FROM SUCH PARTY'S NEGLIGENCE TO THE EXTENT APPLICABLE LAW
+PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE
+EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO
+THAT EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
+
+6. RESPONSIBILITY FOR CLAIMS.
+
+You are responsible for damages arising, directly or indirectly, out
+of Your exercise of rights under this License, based on the number of
+copies of Licensed Software you made available, the revenues you
+received from utilizing such rights, and other relevant factors. You
+agree to work with affected parties to distribute responsibility on an
+equitable basis.
+
+7. U.S. GOVERNMENT END USERS.
+
+The Licensed Software is a "commercial item," as that term is defined
+in 48 C.F.R. 2.101 (Oct. 1995), consisting of "commercial computer
+software" and "commercial computer software documentation," as such
+terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48
+C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995),
+all U.S. Government End Users acquire Licensed Software with only
+those rights set forth herein.
+
+8. MISCELLANEOUS.
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. This License shall be governed by
+Oregon law provisions (except to the extent applicable law, if any,
+provides otherwise), excluding its conflict-of-law provisions. With
+respect to disputes in which at least one party is a citizen of, or an
+entity chartered or registered to do business in, the United States of
+America any litigation relating to this Agreement shall be subject to
+personal jurisdiction and venue in the Federal Courts of the District
+of Oregon, and in the Oregon state courts of Portland, OR, with the
+losing party responsible for costs, including without limitation,
+court costs and reasonable attorneys fees and expenses. The
+application of the United Nations Convention on Contracts for the
+International Sale of Goods is expressly excluded. Any law or
+regulation which provides that the language of a contract shall be
+construed against the drafter shall not apply to this License.
+
+EXHIBIT A
+
+Tozny dual licenses this product. For commercial use, please contact
+info@tozny.com. For non-commercial use, the contents of this file are
+subject to the TOZNY NON-COMMERCIAL LICENSE (the "License") which
+permits use of the software only by government agencies, schools,
+universities, non-profit organizations or individuals on projects that
+do not receive external funding other than government research grants
+and contracts.  Any other use requires a commercial license. You may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at https://tozny.com/legal/non-commercial-license.
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
+License for the specific language governing rights and limitations under
+the License. Portions of the software are Copyright (c) TOZNY LLC, 2017.
+All rights reserved.

data/README.md

@@ -37,21 +37,40 @@ $ apt-get install libsodium-dev     (Ubuntu)
 For more information including libsodium installation instructions
 for Windows, see the [libsodium web site](https://download.libsodium.org/doc/installation/).
 
-_Windows Users:_ Make sure to download a recent "MSVC" build. Once downloaded, find the most recent `libsodium.dll` inside the ZIP file and copy it to somewhere in your `PATH`.
+_Windows Users:_ Make sure to download a recent "MSVC" build. Once
+downloaded, find the most recent `libsodium.dll` inside the ZIP file,
+rename it to `sodium.dll` and copy it to C:\usr\local\lib. You can
+also copy it to your \Windows\System32 directory.
 
 ## Registering a client
 
-1. Download and install the E3DB Command-Line interface (CLI) from our
-   [GitHub releases page](https://github.com/tozny/e3db-go/releases).
+Register an account with [InnoVault](https://innovault.io) to get started. From the Admin Console you can create clients directly (and grab their credentials from the console) or create registration tokens to dynamically create clients with `E3DB::Client.register()`. Clients registered from within the console will automatically back their credentials up to your account. Clients created dynamically via the SDK can _optionally_ back their credentials up to your account.
 
-2. Register an account using the CLI:
+For a more complete walkthrough, see [`/examples/registration.rb`](https://github.com/tozny/e3db-ruby/blob/master/examples/registration.rb).
 
-   ```shell
-   $ e3db register me@mycompany.com
-   ```
+### Without Credential Backup
 
-   This will create a new default configuration with a randomly
-   generated key pair and API credentials, saving it in `$HOME/.tozny/e3db.json`.
+```ruby
+token = '...'
+client_name = '...'
+
+public_key, private_key = E3DB::Client.generate_keypair
+client_info = E3DB::Client.register(token, client_name, public_key)
+```
+
+The object returned from the server contains the client's UUID, API key, and API secret (as well as echos back the public key passed during registration). It's your responsibility to store this information locally as it _will not be recoverable_ without credential backup.
+
+### With Credential Backup
+
+```ruby
+token = '...'
+client_name = '...'
+
+public_key, private_key = E3DB::Client.generate_keypair
+client_info = E3DB::Client.register(token, client_name, public_key, private_key, true)
+```
+
+The private key must be passed to the registration handler when backing up credentials as it is used to cryptographically sign the encrypted backup file stored on the server. The private key never leaves the system, and the stored credentials will only be accessible to the newly-registered client itself or the account with which it is registered.
 
 ## Loading configuration and creating a client
 
@@ -139,22 +158,24 @@ See the [simple example code](examples/simple.rb) for runnable detailed examples
 
 ## Development
 
-Before running tests, register an `integration-test` profile using
-the E3DB command-line tool:
+Before running tests, register an account with
+[InnoVault](https://innovault.io), and generate a client token.
 
-```shell
-$ e3db -p integration-test register me+test@mycompany.com
-```
+After checking out the repo, run `bin/setup` to install dependencies. Next,
+set two environment variables:
+
+* API_URL - E3DB host to run tests against.
+* REGISTRATION_TOKEN - A token obtained from InnoVault that can be used
+  to register E3DB clients.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then,
-run `rake spec` to run the tests. You can also run `bin/console` for an
-interactive prompt that will allow you to experiment.
+Run `rake spec` 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`. 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).
 
 ## Documentation
 
@@ -168,7 +189,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/tozny/
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Tozny dual licenses this product. For commercial use, please contact [info@tozny.com](mailto:info@tozny.com). For non-commercial use, the contents of this file are subject to the TOZNY NON-COMMERCIAL LICENSE (the "License") which permits use of the software only by government agencies, schools, universities, non-profit organizations or individuals on projects that do not receive external funding other than government research grants and contracts.  Any other use requires a commercial license. You may not use this file except in compliance with the License. You may obtain a copy of the License at https://tozny.com/legal/non-commercial-license. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. Portions of the software are Copyright (c) TOZNY LLC, 2017. All rights reserved.
 
 [gem-image]: https://badge.fury.io/rb/e3db.svg
 [gem-url]: https://rubygems.org/gems/e3db

data/examples/registration.rb

@@ -0,0 +1,79 @@
+# This program provides a simple example illustrating how to programmatically
+# register a client with InnoVault and e3db. In some situations, it's preferable
+# to register a client from the server or system that will be using its
+# credentials (to ensure that all data is truly encrypted from end-to-end
+# with no possibilities of a credential leak). For more detailed information,
+# please see the documentation home page: https://tozny.com/documentation/e3db
+#
+# Author::    Eric Mann (eric@tozny.com)
+# Copyright:: Copyright (c) 2017 Tozny, LLC
+# License::   Public Domain
+
+# ---------------------------------------------------------
+# Initialization
+# ---------------------------------------------------------
+
+require 'e3db'
+
+# A registration token is required to set up a client. In this situation,
+# we assume an environment variable called REGISTRATION_TOKEN is set
+token = ENV["REGISTRATION_TOKEN"]
+
+# Clients can either create new cryptographic keypairs, or load in a pre-defined
+# pair of Curve25519 keys. In this situation, we will generate a new keypair.
+public_key, private_key = E3DB::Client.generate_keypair
+
+puts("Public Key:  " + public_key)
+puts("Private Key: " + private_key)
+
+# Clients must be registered with a name unique to your account to help
+# differentiate between different sets of credentials in the Admin Console.
+# In this example, the name is set at random
+client_name = sprintf("client_%s", SecureRandom.hex)
+
+puts("Client Name: " + client_name)
+
+# Passing all of the data above into the registration routine will create
+# a new client with the system. Remember to keep your private key private!
+client_info = E3DB::Client.register(token, client_name, public_key)
+
+# Optionally, you can automatically back up the credentials of the newly-created
+# client to your InnoVault account (accessible via https://console.tozny.com) by
+# passing your private key and a backup flag when registering. The private key is
+# not sent anywhere, but is used by the newly-created client to sign an encrypted
+# copy of its credentials that is itself stored in e3db for later use.
+#
+# Client credentials are not backed up by default.
+
+# client_info = E3DB::Client.register(token, client_name, wrapped_key, private_key, true)
+
+puts("Client ID:   " + client_info.client_id)
+puts("API Key ID:  " + client_info.api_key_id)
+puts("API Secret:  " + client_info.api_secret)
+
+# ---------------------------------------------------------
+# Usage
+# ---------------------------------------------------------
+
+# Once the client is registered, you can use it immediately to create the
+# configuration used to instantiate a Client that can communicate with
+# e3db directly.
+
+config = E3DB::Config.new(
+  :version      => 1,
+  :client_id    => client_info.client_id,
+  :api_key_id   => client_info.api_key_id,
+  :api_secret   => client_info.api_secret,
+  :client_email => '',
+  :public_key   => public_key,
+  :private_key  => private_key,
+  :api_url      => 'https://api.e3db.com',
+  :logging      => false
+)
+
+# Now create a client using that configuration.
+client = E3DB::Client.new(config)
+
+# From this point on, the new client can be used as any other client to read
+# write, delete, and query for records. See the `simple.rb` documentation
+# for more complete examples ...