xstream 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 32fee938822c8a5a7cd5ebd651b2b16f42081dbe
-  data.tar.gz: 983432526edf0a8880096b26f7f81df759552aa9
+SHA256:
+  metadata.gz: 869cb2a3a6326ac15f6711049d9e8a47cb801d5d5cba5850274558e34fc7ddef
+  data.tar.gz: 7d21c47213ec45151b556eea0ddbddf4b0fefcd2093464d6fbff42abadb40543
 SHA512:
-  metadata.gz: de13fd1f52f3545c8f8def6ac917ff59a330d290c11102aeddee2f82654993815f5786399692199975be279c27a53b0be791e8499d47bc3a3993483c8f0e1a9a
-  data.tar.gz: 59efd6a0f5b2ce2ffad2f2be16e41ec3f0d9067e9e5a5f997f0994c428c23992ac13ea2054c6064744c7df02a12e4b72a5a4327a8080aa3a0c038145a1abe64f
+  metadata.gz: c1f0e99de71f5d377ebaa83dba2f466407dc880e429c4573639ab5af62841d89060a900342f4fdd3fb9c1be67147fb29d96b11e39c71708878dfa2ef8a9976a2
+  data.tar.gz: cc2a84038f14803c81671838cf86710912f7e02821ad2a01d900a7e61e059bc204c6eeca179ce5fc87f4ee00c2cf16943a650f0c09a4105283eedf80f9f342db

data/.gitignore

@@ -10,3 +10,4 @@
 
 # rspec failure tracking
 .rspec_status
+.rakeTasks

data/.rspec

@@ -1,4 +1,5 @@
 --color
---format=documentation
+--format documentation
 --order random
+--warnings
 --require spec_helper

data/.rubocop.yml

@@ -1,13 +1,7 @@
 AllCops:
+  TargetRubyVersion: 2.2
   DisplayCopNames: true
 
-#
-# Style
-#
-
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
 #
 # Metrics
 #
@@ -15,6 +9,9 @@ Style/StringLiterals:
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/BlockLength:
+  Max: 100
+
 Metrics/CyclomaticComplexity:
   Enabled: false
 
@@ -29,3 +26,13 @@ Metrics/LineLength:
 
 Metrics/MethodLength:
   Max: 25
+
+#
+# Style
+#
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/Gemfile

@@ -5,7 +5,8 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "rake"
-  gem "rspec", "~> 3.7"
-  gem "rubocop", "0.51.0"
+  gem "rake",              require: false
+  gem "rspec",   "~> 3.7", require: false
+  gem "rubocop", "0.52.0", require: false
+  gem "tjson",   "~> 0.5", require: false
 end

data/README.md

@@ -1,6 +1,61 @@
-# xstream.rb
+# xstream.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-link] [![Yard Docs][docs-image]][docs-link] [![MIT licensed][license-image]][license-link] [![Gitter Chat][gitter-image]][gitter-link]
 
-Public key encryption system combining X25519 Diffie-Hellman with the STREAM construction
+[gem-shield]: https://badge.fury.io/rb/xstream.svg
+[gem-link]: https://rubygems.org/gems/xstream
+[build-image]: https://secure.travis-ci.org/miscreant/xstream.svg?branch=master
+[build-link]: http://travis-ci.org/miscreant/xstream
+[docs-image]: https://img.shields.io/badge/yard-docs-blue.svg
+[docs-link]: http://www.rubydoc.info/gems/xstream/0.0.0
+[license-image]: https://img.shields.io/badge/license-MIT/Apache2.0-blue.svg
+[license-link]: https://github.com/miscreant/xstream#license
+[gitter-image]: https://badges.gitter.im/badge.svg
+[gitter-link]: https://gitter.im/miscreant/Lobby
+
+**XSTREAM** (pronounced *"extreme!"*) is a public key encryption system combining
+X25519 Elliptic Curve Diffie-Hellman ([RFC 7748]) with the [STREAM] construction.
+
+The implementations in this repository are built on top of the
+[Miscreant] misuse-resistant symmetric encryption library, which provides
+the [AES-SIV] and [AES-PMAC-SIV] algorithms.
+
+[More information on XSTREAM](https://github.com/miscreant/xstream/wiki/XSTREAM)
+is available in the Wiki.
+
+[RFC 7748]: https://tools.ietf.org/html/rfc7748
+[STREAM]: https://github.com/miscreant/miscreant/wiki/STREAM
+[Miscreant]: https://github.com/miscreant/miscreant
+[AES-SIV]: https://github.com/miscreant/miscreant/wiki/AES-SIV
+[AES-PMAC-SIV]: https://github.com/miscreant/miscreant/wiki/AES-PMAC-SIV
+
+## Help and Discussion
+
+Have questions? Want to suggest a feature or change?
+
+* [Gitter]: web-based chat about miscreant projects including **miscreant.rb**
+* [Google Group]: join via web or email ([miscreant-crypto+subscribe@googlegroups.com])
+
+[Gitter]: https://gitter.im/miscreant/Lobby
+[Google Group]: https://groups.google.com/forum/#!forum/miscreant-crypto
+[miscreant-crypto+subscribe@googlegroups.com]: mailto:miscreant-crypto+subscribe@googlegroups.com?subject=subscribe
+
+## Security Notice
+
+Though this library is written by cryptographic professionals, it has not
+undergone a thorough security audit, and cryptographic professionals are still
+humans that make mistakes.
+
+Use this library at your own risk.
+
+## Requirements
+
+This library is tested against the following MRI versions:
+
+- 2.2
+- 2.3
+- 2.4
+- 2.5
+
+Other Ruby versions may work, but are not officially supported.
 
 ## Installation
 
@@ -18,11 +73,35 @@ Or install it yourself as:
 
     $ gem install xstream
 
-## Usage
+## Documentation
+
+[Please see the XSTREAM Wiki](https://github.com/miscreant/xstream/wiki/Ruby-Documentation)
+for API documentation.
+
+[Yard documentation][docs-link] is also available.
+
+## Code of Conduct
+
+We abide by the [Contributor Covenant][cc] and ask that you do as well.
 
-TODO: Write usage instructions here
+For more information, please see [CODE_OF_CONDUCT.md].
+
+[cc]: https://contributor-covenant.org
+[CODE_OF_CONDUCT.md]: https://github.com/miscreant/xstream/blob/master/CODE_OF_CONDUCT.md
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/miscreant/xstream.
 
+## License
+
+Copyright (c) 2017 [The Miscreant Developers][AUTHORS].
+
+All XSTREAM libraries are licensed under either of:
+
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+[AUTHORS]: https://github.com/miscreant/miscreant/blob/master/AUTHORS.md

data/ci.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+set -e
+
+bundle
+bundle exec rake

data/lib/xstream.rb

@@ -1,5 +1,21 @@
+# encoding: binary
+# frozen_string_literal: true
+
 require "xstream/version"
 
+require "securerandom"
+
+require "hkdf"
+require "miscreant"
+require "x25519"
+
+require "xstream/x25519hkdf"
+
 # Public key encryption system combining X25519 Diffie-Hellman with the STREAM construction
 module XStream
+  # STREAM nonce of all zeroes (since we always derive a unique key per STREAM)
+  NONCE = "\0\0\0\0\0\0\0\0".freeze
+
+  # Default XSTREAM encryptor type
+  Encryptor = X25519HKDF::Encryptor
 end

data/lib/xstream/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module XStream
-  VERSION = "0.0.0".freeze
+  VERSION = "0.1.0".freeze
 end

data/lib/xstream/x25519hkdf.rb

@@ -0,0 +1,94 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module XStream
+  # XSTREAM with X25519 key agreement and HKDF as the key derivation function
+  module X25519HKDF
+    # Domain separation string passed as HKDF info
+    HKDF_INFO = "XSTREAM_X25519_HKDF".freeze
+
+    # Size of an AES-128 key * 2 (for SIV mode)
+    SYMMETRIC_KEY_SIZE = 32
+
+    # XSTREAM encryptor with X25519+HKDF key derivation
+    class Encryptor < ::Miscreant::STREAM::Encryptor
+      # Generate an XSTREAM encryptor object with a random ephemeral key
+      #
+      # @param public_key [String] 32-byte X25519 public key (i.e. compressed Montgomery-u coordinate)
+      # @param encryption_alg [String] symmetric encryption algorithm to use with STREAM (default `"AES-PMAC-SIV"`)
+      # @param digest_alg [String] digest algorithm to use with HKDF (default `"SHA256"`)
+      # @param salt [String] (optional) salt value to pass to HKDF
+      # @param csrng [#random_bytes] secure RNG to use to derive ephemeral X25519 key (default `SecureRandom`)
+      #
+      # @return [Array(XStream::X25519HKDF, String)] STREAM encryptor and ephemeral public key
+      def self.generate(
+        public_key,
+        encryption_alg: "AES-PMAC-SIV",
+        digest_alg: "SHA-256",
+        salt: nil,
+        csrng: SecureRandom
+      )
+        ephemeral_scalar = csrng.random_bytes(::X25519::KEY_SIZE)
+        ephemeral_public = ::X25519.calculate_public_key(ephemeral_scalar)
+
+        symmetric_key = X25519HKDF.kdf(
+          ephemeral_scalar,
+          public_key,
+          salt: salt,
+          digest_alg: digest_alg,
+          output_size: SYMMETRIC_KEY_SIZE
+        )
+
+        stream = new(encryption_alg, symmetric_key, XStream::NONCE)
+        [stream, ephemeral_public]
+      end
+    end
+
+    # XSTREAM decryptor class with X25519+HKDF key derivation
+    class Decryptor < ::Miscreant::STREAM::Decryptor
+      # Create an XSTREAM decryptor object using our private key and an ephemeral public key
+      #
+      # @param private_key [String] 32-byte X25519 private key (i.e. private scalar)
+      # @param ephemeral_public [String] 32-byte X25519 ephemeral public key from XSTREAM encryption
+      # @param encryption_alg [String] symmetric encryption algorithm to use with STREAM (default `"AES-PMAC-SIV"`)
+      # @param digest_alg [String] digest algorithm to use with HKDF (default `"SHA256"`)
+      # @param salt [String] (optional) salt value to pass to HKDF
+      def initialize(
+          private_key,
+          ephemeral_public,
+          encryption_alg: "AES-PMAC-SIV",
+          digest_alg: "SHA-256",
+          salt: nil
+      )
+        # Perform an X25519 elliptic curve Diffie-Hellman operation and use
+        # the resulting shared secret to derive a symmetric key (using HKDF)
+        symmetric_key = X25519HKDF.kdf(
+          private_key,
+          ephemeral_public,
+          salt: salt,
+          digest_alg: digest_alg,
+          output_size: SYMMETRIC_KEY_SIZE
+        )
+
+        super(encryption_alg, symmetric_key, XStream::NONCE)
+      end
+    end
+
+    # Derive a symmetric encryption key from the combination of a public and
+    # private key and salt using X25519 D-H and HKDF
+    def self.kdf(private_key, public_key, output_size:, salt: nil, digest_alg: "SHA-256")
+      raise ArgumentError, "invalid digest_alg: #{digest_alg}" unless digest_alg == "SHA-256"
+
+      # Use X25519 to compute a shared secret
+      shared_secret = X25519.diffie_hellman(private_key, public_key)
+
+      # Use HKDF to derive a symmetric encryption key from the shared secret
+      ::HKDF.new(
+        shared_secret,
+        salt: salt,
+        info: HKDF_INFO,
+        algorithm: "SHA256"
+      ).next_bytes(output_size)
+    end
+  end
+end

data/xstream.gemspec

@@ -20,5 +20,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.required_ruby_version = ">= 2.2.2"
+
+  spec.add_runtime_dependency "hkdf",      "~> 0.3"
+  spec.add_runtime_dependency "miscreant", "~> 0.3"
+  spec.add_runtime_dependency "x25519",    "~> 1.0"
+
   spec.add_development_dependency "bundler", "~> 1.16"
 end

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: xstream
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-14 00:00:00.000000000 Z
+date: 2018-01-05 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: hkdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: miscreant
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: x25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -39,8 +81,10 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- ci.sh
 - lib/xstream.rb
 - lib/xstream/version.rb
+- lib/xstream/x25519hkdf.rb
 - xstream.gemspec
 homepage: https://github.com/miscreant/xstream/
 licenses: []
@@ -61,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.4
 signing_key: 
 specification_version: 4
 summary: Public key encryption system combining X25519 Diffie-Hellman with the STREAM