miscreant 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23230bd423fada7ae6bfceeafeb1bff7133e8e75
-  data.tar.gz: 3dc5b9db54803f64f9e58a87a4ac89370e785b2e
+  metadata.gz: 96a35e90aee3d3f35dcbe9a273e57d9685b7d537
+  data.tar.gz: dc9ab108d1d8e69daccc528bc6f06f009ab584ed
 SHA512:
-  metadata.gz: c53969bd291002daf380591ee6547c49fa24e86e7b3e9c3fdb5c4575cbfa049a1db141af95f447dc8e4bf5a35a9acd053138a4cea1ee940c635cb44e2b0d50a9
-  data.tar.gz: 45871b8499fbf30d1090a4f45a31eaf6d54583f7e458013c701597a7ec28c2d7df8aac80b94adf717baf1b2b64a9233dc77fd7294595e744b948ae08df7c92c7
+  metadata.gz: 8463583471437d1be6ef3885bbcee2ef6d78c58db500d2893a2ab3c91e6864eb5669fae96377d59d6a45e4711b6a2b7bbc57bb8d41f1a8538b0475a10ceeeb7e
+  data.tar.gz: f9d0be51f4255fed217290c9d07e90dea204e3009836bf5088eb861881d3b5f84b0d05804004c48d6b50e21f6367a0b8927177dd7cda138173fd1ef82d4a7039

data/.rubocop.yml

@@ -17,6 +17,9 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Enabled: false
 
+Metrics/BlockLength:
+  Max: 100
+
 Metrics/ClassLength:
   Max: 100
 
@@ -30,5 +33,17 @@ Metrics/MethodLength:
 # Style
 #
 
+Style/AsciiComments:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/README.md

@@ -81,27 +81,24 @@ Or install it yourself as:
 
 ## API
 
-### Miscreant::AES::SIV
+### Miscreant::AEAD
 
-The `Miscreant::AES::SIV` class provides the main interface to the **AES-SIV**
+The `Miscreant::AEAD` 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):
+To make a new instance, pass in a binary-encoded 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).
 
 ```ruby
-key_bytes = Miscreant::AES::SIV.generate_key
-key = Miscreant::AES::SIV.new(key_bytes)
-# => #<Miscreant::AES::SIV:0x007fe0109e85e8>
+secret_key = Miscreant::AEAD.generate_key
+encryptor = Miscreant::AEAD.new("AES-SIV", secret_key)
 ```
 
 #### Encryption (#seal)
 
-The `Miscreant::AES::SIV#seal` method encrypts a message along with a set of
-*associated data* message headers.
+The `Miscreant::AEAD#seal` method encrypts a binary-encoded 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
@@ -114,23 +111,33 @@ Example:
 
 ```ruby
 message = "Hello, world!"
-nonce = SecureRandom.random_bytes(16)
+nonce = Miscreant::AEAD.generate_nonce
 ciphertext = key.seal(message, nonce)
 ```
 
 #### Decryption (#open)
 
-The `Miscreant::AES::SIV#open` method decrypts a ciphertext with the given key.
+The `Miscreant::AEAD#open` method decrypts a binary-encoded ciphertext with the
+given key.
 
 Example:
 
 ```ruby
 message = "Hello, world!"
-nonce = SecureRandom.random_bytes(16)
+nonce = Miscreant::AEAD.generate_nonce
 ciphertext = key.seal(message, nonce)
 plaintext = key.open(ciphertext, nonce)
 ```
 
+## Code of Conduct
+
+We abide by the [Contributor Covenant][cc] and ask that you do as well.
+
+For more information, please see [CODE_OF_CONDUCT.md].
+
+[cc]: https://contributor-covenant.org
+[CODE_OF_CONDUCT.md]: https://github.com/miscreant/miscreant/blob/master/CODE_OF_CONDUCT.md
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/miscreant/miscreant

data/lib/miscreant.rb

@@ -1,9 +1,14 @@
+# encoding: binary
 # frozen_string_literal: true
 
 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"
 
 # Miscreant: A misuse-resistant symmetric encryption library
@@ -13,4 +18,7 @@ module Miscreant
 
   # Ciphertext failed to verify as authentic
   IntegrityError = Class.new(CryptoError)
+
+  # Hide internals from the outside world
+  private_constant :Internals
 end

data/lib/miscreant/aead.rb

@@ -0,0 +1,93 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The AEAD class provides Authenticated Encryption with Associated Data
+  #
+  # If you're looking for the API to encrypt something, congratulations!
+  # This is the one you probably want to use. This class provides a high-level
+  # interface to Miscreant's misuse-resistant encryption.
+  class AEAD
+    # 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)
+      AES::SIV.generate_key(size)
+    end
+
+    # Generate a random "nonce" (i.e. number used once) value
+    #
+    # @param size [Integer] size of nonce in bytes (default 16)
+    #
+    # @return [String] newly generated nonce value
+    def self.generate_nonce(size = 16)
+      SecureRandom.random_bytes(size)
+    end
+
+    # Create a new AEAD encryptor instance.
+    #
+    # You will need to select an algorithm to use, passed as a string:
+    #
+    # * "AES-SIV" (RFC 5297): the original AES-SIV function, based on CMAC
+    # * "AES-PMAC-SIV": a parallelizable AES-SIV alternative
+    #
+    # Choose AES-PMAC-SIV if you'd like better performance.
+    # Choose AES-SIV if you'd like wider compatibility: AES-PMAC-SIV is
+    # presently implemented in the Miscreant libraries.
+    #
+    # @param alg ["AES-SIV", "AES-PMAC-SIV"] cryptographic algorithm to use
+    # @param key [String] 32-byte or 64-byte random Encoding::BINARY secret key
+    def initialize(alg, key)
+      Internals::Util.validate_bytestring("key", key, length: [32, 64])
+
+      case alg
+      when "AES-SIV", "AES-CMAC-SIV"
+        mac = :CMAC
+      when "AES-PMAC-SIV"
+        mac = :PMAC
+      else raise ArgumentError, "unsupported algorithm: #{alg.inspect}"
+      end
+
+      @siv = AES::SIV.new(key, mac)
+    end
+
+    # Inspect this AES-SIV instance
+    #
+    # @return [String] description of this instance
+    def inspect
+      to_s
+    end
+
+    # Encrypt a message, authenticating it along with the associated data
+    #
+    # @param plaintext [String] an Encoding::BINARY string to encrypt
+    # @param nonce [String] a unique-per-message value
+    # @param ad [String] optional data to authenticate along with the message
+    #
+    # @return [String] encrypted ciphertext
+    def seal(plaintext, nonce:, ad: "")
+      raise TypeError, "expected String, got #{nonce.class}" unless nonce.is_a?(String)
+      raise TypeError, "expected String, got #{ad.class}" unless ad.is_a?(String)
+
+      @siv.seal(plaintext, [ad, nonce])
+    end
+
+    # Verify and decrypt a ciphertext, authenticating it along with the associated data
+    #
+    # @param ciphertext [String] an Encoding::BINARY string to decrypt
+    # @param nonce [String] a unique-per-message value
+    # @param associated_data [String] optional data to authenticate along with the message
+    #
+    # @raise [Miscreant::IntegrityError] ciphertext and/or associated data are corrupt or tampered with
+    # @return [String] decrypted plaintext
+    def open(ciphertext, nonce:, ad: "")
+      raise TypeError, "expected nonce to be String, got #{nonce.class}" unless nonce.is_a?(String)
+      raise TypeError, "expected ad to be String, got #{ad.class}" unless ad.is_a?(String)
+
+      @siv.open(ciphertext, [ad, nonce])
+    end
+  end
+end

data/lib/miscreant/aes/cmac.rb

@@ -0,0 +1,63 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The Advanced Encryption Standard
+  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
+      def initialize(key)
+        @cipher = Internals::AES::BlockCipher.new(key)
+
+        @subkey1 = Internals::Block.new
+        @subkey1.encrypt(@cipher)
+        @subkey1.dbl
+
+        @subkey2 = @subkey1.dup
+        @subkey2.dbl
+      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)
+        Internals::Util.validate_bytestring("message", message)
+
+        if message.empty? || message.length % Internals::Block::SIZE != 0
+          message = Internals::Util.pad(message, Internals::Block::SIZE)
+          subkey = @subkey2
+        else
+          subkey = @subkey1
+        end
+
+        count = message.length / Internals::Block::SIZE
+        digest = Internals::Block.new
+
+        count.times do |i|
+          digest.xor_in_place(message[Internals::Block::SIZE * i, Internals::Block::SIZE])
+          digest.xor_in_place(subkey) if i == count - 1
+          digest.encrypt(@cipher)
+        end
+
+        digest.data
+      end
+    end
+  end
+end

data/lib/miscreant/aes/pmac.rb

@@ -0,0 +1,128 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The Advanced Encryption Standard
+  module AES
+    # The Parallel Message Authentication Code
+    class PMAC
+      # Number of L blocks to precompute (i.e. µ in the PMAC paper)
+      # TODO: dynamically compute these as needed
+      PRECOMPUTED_BLOCKS = 31
+
+      # Create a new PMAC instance
+      #
+      # @param key [String] 16-byte or 32-byte Encoding::BINARY cryptographic key
+      def initialize(key)
+        @cipher = Internals::AES::BlockCipher.new(key)
+
+        # L is defined as follows (quoted from the PMAC paper):
+        #
+        # Equation 1:
+        #
+        #     a · x =
+        #         a<<1 if firstbit(a)=0
+        #         (a<<1) ⊕ 0¹²⁰10000111 if firstbit(a)=1
+        #
+        # Equation 2:
+        #
+        #     a · x⁻¹ =
+        #         a>>1 if lastbit(a)=0
+        #         (a>>1) ⊕ 10¹²⁰1000011 if lastbit(a)=1
+        #
+        # Let L(0) ← L. For i ∈ [1..µ], compute L(i) ← L(i − 1) · x by
+        # Equation (1) using a shift and a conditional xor.
+        #
+        # Compute L(−1) ← L · x⁻¹ by Equation (2), using a shift and a
+        # conditional xor.
+        #
+        # Save the values L(−1), L(0), L(1), L(2), ..., L(µ) in a table.
+        # (Alternatively, [ed: as we have done in this codebase] defer computing
+        # some or  all of these L(i) values until the value is actually needed.)
+        @l = []
+        tmp = Internals::Block.new
+        tmp.encrypt(@cipher)
+
+        PRECOMPUTED_BLOCKS.times.each do
+          block = Internals::Block.new(tmp.data.dup)
+          block.data.freeze
+          block.freeze
+
+          @l << block
+          tmp.dbl
+        end
+
+        @l.freeze
+
+        # Compute L(−1) ← L · x⁻¹:
+        #
+        #     a>>1 if lastbit(a)=0
+        #     (a>>1) ⊕ 10¹²⁰1000011 if lastbit(a)=1
+        #
+        @l_inv = Internals::Block.new(@l[0].data.dup)
+        last_bit = @l_inv[Internals::Block::SIZE - 1] & 0x01
+
+        (Internals::Block::SIZE - 1).downto(1) do |i|
+          carry = Internals::Util.ct_select(@l_inv[i - 1] & 1, 0x80, 0)
+          @l_inv[i] = (@l_inv[i] >> 1) | carry
+        end
+
+        @l_inv[0] >>= 1
+        @l_inv[0] ^= Internals::Util.ct_select(last_bit, 0x80, 0)
+        @l_inv[Internals::Block::SIZE - 1] ^= Internals::Util.ct_select(last_bit, Internals::Block::R >> 1, 0)
+        @l_inv.freeze
+        @l_inv.data.freeze
+      end
+
+      # Inspect this PMAC instance
+      #
+      # @return [String] description of this instance
+      def inspect
+        to_s
+      end
+
+      # Compute the PMAC of the given input message in a single shot,
+      # outputting the MAC tag.
+      #
+      # Unlike other PMAC 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] PMAC tag
+      def digest(message)
+        Internals::Util.validate_bytestring("message", message)
+
+        offset = Internals::Block.new
+        tmp = Internals::Block.new
+        tag = Internals::Block.new
+        ctr = 0
+        remaining = message.bytesize
+
+        while remaining > Internals::Block::SIZE
+          offset.xor_in_place(@l.fetch(Internals::Util.ctz(ctr + 1)))
+
+          tmp.copy(offset)
+          tmp.xor_in_place(message[ctr * Internals::Block::SIZE, Internals::Block::SIZE])
+          tmp.encrypt(@cipher)
+          tag.xor_in_place(tmp)
+
+          ctr += 1
+          remaining -= Internals::Block::SIZE
+        end
+
+        if remaining == Internals::Block::SIZE
+          tag.xor_in_place(message[(ctr * Internals::Block::SIZE)..-1])
+          tag.xor_in_place(@l_inv)
+        else
+          remaining.times { |i| tag[i] ^= message.getbyte((ctr * Internals::Block::SIZE) + i) }
+          tag[remaining] ^= 0x80
+        end
+
+        tag.encrypt(@cipher)
+        tag.data
+      end
+    end
+  end
+end

data/lib/miscreant/aes/siv.rb

@@ -0,0 +1,123 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  # The Advanced Encryption Standard
+  module AES
+    # The SIV misuse resistant authenticated encryption mode
+    #
+    # This class is intended for power users. If you're uncertain if you
+    # should be using it, you probably want the `Miscreant::AEAD` API.
+    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
+      # @param mac [:CMAC, :PMAC] (optional) MAC function to use (default CMAC)
+      def initialize(key, mac_class = :CMAC)
+        Internals::Util.validate_bytestring("key", key, length: [32, 64])
+        length = key.length / 2
+
+        case mac_class
+        when :CMAC
+          @mac = CMAC.new(key[0, length])
+        when :PMAC
+          @mac = PMAC.new(key[0, length])
+        else raise ArgumentError, "bad MAC class: #{mac_class} (expected :CMAC or :PMAC)"
+        end
+
+        @ctr = Internals::AES::CTR.new(key[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)
+        v = _s2v(associated_data, plaintext)
+        ciphertext = @ctr.encrypt(_zero_iv_bits(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)
+        v = ciphertext[0, Internals::Block::SIZE]
+        plaintext = @ctr.encrypt(_zero_iv_bits(v), ciphertext[Internals::Block::SIZE..-1])
+        t = _s2v(associated_data, plaintext)
+        raise IntegrityError, "ciphertext verification failure!" unless Internals::Util.ct_equal(t, v)
+
+        plaintext
+      end
+
+      private
+
+      # 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.
+        d = Internals::Block.new
+        d.xor_in_place(@mac.digest(d.data))
+
+        associated_data.each do |ad|
+          d.dbl
+          d.xor_in_place(@mac.digest(ad))
+        end
+
+        if plaintext.bytesize >= Internals::Block::SIZE
+          # TODO: implement this more efficiently by adding IUF support to CMAC
+          difference = plaintext.length - Internals::Block::SIZE
+          beginning = plaintext[0, difference]
+          d.xor_in_place(plaintext[difference..-1])
+          msg = beginning + d.data
+        else
+          d.dbl
+          d.xor_in_place(Internals::Util.pad(plaintext, Internals::Block::SIZE))
+          msg = d.data
+        end
+
+        @mac.digest(msg)
+      end
+
+      # "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
+      def _zero_iv_bits(iv)
+        iv = iv.dup
+        iv.setbyte(8, iv.getbyte(8) & 0x7f)
+        iv.setbyte(12, iv.getbyte(12) & 0x7f)
+        iv
+      end
+    end
+  end
+end

data/lib/miscreant/internals.rb

@@ -1,9 +1,10 @@
+# encoding: binary
 # frozen_string_literal: true
 
-require "miscreant/internals/aes"
-require "miscreant/internals/aes/siv"
-require "miscreant/internals/aes/cmac"
+require "miscreant/internals/block"
 require "miscreant/internals/util"
+require "miscreant/internals/aes/block_cipher"
+require "miscreant/internals/aes/ctr"
 
 module Miscreant
   # Internal functionality not intended for direct consumption

data/lib/miscreant/internals/aes/block_cipher.rb

@@ -0,0 +1,48 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  module Internals
+    module AES # :nodoc:
+      # The AES cipher in a raw block mode (a.k.a. ECB mode)
+      #
+      # NOTE: The only valid use of ECB mode is constructing higher-level
+      # cryptographic primitives. This library uses this class to implement
+      # the CMAC and PMAC message authentication codes.
+      class BlockCipher # :nodoc:
+        # Create a new block cipher instance
+        #
+        # @param key [String] a random 16-byte or 32-byte Encoding::BINARY encryption key
+        #
+        # @raise [TypeError] the key was not a String
+        # @raise [ArgumentError] the key was the wrong length or encoding
+        def initialize(key)
+          Util.validate_bytestring("key", key, length: [16, 32])
+
+          @cipher = OpenSSL::Cipher.new("AES-#{key.length * 8}-ECB")
+          @cipher.encrypt
+          @cipher.padding = 0
+          @cipher.key = key
+        end
+
+        # Inspect this AES block cipher instance
+        #
+        # @return [String] description of this instance
+        def inspect
+          to_s
+        end
+
+        # Encrypt the given AES block-sized message
+        #
+        # @param message [String] a 16-byte Encoding::BINARY message to encrypt
+        #
+        # @raise [TypeError] the message was not a String
+        # @raise [ArgumentError] the message was the wrong length
+        def encrypt(message)
+          Util.validate_bytestring("message", message, length: Block::SIZE)
+          @cipher.update(message) + @cipher.final
+        end
+      end
+    end
+  end
+end

data/lib/miscreant/internals/aes/ctr.rb

@@ -0,0 +1,40 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  module Internals
+    module AES # :nodoc:
+      # The AES-CTR unauthenticated stream cipher
+      class CTR # :nodoc:
+        # Create a new AES-CTR instance
+        #
+        # @param key [String] 16-byte or 32-byte Encoding::BINARY cryptographic key
+        def initialize(key)
+          Util.validate_bytestring("key", key, length: [16, 32])
+          @cipher = OpenSSL::Cipher::AES.new(key.bytesize * 8, :CTR)
+          @cipher.encrypt
+          @cipher.key = key
+        end
+
+        # Inspect this AES-CTR instance
+        #
+        # @return [String] description of this instance
+        def inspect
+          to_s
+        end
+
+        # Encrypt the given message using the given counter (i.e. IV)
+        #
+        # @param iv [String] initial counter value as a 16-byte Encoding::BINARY string
+        # @param message [String] message to be encrypted
+        def encrypt(iv, message)
+          Util.validate_bytestring("IV", iv, length: Block::SIZE)
+          return "".b if message.empty?
+
+          @cipher.iv = iv
+          @cipher.update(message) + @cipher.final
+        end
+      end
+    end
+  end
+end

data/lib/miscreant/internals/block.rb

@@ -0,0 +1,103 @@
+# encoding: binary
+# frozen_string_literal: true
+
+module Miscreant
+  module Internals
+    # A 128-bit block (i.e. for AES)
+    class Block # :nodoc:
+      # Size of an AES block in bytes
+      SIZE = 16
+
+      # Minimal irreducible polynomial for a 128-bit block size
+      R = 0x87
+
+      attr_reader :data
+
+      # Create a new Block, optionally from the given data
+      def initialize(data = nil)
+        if data
+          @data = Util.validate_bytestring("block data", data, length: SIZE)
+        else
+          @data = "\0".b * SIZE
+        end
+      end
+
+      # Inspect the contents of the block in hex
+      def inspect
+        "#<#{self.class} data:\"#{@data.unpack('H*').first}\">"
+      end
+
+      # Retrieve the value of the byte at the given index as an integer
+      def [](n)
+        raise IndexError, "n must be zero or greater (got #{n})" if n < 0
+        raise IndexError, "n must be less than #{SIZE} (got #{n})" unless n < SIZE
+
+        @data.getbyte(n)
+      end
+
+      # Set the value of the byte at the given index as an integer
+      def []=(n, byte)
+        @data.setbyte(n, byte)
+      end
+
+      # Reset the value of this block to all zeroes
+      def clear
+        SIZE.times { |n| @data[n] = 0 }
+      end
+
+      # Copy the contents of another block into this block
+      def copy(other_block)
+        SIZE.times { |n| @data[n] = other_block.data[n] }
+      end
+
+      # Double a value over GF(2^128):
+      #
+      #     a<<1 if firstbit(a)=0
+      #     (a<<1) ⊕ 0¹²⁰10000111 if firstbit(a)=1
+      #
+      def dbl
+        overflow = 0
+        words = @data.unpack("N4").reverse
+
+        words.map! do |word|
+          new_word = (word << 1) & 0xFFFFFFFF
+          new_word |= overflow
+          overflow = (word & 0x80000000) >= 0x80000000 ? 1 : 0
+          new_word
+        end
+
+        @data = words.reverse.pack("N4")
+        @data[-1] = (@data[-1].ord ^ Util.ct_select(overflow, R, 0)).chr
+        self
+      end
+
+      # Encrypt this block in-place, replacing its current contents with
+      # their ciphertext under the given block cipher
+      #
+      # @param cipher [Miscreant::Internals::AES::BlockCipher] block cipher to encrypt with
+      def encrypt(cipher)
+        raise TypeError, "invalid cipher: #{cipher.class}" unless cipher.is_a?(AES::BlockCipher)
+
+        # TODO: more efficient in-place encryption
+        @data = cipher.encrypt(@data)
+      end
+
+      # XOR the given data into the current block in-place
+      #
+      # @param value [AES::Block, String] a block or String to XOR into this one
+      def xor_in_place(value)
+        case value
+        when Block
+          value = value.data
+        when String
+          Util.validate_bytestring("value", value, length: SIZE)
+        else raise TypeError, "invalid XOR input: #{value.class}"
+        end
+
+        SIZE.times do |i|
+          self[i] ^= value.getbyte(i)
+        end
+      end
+    end
+  end
+end

data/lib/miscreant/internals/util.rb

@@ -7,76 +7,72 @@ module Miscreant
     module Util # :nodoc:
       module_function
 
-      # Perform a doubling operation as described in the CMAC and SIV papers
-      def dbl(value)
-        overflow = 0
-        words = value.unpack("N4").reverse
+      # :nodoc: Lookup table for the number of trailing zeroes in a byte
+      CTZ_TABLE = [
+        8, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        6, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        7, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        6, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        5, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0,
+        4, 0, 1, 0, 2, 0, 1, 0, 3, 0, 1, 0, 2, 0, 1, 0
+      ].freeze
 
-        words.map! do |word|
-          new_word = (word << 1) & 0xFFFFFFFF
-          new_word |= overflow
-          overflow = (word & 0x80000000) >= 0x80000000 ? 1 : 0
-          new_word
-        end
+      # Perform a constant time-ish comparison of two bytestrings
+      def ct_equal(a, b)
+        return false unless a.bytesize == b.bytesize
 
-        result = words.reverse.pack("N4")
-        result[-1] = (result[-1].ord ^ select(overflow, 0x87, 0)).chr
-        result
-      end
+        l = a.unpack("C*")
+        r = 0
+        i = -1
 
-      # 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")
+        b.each_byte { |v| r |= v ^ l[i += 1] }
+        r.zero?
       end
 
       # Perform a constant time(-ish) branch operation
-      def select(subject, result_if_one, result_if_zero)
+      def ct_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)
+      # Count the number of zeros in a given 8-bit integer
+      #
+      # @param value [Integer] an integer in the 8-bit unsigned range (0-255)
+      def ctz(value)
+        CTZ_TABLE.fetch(value)
       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
+      # 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 comparison of two bytestrings
-      def ct_equal(a, b)
-        return false unless a.bytesize == b.bytesize
+      # Ensure a string is a valid bytestring (potentially of a given length)
+      def validate_bytestring(name, string, length: nil)
+        raise TypeError, "expected String for #{name}, got #{string.class}" unless string.is_a?(String)
+        raise ArgumentError, "#{name} must be Encoding::BINARY" unless string.encoding == Encoding::BINARY
 
-        l = a.unpack("C*")
-        r = 0
-        i = -1
+        case length
+        when Array
+          raise ArgumentError, "#{name} must be #{length.join(' or ')} bytes long" unless length.include?(string.bytesize)
+        when Integer
+          raise ArgumentError, "#{name} must be #{length}-bytes long" unless string.bytesize == length
+        else
+          raise TypeError, "bad length parameter: #{length.inspect} (#{length.class}" unless length.nil?
+        end
 
-        b.each_byte { |v| r |= v ^ l[i += 1] }
-        r.zero?
+        string
       end
     end
   end

data/lib/miscreant/version.rb

@@ -1,5 +1,6 @@
+# encoding: binary
 # frozen_string_literal: true
 
 module Miscreant
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: miscreant
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tony Arcieri
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-07-31 00:00:00.000000000 Z
+date: 2017-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -39,10 +39,14 @@ files:
 - README.md
 - Rakefile
 - lib/miscreant.rb
+- lib/miscreant/aead.rb
+- lib/miscreant/aes/cmac.rb
+- lib/miscreant/aes/pmac.rb
+- lib/miscreant/aes/siv.rb
 - lib/miscreant/internals.rb
-- lib/miscreant/internals/aes.rb
-- lib/miscreant/internals/aes/cmac.rb
-- lib/miscreant/internals/aes/siv.rb
+- lib/miscreant/internals/aes/block_cipher.rb
+- lib/miscreant/internals/aes/ctr.rb
+- lib/miscreant/internals/block.rb
 - lib/miscreant/internals/util.rb
 - lib/miscreant/version.rb
 - miscreant.gemspec

data/lib/miscreant/internals/aes.rb

@@ -1,15 +0,0 @@
-# encoding: binary
-# frozen_string_literal: true
-
-module Miscreant
-  module Internals
-    # The Advanced Encryption Standard Block Cipher
-    module AES # :nodoc:
-      # 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
-end

data/lib/miscreant/internals/aes/cmac.rb

@@ -1,79 +0,0 @@
-# encoding: binary
-# frozen_string_literal: true
-
-module Miscreant
-  module Internals
-    module AES
-      # The AES-CMAC message authentication code
-      class CMAC # :nodoc:
-        # 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
-end

data/lib/miscreant/internals/aes/siv.rb

@@ -1,120 +0,0 @@
-# encoding: binary
-# frozen_string_literal: true
-
-module Miscreant
-  module Internals
-    module AES
-      # The AES-SIV misuse resistant authenticated encryption cipher
-      class SIV # :nodoc:
-        # 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
-end