session_keys 0.1.0

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.2.4
+  - 2.3.1
+  - jruby-9.0.5.0
+before_install: gem install bundler -v 1.12.1

data/.yardopts

@@ -0,0 +1 @@
+--no-private  lib/**/*.rb - README.md LICENSE.txt CODE_OF_CONDUCT.md

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at glenn@rempe.us. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in session_keys.gemspec
+gemspec
+
+# FIXME : remove when @bascule publishes new rbnacl release
+# including commit : dc1e8d10b8fc4784130b0864d45b9275a9e979dc
+# https://github.com/cryptosphere/rbnacl/pull/135
+gem 'rbnacl', git: 'https://github.com/cryptosphere/rbnacl.git'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Glenn Rempe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# SessionKeys
+
+[![Gem Version](https://badge.fury.io/rb/session-keys-rb.svg)](https://badge.fury.io/rb/session-keys-rb)
+[![Dependency Status](https://gemnasium.com/badges/github.com/grempe/session-keys-rb.svg)](https://gemnasium.com/github.com/grempe/session-keys-rb)
+[![Build Status](https://travis-ci.org/grempe/session-keys-rb.svg?branch=master)](https://travis-ci.org/grempe/session-keys-rb)
+[![Coverage Status](https://coveralls.io/repos/github/grempe/session-keys-rb/badge.svg?branch=master)](https://coveralls.io/github/grempe/session-keys-rb?branch=master)
+[![Code Climate](https://codeclimate.com/github/grempe/session-keys-rb/badges/gpa.svg)](https://codeclimate.com/github/grempe/session-keys-rb)
+[![Inline docs](http://inch-ci.org/github/grempe/session-keys-rb.svg?branch=master)](http://inch-ci.org/github/grempe/session-keys-rb)
+
+SessionKeys is a cryptographic tool for the deterministic generation of
+NaCl compatible [Curve25519](https://cr.yp.to/ecdh.html) encryption and
+[Ed25519](http://ed25519.cr.yp.to) digital signature keys.
+
+The strength of the system lies in the fact that the keypairs are derived from
+passing an identifier, such as a username or email address, and a high-entropy
+passphrase through the `SHA256` hash and the `scrypt` key derivation
+functions. This means that no private key material need ever be stored to disk.
+The generated keys are deterministic; for any given ID, password, and
+strength combination the same keys will always be returned.
+
+The generated ID is passed through `SHA256` and `scrypt` and is derived from
+only the ID parameter your provide and a common salt.
+
+The password is also passed through `SHA256` and `scrypt` and NaCl encryption
+and signing keypairs are derived from the combination of the stretched ID,
+your password, and a common salt.
+
+## WARNING : BETA CODE
+
+This code is new and has not yet been tested in production. Use at your own risk.
+The interface should be fairly stable now but should not be considered fully
+stable until v1.0.0 is released.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem 'session_keys'
+```
+
+And then execute:
+
+``` text
+$ bundle
+```
+
+Or install it yourself as:
+
+``` text
+$ gem install session_keys
+```
+
+### Installation Security : Signed Ruby Gem
+
+The SessionKeys gem is cryptographically signed. To be sure the gem you install hasn’t
+been tampered with you can install it using the following method:
+
+Add required public keys (if you haven’t already) as trusted certificates
+
+``` text
+# Caveat: Gem certificates are trusted globally, such that adding a
+# cert.pem for one gem automatically trusts all gems signed by that cert.
+gem cert --add <(curl -Ls https://raw.githubusercontent.com/cryptosphere/rbnacl/master/bascule.cert)
+gem cert --add <(curl -Ls https://raw.github.com/grempe/session-keys-rb/master/certs/gem-public_cert_grempe.pem)
+```
+
+To install, it is possible to specify either `HighSecurity` or `MediumSecurity`
+mode. Since the `session_keys` gem depends on one or more gems that are not cryptographically
+signed you will likely need to use `MediumSecurity`. You should receive a warning
+if any signed gem does not match its signature.
+
+``` text
+# All dependent gems must be signed and verified.
+gem install session_keys -P HighSecurity
+```
+
+``` text
+# All signed dependent gems must be verified.
+gem install session_keys -P MediumSecurity
+```
+
+``` text
+# Same as above, except Bundler only recognizes
+# the long --trust-policy flag, not the short -P
+bundle --trust-policy MediumSecurity
+```
+
+You can [learn more about security and signed Ruby Gems](http://guides.rubygems.org/security/).
+
+### Installation Security : Signed Git Commits
+
+Most, if not all, of the commits and tags to the repository for this code are
+signed with my PGP/GPG code signing key. I have uploaded my code signing public
+keys to GitHub and you can now verify those signatures with the GitHub UI.
+See [this list of commits](https://github.com/grempe/session-keys-rb/commits/master)
+and look for the `Verified` tag next to each commit. You can click on that tag
+for additional information.
+
+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/).
+
+## Usage
+
+``` ruby
+keys = SessionKeys.generate('user@example.com', 'my strong passphrase')
+#=> {...}
+```
+
+## Development
+
+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`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+[https://github.com/grempe/session-keys-rb](https://github.com/grempe/session-keys-rb).
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Legal
+
+### Copyright
+
+(c) 2016 Glenn Rempe <[glenn@rempe.us](mailto:glenn@rempe.us)> ([https://www.rempe.us/](https://www.rempe.us/))
+
+### License
+
+The gem is available as open source under the terms of
+the [MIT License](http://opensource.org/licenses/MIT).
+
+### Warranty
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See the LICENSE.txt file for the
+specific language governing permissions and limitations under
+the License.

data/Rakefile

@@ -0,0 +1,13 @@
+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
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'session_keys'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require 'pry'
+Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/certs/gem-public_cert_grempe.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDYDCCAkigAwIBAgIBATANBgkqhkiG9w0BAQUFADA7MQ4wDAYDVQQDDAVnbGVu
+bjEVMBMGCgmSJomT8ixkARkWBXJlbXBlMRIwEAYKCZImiZPyLGQBGRYCdXMwHhcN
+MTYwNDExMDI0NTU0WhcNMTcwNDExMDI0NTU0WjA7MQ4wDAYDVQQDDAVnbGVubjEV
+MBMGCgmSJomT8ixkARkWBXJlbXBlMRIwEAYKCZImiZPyLGQBGRYCdXMwggEiMA0G
+CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZqTH5Jf+D/W2B4BIiL49CpHa86rK/
+oT+v3xZwuEE92lJea+ygn3IAsidVTW47AKE6Lt3UqUkGQGKxsqH/Dhir08BqjLlD
+gBUozGZpM3B6uWZnD6QXLbOmZeGVDnwB/QDfzaawN1i3smlYxYT+KNLjl80aN3we
+/cHAWG7JG47AF/S91mYcg1WgZnDgZt9+RyVR1AsfYbM+SidOSoXEOHPCbuUxLKJb
+gj5ieCFhm5GNWEugvgiX/ruas+VHV0fF3fzjYlU2fZPTuQyB4UD5FWX4UqdsBf3w
+jB94TDBsJ3FVGPbggEhLGKd8pbQmBIOqXolGaqhs7dnuf5imu5mAXHC1AgMBAAGj
+bzBtMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBRfxEyosUbKjfFa
+j+gae2CcT3aFCTAZBgNVHREEEjAQgQ5nbGVubkByZW1wZS51czAZBgNVHRIEEjAQ
+gQ5nbGVubkByZW1wZS51czANBgkqhkiG9w0BAQUFAAOCAQEAzgK20+MNOknR9Kx6
+RisI3DsioCADjGldxY+INrwoTfPDVmNm4GdTYC+V+/BvxJw1RqHjEbuXSg0iibQC
+4vN+th0Km7dnas/td1i+EKfGencfyQyecIaG9l3kbCkCWnldRtZ+BS5EfP2ML2u8
+fyCtze/Piovu8IwXL1W5kGZMnvzLmWxdqI3VPUou40n8F+EiMMLgd53kpzjtNOau
+4W+mqVGOwlEGVSgI5+0SIsD8pvc62PlPWTv0kn1bcufKKCZmoVmpfbe3j4JpBInq
+zieXiXZSAojfFx9g91fKdIrlPbInHU/BaCxXSLBwvOM0drE+c2ue9X8gB55XAhzX
+37oBiw==
+-----END CERTIFICATE-----

data/lib/session_keys.rb

@@ -0,0 +1,188 @@
+require 'session_keys/version'
+require 'rbnacl/libsodium'
+require 'rbnacl'
+require 'zxcvbn'
+require 'base64'
+
+# SessionKeys deterministic cryptographic key generation.
+module SessionKeys
+  # Opslimit represents a maximum amount of computations to perform.
+  # Raising this number will make the function require more CPU cycles to
+  # compute a key.
+  #
+  # Number of scrypt computations for scrypt to perform for interactive security setting.
+  # Set to SCRYPT_MEMLIMIT_INTERACTIVE / 32
+  #
+  # For interactive, online operations, `SCRYPT_OPSLIMIT_INTERACTIVE` and
+  # `SCRYPT_MEMLIMIT_INTERACTIVE` provide a safe base line for these two parameters.
+  # However, using higher values may improve security.
+  #
+  # See : https://download.libsodium.org/doc/password_hashing/scrypt.html
+  SCRYPT_OPSLIMIT_INTERACTIVE = 2**19
+
+  # Memlimit is the maximum amount of RAM that the function will use, in
+  # bytes. It is highly recommended to allow the function to use at least 16
+  # megabytes.
+  #
+  # Max RAM in Bytes to be used by scrypt for interactive security setting.
+  SCRYPT_MEMLIMIT_INTERACTIVE = 2**24
+
+  # Number of scrypt computations for scrypt to perform for sensitive security setting.
+  # Set to SCRYPT_MEMLIMIT_SENSITIVE / 32
+  #
+  # For highly sensitive data, `SCRYPT_OPSLIMIT_SENSITIVE` and `SCRYPT_MEMLIMIT_SENSITIVE` can
+  # be used as an alternative. But with these parameters, deriving a key takes
+  # about 2 seconds on a 2.8 Ghz Core i7 CPU and requires up to 1 gigabyte of
+  # dedicated RAM.
+  SCRYPT_OPSLIMIT_SENSITIVE = 2**25
+
+  # Max RAM in Bytes to be used by scrypt for sensitive security setting.
+  SCRYPT_MEMLIMIT_SENSITIVE = 2**30
+
+  # Size in Bytes of the scrypt derived output for the id
+  SCRYPT_DIGEST_SIZE_ID = 32
+
+  # Size in Bytes of the scrypt derived output for the password
+  SCRYPT_DIGEST_SIZE_PASSWORD = 256
+
+  # A site-wide 32 Byte common random value that will be concatenated with a value
+  # being hashed for some additional measure of security against dictionary
+  # style attacks. This value was randomly chosen but must be the same across
+  # implementations and is assumed public.
+  PEPPER = 'f01f0a0c44a2d1e7e5b00d7dc78941d404474a90ce7f4ae9d1432bf76fa169e7'.freeze
+
+  # Deterministically generates a collection of derived encryption key material from
+  # a provided id and password. Uses SHA256 and scrypt for key derivation.
+  #
+  # @param id [String] a unique UTF-8 String identifier such as a username or
+  #   email address. Max length 256 characters.
+  # @param password [String] a cryptographically strong UTF-8 password or
+  #   passphrase. Max length 256 characters.
+  # @param strength [Symbol] the desired strength of the key derivation. Can be
+  #   the symbols :interactive or (:sensitive).
+  # @param min_password_entropy [Integer] the minimum (75) estimated entropy allowed
+  #   for the password. This will be measured with Zxcvbn.
+  # @return [Hash] returns a Hash of keys and derived key material.
+  # @raise [ArgumentError] if invalid arguments are provided.
+  def self.generate(id, password, strength = :sensitive, min_password_entropy = 75)
+    unless id.is_a?(String) && id.encoding.name == 'UTF-8'
+      raise ArgumentError, 'invalid id, not a UTF-8 string'
+    end
+
+    unless id.length.between?(1,256)
+      raise ArgumentError, 'invalid id, must be between 1 and 256 characters in length'
+    end
+
+    unless password.is_a?(String) && password.encoding.name == 'UTF-8'
+      raise ArgumentError, 'invalid password, not a UTF-8 string'
+    end
+
+    # Enforce max length only due to Zxcvbn taking a *long* time to
+    # process long strings and determine entropy.
+    unless password.length.between?(1,256)
+      raise ArgumentError, 'invalid password, must be between 1 and 256 characters in length'
+    end
+
+    unless min_password_entropy.is_a?(Integer) && min_password_entropy.between?(1, 512)
+      raise ArgumentError, 'invalid min_password_entropy, must be an Integer between 1 and 512'
+    end
+
+    password_test = Zxcvbn.test(password)
+    unless password_test.entropy.round >= min_password_entropy
+      raise ArgumentError, "invalid password, must be at least #{min_password_entropy} bits of estimated entropy"
+    end
+
+    unless [:interactive, :sensitive].include?(strength)
+      raise ArgumentError, 'invalid strength, must be :interactive (min), or :sensitive (strong)'
+    end
+
+    start_processing_time = Time.now
+
+    # Run the ID and a 'pepper' (an app common salt) through scrypt. This will be
+    # the system ID for this user. This processing is done to prevent knowledge
+    # of the user on the server side and prevent the ability to reverse this
+    # ID back into a username or email. Using scrypt instead of a SHA256 Hash
+    # is so that it will also take unreasonable effort for someone with a list
+    # of user identifiers from looking up users on the system quickly even if
+    # provided with a local copy of the DB.
+    id_sha256_bytes = RbNaCl::Hash.sha256(id.bytes.pack('C*'))
+
+    id_sha256_pepper_bytes = RbNaCl::Hash.sha256(
+      "#{id}#{id.length}#{PEPPER}#{PEPPER.length}".bytes.pack('C*')
+    )
+
+    id_scrypt_hex = RbNaCl::PasswordHash.scrypt(
+      id_sha256_bytes,
+      id_sha256_pepper_bytes,
+      SCRYPT_OPSLIMIT_INTERACTIVE,
+      SCRYPT_MEMLIMIT_INTERACTIVE,
+      SCRYPT_DIGEST_SIZE_ID
+    ).bytes.map { |byte| '%02x' % byte }.join
+
+    # libsodium : By design, a password whose length is 65 bytes or more is
+    # reduced to SHA-256(password). This can have security implications if the
+    # password is present in another password database using raw, unsalted
+    # SHA-256. Or when upgrading passwords previously hashed with unsalted
+    # SHA-256 to scrypt. If this is a concern, passwords should be pre-hashed
+    # before being hashed using scrypt.
+    password_sha256_bytes = RbNaCl::Hash.sha256(password.bytes.pack('C*'))
+
+    password_sha256_pepper_bytes = RbNaCl::Hash.sha256(
+      "#{id_scrypt_hex}#{id_scrypt_hex.length}#{PEPPER}#{PEPPER.length}".bytes.pack('C*')
+    )
+
+    # Derive SCRYPT_DIGEST_SIZE_PASSWORD secret bytes. They will be split
+    # into 32 Byte chunks to serve as deterministic seeds for ID or key
+    # generation. Some derived bytes are reserved for future use.
+    password_digest = RbNaCl::PasswordHash.scrypt(
+      password_sha256_bytes,
+      password_sha256_pepper_bytes,
+      strength == :interactive ? SCRYPT_OPSLIMIT_INTERACTIVE : SCRYPT_OPSLIMIT_SENSITIVE,
+      strength == :interactive ? SCRYPT_MEMLIMIT_INTERACTIVE : SCRYPT_MEMLIMIT_SENSITIVE,
+      SCRYPT_DIGEST_SIZE_PASSWORD
+    ).bytes
+
+    # Break up the scrypt digest into 32 Byte seeds.
+    secret_bytes = []
+    (SCRYPT_DIGEST_SIZE_PASSWORD/32).times { secret_bytes << password_digest.shift(32) }
+
+    # Seed 0 : RbNaCl::SimpleBox
+    # The seed bytes are used as a 32 Byte key suitable for
+    # simple symetric key encryption using `RbNaCl::SimpleBox`. SimpleBox is
+    # a wrapper around NaCl SecretBox construct with automated nonce management.
+    #
+    # To encrypt/decreypt with this object try:
+    #  ciphertext = nacl_simple_box.encrypt('foobar')
+    #  plaintext = nacl_simple_box.decrypt(ciphertext)
+    nacl_simple_box_key = secret_bytes[0].pack('C*').force_encoding('ASCII-8BIT')
+    nacl_simple_box = RbNaCl::SimpleBox.from_secret_key(nacl_simple_box_key)
+
+    # Seed 1 : NaCl Box Keypair
+    nacl_enc_sec_seed = secret_bytes[1].pack('C*').force_encoding('ASCII-8BIT')
+    nacl_enc_sec_key = RbNaCl::PrivateKey.new(nacl_enc_sec_seed)
+    nacl_enc_pub_key = nacl_enc_sec_key.public_key
+
+    # Seed 2 : NaCl Signing Keypair
+    nacl_sig_sec_seed = secret_bytes[2].pack('C*').force_encoding('ASCII-8BIT')
+    nacl_sig_sec_key = RbNaCl::SigningKey.new(nacl_sig_sec_seed)
+    nacl_sig_pub_key = nacl_sig_sec_key.verify_key
+
+    # Seed 3 : Reserved for future use.
+    # Seed 4 : Reserved for future use.
+    # Seed 5 : Reserved for future use.
+    # Seed 6 : Reserved for future use.
+    # Seed 7 : Reserved for future use.
+
+    {
+      id: id_scrypt_hex,
+      nacl_simple_box: nacl_simple_box,
+      nacl_enc_pub_key: nacl_enc_pub_key,
+      nacl_enc_sec_key: nacl_enc_sec_key,
+      nacl_sig_pub_key: nacl_sig_pub_key,
+      nacl_sig_sec_key: nacl_sig_sec_key,
+      nacl_enc_pub_key_b64: Base64.strict_encode64(nacl_enc_pub_key.to_bytes),
+      nacl_sig_pub_key_b64: Base64.strict_encode64(nacl_sig_pub_key.to_bytes),
+      process_time: ((Time.now - start_processing_time)*1000).round(2)
+    }
+  end
+end