miscreant 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96a35e90aee3d3f35dcbe9a273e57d9685b7d537
-  data.tar.gz: dc9ab108d1d8e69daccc528bc6f06f009ab584ed
+  metadata.gz: 28739a2b5b206f73877d8c3ecf7d1b90591dbbcb
+  data.tar.gz: d044df29dbe78614ef99cded5a1a0a3ccacbfed7
 SHA512:
-  metadata.gz: 8463583471437d1be6ef3885bbcee2ef6d78c58db500d2893a2ab3c91e6864eb5669fae96377d59d6a45e4711b6a2b7bbc57bb8d41f1a8538b0475a10ceeeb7e
-  data.tar.gz: f9d0be51f4255fed217290c9d07e90dea204e3009836bf5088eb861881d3b5f84b0d05804004c48d6b50e21f6367a0b8927177dd7cda138173fd1ef82d4a7039
+  metadata.gz: 536b1a5d7b38885783b24d99e19716ab72ea5167684f190ddccb2f5740329c55af95be9782c4f2246eb4b9684e03f0f1329b92abf22d7aee698cb117619eedcc
+  data.tar.gz: 4aa49283f01fc63f3b15b77b92b92ce2b98c4888342943355043bb731c915934742319e9e54862f82b25fc163a4b88e82c6304706e9fd6e88a9f256a463c6cb3

data/README.md

@@ -1,11 +1,11 @@
-# miscreant.rb [![Latest Version][gem-shield]][gem-link] [![Build Status][build-image]][build-link] [![Code Climate][codeclimate-image]][codeclimate-link] [![MIT licensed][license-image]][license-link] [![Gitter Chat][gitter-image]][gitter-link]
+# miscreant.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]
 
 [gem-shield]: https://badge.fury.io/rb/miscreant.svg
 [gem-link]: https://rubygems.org/gems/miscreant
 [build-image]: https://secure.travis-ci.org/miscreant/miscreant.svg?branch=master
 [build-link]: http://travis-ci.org/miscreant/miscreant
-[codeclimate-image]: https://codeclimate.com/github/miscreant/miscreant/badges/gpa.svg
-[codeclimate-link]: https://codeclimate.com/github/miscreant/miscreant
+[docs-image]: https://img.shields.io/badge/yard-docs-blue.svg
+[docs-link]: http://www.rubydoc.info/gems/miscreant/0.3.0
 [license-image]: https://img.shields.io/badge/license-MIT-blue.svg
 [license-link]: https://github.com/miscreant/miscreant/blob/master/LICENSE.txt
 [gitter-image]: https://badges.gitter.im/badge.svg
@@ -13,9 +13,17 @@
 
 > The best crypto you've never heard of, brought to you by [Phil Rogaway]
 
-Ruby implementation of **Miscreant**: Advanced symmetric encryption using the
-AES-SIV ([RFC 5297]) and [CHAIN/STREAM] constructions, providing easy-to-use (or
-rather, hard-to-misuse) encryption of individual messages or message streams.
+[Phil Rogaway]: https://en.wikipedia.org/wiki/Phillip_Rogaway
+
+Ruby implementation of **Miscreant**: Advanced symmetric encryption library
+which provides the [AES-SIV] ([RFC 5297]), [AES-PMAC-SIV], and [STREAM]
+constructions. These algorithms are easy-to-use (or rather, hard-to-misuse)
+and support encryption of individual messages or message streams.
+
+[AES-SIV]: https://github.com/miscreant/miscreant/wiki/AES-SIV
+[RFC 5297]: https://tools.ietf.org/html/rfc5297
+[AES-PMAC-SIV]: https://github.com/miscreant/miscreant/wiki/AES-PMAC-SIV
+[STREAM]: https://github.com/miscreant/miscreant/wiki/STREAM
 
 **AES-SIV** provides [nonce-reuse misuse-resistance] (NRMR): accidentally
 reusing a nonce with this construction is not a security catastrophe,
@@ -27,11 +35,7 @@ full plaintext recovery.
 
 For more information, see the [toplevel README.md].
 
-[Phil Rogaway]: https://en.wikipedia.org/wiki/Phillip_Rogaway
-[AES-SIV]: https://www.iacr.org/archive/eurocrypt2006/40040377/40040377.pdf
-[RFC 5297]: https://tools.ietf.org/html/rfc5297
-[CHAIN/STREAM]: http://web.cs.ucdavis.edu/~rogaway/papers/oae.pdf
-[nonce-reuse misuse-resistance]: https://www.lvh.io/posts/nonce-misuse-resistance-101.html
+[nonce-reuse misuse-resistance]: https://github.com/miscreant/miscreant/wiki/Nonce-Reuse-Misuse-Resistance
 [AES-GCM]: https://en.wikipedia.org/wiki/Galois/Counter_Mode
 [chosen ciphertext attacks]: https://en.wikipedia.org/wiki/Chosen-ciphertext_attack
 [toplevel README.md]: https://github.com/miscreant/miscreant/blob/master/README.md

data/ci.bat

@@ -0,0 +1 @@
+bundle && bundle exec rake spec

data/ci.sh

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

data/lib/miscreant.rb

@@ -5,11 +5,13 @@ require "openssl"
 require "securerandom"
 
 require "miscreant/version"
+
 require "miscreant/aead"
 require "miscreant/aes/cmac"
 require "miscreant/aes/pmac"
 require "miscreant/aes/siv"
 require "miscreant/internals"
+require "miscreant/stream"
 
 # Miscreant: A misuse-resistant symmetric encryption library
 module Miscreant
@@ -19,6 +21,9 @@ module Miscreant
   # Ciphertext failed to verify as authentic
   IntegrityError = Class.new(CryptoError)
 
+  # Integer value overflowed
+  OverflowError = Class.new(StandardError)
+
   # Hide internals from the outside world
   private_constant :Internals
 end

data/lib/miscreant/stream.rb

@@ -0,0 +1,132 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The STREAM online authenticated encryption construction.
+  # See <https://eprint.iacr.org/2015/189.pdf> for definition.
+  #
+  # Miscreant's implementation of STREAM uses an 8-byte (64-bit) nonce
+  # prefix along with a 32-bit counter and 1-byte "last block" flag
+  module STREAM
+    # Size of a nonce required by STREAM in bytes
+    NONCE_SIZE = 8
+
+    # Byte flag indicating this is the last block in the STREAM (otherwise 0)
+    LAST_BLOCK_FLAG = 1
+
+    # Maximum value of the STREAM counter
+    COUNTER_MAX = 2**32
+
+    # Raised if we attempt to continue an already-finished STREAM
+    FinishedError = Class.new(StandardError)
+
+    # A STREAM encryptor
+    #
+    # This corresponds to the ℰ stream encryptor object as defined in the paper
+    # Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance
+    class Encryptor
+      # Create a new STREAM encryptor.
+      #
+      # @param alg ["AES-SIV", "AES-PMAC-SIV"] cryptographic algorithm to use
+      # @param key [String] 32-byte or 64-byte random Encoding::BINARY secret key
+      # @param nonce [String] 8-byte nonce
+      #
+      # @raise [TypeError] nonce is not a String
+      # @raise [ArgumentError] nonce is wrong length or not Encoding::BINARY
+      def initialize(alg, key, nonce)
+        @aead = AEAD.new(alg, key)
+        @nonce_encoder = NonceEncoder.new(nonce)
+      end
+
+      # Encrypt the next message in the stream
+      #
+      # @param plaintext [String] plaintext message to encrypt
+      # @param ad [String] (optional) associated data to authenticate
+      # @param last_block [true, false] is this the last block in the STREAM?
+      #
+      # @return [String] ciphertext message
+      def seal(plaintext, ad: "", last_block: false)
+        @aead.seal(plaintext, nonce: @nonce_encoder.next(last_block), ad: ad)
+      end
+
+      # Inspect this STREAM encryptor instance
+      #
+      # @return [String] description of this instance
+      def inspect
+        to_s
+      end
+    end
+
+    # A STREAM decryptor
+    #
+    # This corresponds to the 𝒟 stream decryptor object as defined in the paper
+    # Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance
+    class Decryptor
+      # Create a new STREAM decryptor.
+      #
+      # @param alg ["AES-SIV", "AES-PMAC-SIV"] cryptographic algorithm to use
+      # @param key [String] 32-byte or 64-byte random Encoding::BINARY secret key
+      # @param nonce [String] 8-byte nonce
+      #
+      # @raise [TypeError] nonce is not a String
+      # @raise [ArgumentError] nonce is wrong length or not Encoding::BINARY
+      def initialize(alg, key, nonce)
+        @aead = AEAD.new(alg, key)
+        @nonce_encoder = NonceEncoder.new(nonce)
+      end
+
+      # Decrypt the next message in the stream
+      #
+      # @param ciphertext [String] cipher message to encrypt
+      # @param ad [String] (optional) associated data to authenticate
+      # @param last_block [true, false] is this the last block in the STREAM?
+      #
+      # @raise [Miscreant::IntegrityError] ciphertext and/or associated data are corrupt or tampered with
+      # @return [String] plaintext message
+      def open(ciphertext, ad: "", last_block: false)
+        @aead.open(ciphertext, nonce: @nonce_encoder.next(last_block), ad: ad)
+      end
+
+      # Inspect this STREAM encryptor instance
+      #
+      # @return [String] description of this instance
+      def inspect
+        to_s
+      end
+    end
+
+    # Computes STREAM nonces based on the current position in the STREAM.
+    class NonceEncoder
+      # Create a new nonce encoder with the given prefix
+      #
+      # @param [nonce_prefix] 64-bit string used as the STREAM nonce prefix
+      #
+      # @raise [TypeError] nonce prefix is not a String
+      # @raise [ArgumentError] nonce prefix is wrong length or not Encoding::BINARY
+      def initialize(nonce_prefix)
+        Internals::Util.validate_bytestring("nonce", nonce_prefix, length: NONCE_SIZE)
+        @nonce_prefix = nonce_prefix
+        @counter = 0
+        @finished = false
+      end
+
+      # Obtain the next nonce in the stream
+      #
+      # @param last_block [true, false] is this the last block?
+      #
+      # @return [String] encoded STREAM nonce
+      def next(last_block)
+        raise FinishedError, "STREAM is already finished" if @finished
+        @finished = last_block
+
+        encoded_nonce = [@nonce_prefix, @counter, last_block ? LAST_BLOCK_FLAG : 0].pack("a8NC")
+        @counter += 1
+        raise OverflowError, "STREAM counter overflowed" if @counter >= COUNTER_MAX
+
+        encoded_nonce
+      end
+    end
+
+    private_constant :NonceEncoder
+  end
+end

data/lib/miscreant/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Miscreant
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/miscreant.gemspec

@@ -11,8 +11,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["bascule@gmail.com"]
   spec.summary       = "Misuse-resistant authenticated symmetric encryption"
   spec.description   = <<-DESCRIPTION.strip.gsub(/\s+/, " ")
-    Misuse-resistant symmetric encryption using the AES-SIV (RFC 5297)
-    and CHAIN/STREAM constructions.
+    Misuse resistant symmetric encryption library providing AES-SIV (RFC 5297),
+    AES-PMAC-SIV, and STREAM constructions
   DESCRIPTION
 
   spec.version       = Miscreant::VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: miscreant
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-10-02 00:00:00.000000000 Z
+date: 2017-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,6 +38,8 @@ files:
 - Gemfile
 - README.md
 - Rakefile
+- ci.bat
+- ci.sh
 - lib/miscreant.rb
 - lib/miscreant/aead.rb
 - lib/miscreant/aes/cmac.rb
@@ -48,6 +50,7 @@ files:
 - lib/miscreant/internals/aes/ctr.rb
 - lib/miscreant/internals/block.rb
 - lib/miscreant/internals/util.rb
+- lib/miscreant/stream.rb
 - lib/miscreant/version.rb
 - miscreant.gemspec
 homepage: https://github.com/miscreant/miscreant/tree/master/ruby/
@@ -70,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
 summary: Misuse-resistant authenticated symmetric encryption