miscreant 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3b2740135b6e13589326c9b8f2c926edff86516
+  data.tar.gz: b4327cc7c72ce38aaec0208f967c67fdceb2508f
+SHA512:
+  metadata.gz: b24730c57fd7ef67a4e7699a63c05454875ffec00366212a31445111525b7fbd953d122f8ff88e1871e0f7caee792780394382b7b9021fb9a83772fbf8d2ad6f
+  data.tar.gz: ceafedfa57c9b6d6ca7a72d8d50e31041af4d9c5113ea7e2d6482ef49a456914411138d6a75f43f5f67340f8aed5fe71bac0a5bbe7581734c2379681e3e1cf15

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/.rakeTasks
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,34 @@
+AllCops:
+  DisplayCopNames: true
+
+#
+# Metrics
+#
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Max: 50
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 100
+
+Metrics/LineLength:
+  Max: 128
+
+Metrics/MethodLength:
+  Max: 25
+
+#
+# Style
+#
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/.ruby-version

@@ -0,0 +1 @@
+2.4.1

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "benchmark-ips"
+  gem "guard-rspec"
+  gem "rake"
+  gem "rspec", "~> 3.5"
+  gem "rubocop", "0.49.1"
+  gem "tjson", "~> 0.5"
+end

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2013-2017 John Downey, The Miscreant Developers
+
+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,142 @@
+# 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]
+
+[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
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
+[license-link]: https://github.com/miscreant/miscreant/blob/master/LICENSE.txt
+
+> 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] constructions, providing easy-to-use (or
+rather, hard-to-misuse) encryption of individual messages or message streams.
+
+**AES-SIV** provides [nonce-reuse misuse-resistance] (NRMR): accidentally
+reusing a nonce with this construction is not a security catastrophe,
+unlike it is with more popular AES encryption modes like [AES-GCM].
+With **AES-SIV**, the worst outcome of reusing a nonce is an attacker
+can see you've sent the same plaintext twice, as opposed to almost all other
+AES modes where it can facilitate [chosen ciphertext attacks] and/or
+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]: http://web.cs.ucdavis.edu/~rogaway/papers/oae.pdf
+[nonce-reuse misuse-resistance]: https://www.lvh.io/posts/nonce-misuse-resistance-101.html
+[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
+
+## 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+subscribe@googlegroups.com])
+
+[Gitter]: https://gitter.im/miscreant/Lobby
+[Google Group]: https://groups.google.com/forum/#!forum/miscreant
+[miscreant+subscribe@googlegroups.com]: mailto:miscreant+subscribe@googlegroups.com
+
+## 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
+
+Other Ruby versions may work, but are not officially supported.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "miscreant"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install miscreant
+
+## API
+
+### Miscreant::AES::SIV
+
+The `Miscreant::AES::SIV` class provides the main interface to the **AES-SIV**
+misuse resistant authenticated encryption function.
+
+To make a new instance, pass in a 32-byte or 64-byte key. Note that these
+options are twice the size of what you might be expecting (AES-SIV uses two
+AES keys).
+
+You can generate a random key using the `generate_key` method (default 32 bytes):
+
+```ruby
+key_bytes = Miscreant::AES::SIV.generate_key
+key = Miscreant::AES::SIV.new(key_bytes)
+# => #<Miscreant::AES::SIV:0x007fe0109e85e8>
+```
+
+#### Encryption (#seal)
+
+The `Miscreant::AES::SIV#seal` method encrypts a message along with a set of
+*associated data* message headers.
+
+It's recommended to include a unique "nonce" value with each message. This
+prevents those who may be observing your ciphertexts from being able to tell
+if you encrypted the same message twice. However, unlike other cryptographic
+algorithms where using a nonce has catastrophic security implications such as
+key recovery, reusing a nonce with AES-SIV only leaks repeated ciphertexts to
+attackers.
+
+Example:
+
+```ruby
+message = "Hello, world!"
+nonce = SecureRandom.random_bytes(16)
+ciphertext = key.seal(message, nonce)
+```
+
+#### Decryption (#open)
+
+The `Miscreant::AES::SIV#open` method decrypts a ciphertext with the given key.
+
+Example:
+
+```ruby
+message = "Hello, world!"
+nonce = SecureRandom.random_bytes(16)
+ciphertext = key.seal(message, nonce)
+plaintext = key.open(ciphertext, nonce)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/miscreant/miscreant
+
+## Copyright
+
+Copyright (c) 2013-2017 John Downey, [The Miscreant Developers][AUTHORS].
+See [LICENSE.txt] for further details.
+
+[AUTHORS]: https://github.com/miscreant/miscreant/blob/master/AUTHORS.md
+[LICENSE.txt]: https://github.com/miscreant/miscreant/blob/master/ruby/LICENSE.txt

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+task default: %w[spec rubocop]

data/lib/miscreant.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require "miscreant/version"
+
+require "miscreant/aes"
+require "miscreant/aes/siv"
+require "miscreant/aes/cmac"
+require "miscreant/util"
+
+# Misuse-resistant symmetric encryption using the AES-SIV (RFC 5297) and CHAIN constructions
+module Miscreant
+  # Parent of all cryptography-related errors
+  CryptoError = Class.new(StandardError)
+
+  # Ciphertext failed to verify as authentic
+  IntegrityError = Class.new(CryptoError)
+end

data/lib/miscreant/aes.rb

@@ -0,0 +1,13 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The Advanced Encryption Standard Block Cipher
+  module AES
+    # Size of an AES block (i.e. input/output from the AES function)
+    BLOCK_SIZE = 16
+
+    # A bytestring of all zeroes, the same length as an AES block
+    ZERO_BLOCK = ("\0" * BLOCK_SIZE).freeze
+  end
+end

data/lib/miscreant/aes/cmac.rb

@@ -0,0 +1,77 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  module AES
+    # The AES-CMAC message authentication code
+    class CMAC
+      # Create a new AES-CMAC instance
+      #
+      # @param key [String] 16-byte or 32-byte Encoding::BINARY cryptographic key
+      #
+      # @return [Miscreant::AES::CMAC] new AES-CMAC instance
+      def initialize(key)
+        raise TypeError, "expected String, got #{key.class}" unless key.is_a?(String)
+        raise ArgumentError, "key must be Encoding::BINARY" unless key.encoding == Encoding::BINARY
+        raise ArgumentError, "key must be 32 or 64 bytes" unless [16, 32].include?(key.length)
+
+        # The only valid use of ECB mode: constructing higher-level cryptographic primitives
+        @cipher = OpenSSL::Cipher.new("AES-#{key.length * 8}-ECB")
+        @cipher.encrypt
+        @cipher.padding = 0
+        @cipher.key = key
+        @key1, @key2 = _generate_subkeys
+      end
+
+      # Inspect this AES-CMAC instance
+      #
+      # @return [String] description of this instance
+      def inspect
+        to_s
+      end
+
+      # Compute the AES-CMAC of the given input message in a single shot,
+      # outputting the MAC tag.
+      #
+      # Unlike other AES-CMAC implementations, this one does not support
+      # incremental processing/IUF operation. (Though that would enable
+      # slightly more efficient decryption for AES-SIV)
+      #
+      # @param message [String] an Encoding::BINARY string to authenticate
+      #
+      # @return [String] CMAC tag
+      def digest(message)
+        raise TypeError, "expected String, got #{message.class}" unless message.is_a?(String)
+        raise ArgumentError, "message must be Encoding::BINARY" unless message.encoding == Encoding::BINARY
+
+        if message.empty? || message.length % AES::BLOCK_SIZE != 0
+          message = Util.pad(message, AES::BLOCK_SIZE)
+          final_block = @key2
+        else
+          final_block = @key1
+        end
+
+        count = message.length / AES::BLOCK_SIZE
+        result = AES::ZERO_BLOCK
+
+        count.times do |i|
+          block = message.slice(AES::BLOCK_SIZE * i, AES::BLOCK_SIZE)
+          block = Util.xor(final_block, block) if i == count - 1
+          block = Util.xor(block, result)
+          result = @cipher.update(block) + @cipher.final
+        end
+
+        result
+      end
+
+      private
+
+      def _generate_subkeys
+        key0 = @cipher.update(AES::ZERO_BLOCK) + @cipher.final
+        key1 = Util.dbl(key0)
+        key2 = Util.dbl(key1)
+        [key1, key2]
+      end
+    end
+  end
+end

data/lib/miscreant/aes/siv.rb

@@ -0,0 +1,118 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  module AES
+    # The AES-SIV misuse resistant authenticated encryption cipher
+    class SIV
+      # Generate a new random AES-SIV key of the given size
+      #
+      # @param size [Integer] size of key in bytes (32 or 64)
+      #
+      # @return [String] newly generated AES-SIV key
+      def self.generate_key(size = 32)
+        raise ArgumentError, "key size must be 32 or 64 bytes" unless [32, 64].include?(size)
+        SecureRandom.random_bytes(size)
+      end
+
+      # Create a new AES-SIV instance
+      #
+      # @param key [String] 32-byte or 64-byte Encoding::BINARY cryptographic key
+      #
+      # @return [Miscreant::AES::SIV] new AES-SIV instance
+      def initialize(key)
+        raise TypeError, "expected String, got #{key.class}" unless key.is_a?(String)
+        raise ArgumentError, "key must be Encoding::BINARY" unless key.encoding == Encoding::BINARY
+        raise ArgumentError, "key must be 32 or 64 bytes" unless [32, 64].include?(key.length)
+
+        length = key.length / 2
+
+        @mac_key = key.slice(0, length)
+        @enc_key = key.slice(length..-1)
+      end
+
+      # Inspect this AES-SIV instance
+      #
+      # @return [String] description of this instance
+      def inspect
+        to_s
+      end
+
+      # Encrypt a message using AES-SIV, authenticating it along with the associated data
+      #
+      # @param plaintext [String] an Encoding::BINARY string to encrypt
+      # @param associated_data [Array<String>] optional array of message headers to authenticate
+      #
+      # @return [String] encrypted ciphertext
+      def seal(plaintext, associated_data = [])
+        raise TypeError, "expected String, got #{plaintext.class}" unless plaintext.is_a?(String)
+        raise ArgumentError, "plaintext must be Encoding::BINARY" unless plaintext.encoding == Encoding::BINARY
+
+        v = _s2v(associated_data, plaintext)
+        ciphertext = _transform(v, plaintext)
+        v + ciphertext
+      end
+
+      # Verify and decrypt an AES-SIV ciphertext, authenticating it along with the associated data
+      #
+      # @param ciphertext [String] an Encoding::BINARY string to decrypt
+      # @param associated_data [Array<String>] optional array of message headers to authenticate
+      #
+      # @raise [Miscreant::IntegrityError] ciphertext and/or associated data are corrupt or tampered with
+      # @return [String] decrypted plaintext
+      def open(ciphertext, associated_data = [])
+        raise TypeError, "expected String, got #{ciphertext.class}" unless ciphertext.is_a?(String)
+        raise ArgumentError, "ciphertext must be Encoding::BINARY" unless ciphertext.encoding == Encoding::BINARY
+
+        v = ciphertext.slice(0, AES::BLOCK_SIZE)
+        ciphertext = ciphertext.slice(AES::BLOCK_SIZE..-1)
+        plaintext = _transform(v, ciphertext)
+
+        t = _s2v(associated_data, plaintext)
+        raise IntegrityError, "ciphertext verification failure!" unless Util.ct_equal(t, v)
+
+        plaintext
+      end
+
+      private
+
+      # Performs raw unauthenticted encryption or decryption of the message
+      def _transform(v, data)
+        return "".b if data.empty?
+
+        cipher = OpenSSL::Cipher::AES.new(@mac_key.length * 8, :CTR)
+        cipher.encrypt
+        cipher.iv = Util.zero_iv_bits(v)
+        cipher.key = @enc_key
+        cipher.update(data) + cipher.final
+      end
+
+      # The S2V operation consists of the doubling and XORing of the outputs
+      # of the pseudo-random function CMAC.
+      #
+      # See Section 2.4 of RFC 5297 for more information
+      def _s2v(associated_data, plaintext)
+        # Note: the standalone S2V returns CMAC(1) if the number of passed
+        # vectors is zero, however in SIV construction this case is never
+        # triggered, since we always pass plaintext as the last vector (even
+        # if it's zero-length), so we omit this case.
+        cmac = CMAC.new(@mac_key)
+        d = cmac.digest(AES::ZERO_BLOCK)
+
+        associated_data.each do |ad|
+          d = Util.dbl(d)
+          d = Util.xor(d, cmac.digest(ad))
+        end
+
+        if plaintext.bytesize >= AES::BLOCK_SIZE
+          d = Util.xorend(plaintext, d)
+        else
+          d = Util.dbl(d)
+          d = Util.xor(d, Util.pad(plaintext, AES::BLOCK_SIZE))
+        end
+
+        cmac.digest(d)
+      end
+    end
+  end
+end

data/lib/miscreant/util.rb

@@ -0,0 +1,81 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # Internal utility functions
+  module Util
+    module_function
+
+    # Perform a doubling operation as described in the CMAC and SIV papers
+    def dbl(value)
+      overflow = 0
+      words = value.unpack("N4").reverse
+
+      words.map! do |word|
+        new_word = (word << 1) & 0xFFFFFFFF
+        new_word |= overflow
+        overflow = (word & 0x80000000) >= 0x80000000 ? 1 : 0
+        new_word
+      end
+
+      result = words.reverse.pack("N4")
+      result[-1] = (result[-1].ord ^ select(overflow, 0x87, 0)).chr
+      result
+    end
+
+    # Pad value with a 0x80 value and zeroes up to the given length
+    def pad(message, length)
+      padded_length = message.length + length - (message.length % length)
+      message += "\x80"
+      message.ljust(padded_length, "\0")
+    end
+
+    # Perform a constant time(-ish) branch operation
+    def select(subject, result_if_one, result_if_zero)
+      (~(subject - 1) & result_if_one) | ((subject - 1) & result_if_zero)
+    end
+
+    # Perform an xor on arbitrary bytestrings
+    def xor(a, b)
+      length = [a.length, b.length].min
+      output = "\0" * length
+      length.times do |i|
+        output[i] = (a[i].ord ^ b[i].ord).chr
+      end
+      output
+    end
+
+    # XOR the second value into the end of the first
+    def xorend(a, b)
+      difference = a.length - b.length
+
+      left  = a.slice(0, difference)
+      right = a.slice(difference..-1)
+
+      left + xor(right, b)
+    end
+
+    # Zero out the top bits in the last 32-bit words of the IV
+    def zero_iv_bits(iv)
+      # "We zero-out the top bit in each of the last two 32-bit words
+      # of the IV before assigning it to Ctr"
+      # -- http://web.cs.ucdavis.edu/~rogaway/papers/siv.pdf
+      iv = iv.dup
+      iv[8] = (iv[8].ord & 0x7f).chr
+      iv[12] = (iv[12].ord & 0x7f).chr
+      iv
+    end
+
+    # Perform a constant time-ish comparison of two bytestrings
+    def ct_equal(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack("C*")
+      r = 0
+      i = -1
+
+      b.each_byte { |v| r |= v ^ l[i += 1] }
+      r.zero?
+    end
+  end
+end

data/lib/miscreant/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Miscreant
+  VERSION = "0.0.0"
+end

data/miscreant.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "miscreant/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "miscreant"
+  spec.version       = Miscreant::VERSION
+  spec.authors       = ["Tony Arcieri"]
+  spec.email         = ["bascule@gmail.com"]
+  spec.licenses      = ["MIT"]
+  spec.homepage      = "https://github.com/miscreant/miscreant/tree/master/ruby/"
+  spec.summary       = "Misuse-resistant authenticated symmetric encryption"
+  spec.description   = "Misuse-resistant symmetric encryption using the AES-SIV (RFC 5297) and CHAIN constructions"
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 2.2.2"
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: miscreant
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Tony Arcieri
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-07-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+description: Misuse-resistant symmetric encryption using the AES-SIV (RFC 5297) and
+  CHAIN constructions
+email:
+- bascule@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/miscreant.rb
+- lib/miscreant/aes.rb
+- lib/miscreant/aes/cmac.rb
+- lib/miscreant/aes/siv.rb
+- lib/miscreant/util.rb
+- lib/miscreant/version.rb
+- miscreant.gemspec
+homepage: https://github.com/miscreant/miscreant/tree/master/ruby/
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Misuse-resistant authenticated symmetric encryption
+test_files: []