block_cipher_kit 0.0.1

data/lib/block_cipher_kit/block_writable.rb

@@ -0,0 +1,20 @@
+# An adapter which allows a block that accepts chunks of
+# written data to be used as an IO and passed to IO.copy_stream
+class BlockCipherKit::BlockWritable
+  def initialize(io = nil, &blk)
+    if (!io && !blk) || (io && blk)
+      raise ArgumentError, "BlockWritable requires io or a block, but not both"
+    end
+    @io = io
+    @blk = blk
+  end
+
+  def write(string)
+    if string.bytesize.nonzero? && @io
+      @io.write(string.b)
+    elsif string.bytesize.nonzero? && @blk
+      @blk.call(string.b)
+    end
+    string.bytesize
+  end
+end

data/lib/block_cipher_kit/cipher_io.rb

@@ -0,0 +1,16 @@
+# Allows an OpenSSL::Cipher to be written through as if it were an IO. This
+# allows the cipher to be passed to things like IO.copy_stream
+class BlockCipherKit::CipherIO
+  def initialize(io, cipher)
+    @io = io
+    @cipher = cipher
+  end
+
+  def write(bytes)
+    @io.write(@cipher.update(bytes))
+    # We must return the amount of bytes of input
+    # we have accepted, not the amount of bytes
+    # of output we produced from the cipher
+    bytes.bytesize
+  end
+end

data/lib/block_cipher_kit/io_lens.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Allows you to pass through the writes of a particular byte range only, discarding the rest
+class BlockCipherKit::IOLens
+  def initialize(io, range)
+    @io = io
+    @range = range
+    @pos = 0
+  end
+
+  def write(bytes)
+    previous_pos, @pos = @pos, @pos + bytes.bytesize
+    return 0 if bytes.bytesize == 0
+
+    location_in_output = Range.new(previous_pos, previous_pos + bytes.bytesize - 1)
+    overlap = intersection_of(@range, location_in_output)
+    if overlap
+      at = overlap.begin - previous_pos
+      n = overlap.end - overlap.begin + 1
+      @io.write(bytes.byteslice(at, n))
+    end
+
+    bytes.bytesize
+  end
+
+  private
+
+  # lifted from https://github.com/julik/range_utils/blob/master/lib/range_utils.rb
+  def intersection_of(range_a, range_b)
+    range_a = Range.new(range_a.begin, range_a.end.pred) if range_a.exclude_end?
+    range_b = Range.new(range_b.begin, range_b.end.pred) if range_b.exclude_end?
+
+    range_a = Range.new(0, range_a.end) if range_a.begin.nil?
+    range_b = Range.new(0, range_b.end) if range_b.begin.nil?
+
+    range_a = Range.new(range_a.begin, range_b.end) if range_a.end.nil?
+    range_b = Range.new(range_b.begin, range_a.end) if range_b.end.nil?
+
+    range_a, range_b = [range_a, range_b].sort_by(&:begin)
+    return if range_a.end < range_b.begin
+
+    heads_and_tails = [range_a.begin, range_b.begin, range_a.end, range_b.end].sort
+    middle = heads_and_tails[1..-2]
+    middle[0]..middle[1]
+  end
+end

data/lib/block_cipher_kit/key_material.rb

@@ -0,0 +1,16 @@
+require "forwardable"
+
+# Allows a string with key material (like IV and key)
+# to be concealed when an object holding it gets printed or show via #inspect
+class BlockCipherKit::KeyMaterial
+  extend Forwardable
+  def_delegators :@str, :b, :byteslice, :to_s, :to_str
+
+  def initialize(str)
+    @str = str
+  end
+
+  def inspect
+    "[SENSITIVE(#{@str.bytesize * 8} bits)]"
+  end
+end

data/lib/block_cipher_kit/passthru_scheme.rb

@@ -0,0 +1,26 @@
+class BlockCipherKit::PassthruScheme < BlockCipherKit::BaseScheme
+  def initialize(...)
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    w = into_plaintext_io || BlockCipherKit::BlockWritable.new(&blk)
+    IO.copy_stream(from_ciphertext_io, w)
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    if from_plaintext_io && !blk
+      IO.copy_stream(from_plaintext_io, into_ciphertext_io)
+    elsif blk
+      blk.call(into_ciphertext_io)
+    else
+      raise ArgumentError
+    end
+  end
+
+  def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
+    from_ciphertext_io.seek(from_ciphertext_io.pos + range.begin)
+    n_bytes = range.end - range.begin + 1
+    w = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
+    w.write(from_ciphertext_io.read(n_bytes))
+  end
+end

data/lib/block_cipher_kit/version.rb

@@ -0,0 +1,3 @@
+module BlockCipherKit
+  VERSION = "0.0.1"
+end

data/lib/block_cipher_kit.rb

@@ -0,0 +1,32 @@
+begin
+  require "openssl"
+rescue LoadError
+  message = <<~ERR
+    
+    Unable to load "openssl". You may be running a version of Ruby where the "openssl"
+    library is not contained in the standard library, but must be installed as a gem.
+    
+    We do not specify "openssl" as a dependency of block_cipher_kit because gems spun off
+    from the standard library can cause problems if they are specified as transitive dependencies,
+    especially on older Ruby versions.
+
+    Running `bundle add openssl` in your application will likely resolve the issue.
+  ERR
+  raise LoadError, message
+end
+
+require "securerandom"
+module BlockCipherKit
+  autoload :IOLens, __dir__ + "/block_cipher_kit/io_lens.rb"
+  autoload :BlockWritable, __dir__ + "/block_cipher_kit/block_writable.rb"
+  autoload :CipherIO, __dir__ + "/block_cipher_kit/cipher_io.rb"
+  autoload :KeyMaterial, __dir__ + "/block_cipher_kit/key_material.rb"
+  autoload :BaseScheme, __dir__ + "/block_cipher_kit/base_scheme.rb"
+  autoload :PassthruScheme, __dir__ + "/block_cipher_kit/passthru_scheme.rb"
+  autoload :AES256CTRScheme, __dir__ + "/block_cipher_kit/aes_256_ctr_scheme.rb"
+  autoload :AES256CBCScheme, __dir__ + "/block_cipher_kit/aes_256_cbc_scheme.rb"
+  autoload :AES256GCMScheme, __dir__ + "/block_cipher_kit/aes_256_gcm_scheme.rb"
+  autoload :AES256CFBScheme, __dir__ + "/block_cipher_kit/aes_256_cfb_scheme.rb"
+  autoload :AES256CFBCIVScheme, __dir__ + "/block_cipher_kit/aes_256_cfb_civ_scheme.rb"
+  autoload :EncryptedDiskService, __dir__ + "/block_cipher_kit/encrypted_disk_service.rb"
+end

data/test/cipher_io_test.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class CipherIOTest < Minitest::Test
+  class FakeCipher
+    def update(str)
+      str + "c"
+    end
+  end
+
+  def test_writes_through_the_cipher_and_returns_correct_data
+    out = StringIO.new
+    cipher_io = BlockCipherKit::CipherIO.new(out, FakeCipher.new)
+    assert_equal 2, cipher_io.write("ab")
+    assert_equal "abc", out.string
+  end
+end

data/test/io_lens_test.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class IOLensTest < Minitest::Test
+  def test_lens_writes
+    input = Random.bytes(48)
+    (1..input.bytesize).each do |write_size|
+      ranges = [
+        0..0,
+        0...1,
+        1..1,
+        1...2,
+        43..120,
+        14..,
+        ..14
+      ]
+      ranges.each do |test_range|
+        test_io = StringIO.new.binmode
+        readable = StringIO.new(input).binmode
+        lens = BlockCipherKit::IOLens.new(test_io, test_range)
+        while (chunk = readable.read(write_size))
+          lens.write(chunk)
+        end
+        assert_equal input[test_range].bytesize, test_io.size
+        assert_equal input[test_range], test_io.string
+      end
+    end
+  end
+end

data/test/key_material_test.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class KeyMaterialTest < Minitest::Test
+  def test_conceals_but_provides_string_access
+    km = BlockCipherKit::KeyMaterial.new("foo")
+    assert_equal "[SENSITIVE(24 bits)]", km.inspect
+    assert_equal "foo", [km].join
+    assert_equal "foo".b, km.b
+  end
+end

data/test/schemes_test.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class SchemesTest < Minitest::Test
+  SCHEME_NAMES = [
+    "BlockCipherKit::AES256CFBScheme",
+    "BlockCipherKit::AES256CFBCIVScheme",
+    "BlockCipherKit::AES256CTRScheme",
+    "BlockCipherKit::AES256GCMScheme",
+    "BlockCipherKit::AES256CBCScheme"
+  ]
+  SCHEME_NAMES_INCLUDING_PASSTHRU = SCHEME_NAMES + ["BlockCipherKit::PassthruScheme"]
+
+  SCHEME_NAMES_INCLUDING_PASSTHRU.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} encrypts and decrypts using both block and IO for input and output" do
+      assert_encrypts_from_block_and_io(scheme_class_name)
+      assert_decrypts_into_block_and_io(scheme_class_name)
+    end
+  end
+
+  SCHEME_NAMES_INCLUDING_PASSTHRU.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} encrypts and decrypts the entire message" do
+      assert_encrypts_and_decrypts_entire_message(scheme_class_name)
+    end
+  end
+
+  SCHEME_NAMES_INCLUDING_PASSTHRU.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} allows random access reads" do
+      assert_allows_random_access(scheme_class_name)
+    end
+  end
+
+  SCHEME_NAMES.each do |scheme_class_name|
+    define_method("test_scheme #{scheme_class_name} outputs different ciphertext depending on key") do
+      assert_key_changes_ciphertext(scheme_class_name)
+    end
+  end
+
+  SCHEME_NAMES.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} fails to initialise with a key too small" do
+      tiny_key = Random.new.bytes(3)
+      assert_raises(ArgumentError) do
+        resolve(scheme_class_name).new(tiny_key)
+      end
+    end
+  end
+
+  SCHEME_NAMES.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} does not expose key material in #inspect" do
+      big_key = "wonderful, absolutely incredible easiness of being, combined with unearthly pleasures"
+      inspectable = resolve(scheme_class_name).new(big_key).inspect
+      big_key.split(/\s/).each do |word|
+        refute inspectable.include?(word), "Output of #inspect must not reveal key material - was #{inspectable.inspect}"
+      end
+    end
+  end
+
+  def assert_key_changes_ciphertext(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    keys = 4.times.map { rng.bytes(64) }
+
+    n_bytes = rng.rand(129..2048)
+    plaintext = rng.bytes(n_bytes)
+
+    ciphertexts = keys.map do |k|
+      scheme = resolve(scheme_class_name).new(k)
+      encrypted_io = StringIO.new.binmode
+      scheme.streaming_encrypt(from_plaintext_io: StringIO.new(plaintext).binmode, into_ciphertext_io: encrypted_io)
+      encrypted_io.string
+    end
+
+    assert_equal ciphertexts.length, ciphertexts.uniq.length
+  end
+
+  def assert_encrypts_from_block_and_io(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    encryption_key = rng.bytes(64)
+
+    scheme = resolve(scheme_class_name).new(encryption_key)
+
+    # Generate a prime number of bytes, so that the plaintext does not
+    # subdivide into blocks. This will allow us to find situations where
+    # block offsets are not used for reading.
+    plaintext = rng.bytes(OpenSSL::BN.generate_prime(12))
+
+    out1 = StringIO.new.binmode
+    scheme.streaming_encrypt(into_ciphertext_io: out1) do |writable|
+      writable.write(plaintext.byteslice(0, 417))
+      writable.write(plaintext.byteslice(417, plaintext.bytesize))
+    end
+    assert out1.size > 0
+
+    out2 = StringIO.new.binmode
+    scheme.streaming_encrypt(from_plaintext_io: StringIO.new(plaintext), into_ciphertext_io: out2)
+    assert_equal out1.size, out2.size, "The size of the encrypted message must be the same when outputting via a block or a readable IO"
+
+    out1.rewind
+    out2.rewind
+
+    readback1 = StringIO.new.binmode.tap do |w|
+      scheme.streaming_decrypt(from_ciphertext_io: out1, into_plaintext_io: w)
+    end.string
+
+    readback2 = StringIO.new.binmode.tap do |w|
+      scheme.streaming_decrypt(from_ciphertext_io: out2, into_plaintext_io: w)
+    end.string
+
+    assert_equal plaintext, readback1
+    assert_equal plaintext, readback2
+  end
+
+  def assert_decrypts_into_block_and_io(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    encryption_key = rng.bytes(64)
+
+    scheme = resolve(scheme_class_name).new(encryption_key)
+
+    # Generate a prime number of bytes, so that the plaintext does not
+    # subdivide into blocks. This will allow us to find situations where
+    # block offsets are not used for reading.
+    plaintext = rng.bytes(OpenSSL::BN.generate_prime(12))
+    ciphertext_io = StringIO.new
+    scheme.streaming_encrypt(into_ciphertext_io: ciphertext_io, from_plaintext_io: StringIO.new(plaintext))
+
+    ciphertext_io.rewind
+    readback = StringIO.new.binmode
+    scheme.streaming_decrypt(from_ciphertext_io: ciphertext_io, into_plaintext_io: readback)
+    assert_equal readback.size, plaintext.bytesize
+    assert_equal readback.string[0..16], plaintext[0..16]
+    assert_equal readback.string[-4..], plaintext[-4..]
+
+    ciphertext_io.rewind
+    readback = StringIO.new.binmode
+    scheme.streaming_decrypt(from_ciphertext_io: ciphertext_io) do |chunk|
+      readback.write(chunk)
+    end
+    assert_equal readback.size, plaintext.bytesize
+    assert_equal readback.string[0..16], plaintext[0..16]
+    assert_equal readback.string[-4..], plaintext[-4..]
+  end
+
+  def assert_encrypts_and_decrypts_entire_message(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    random_encryption_key = rng.bytes(64)
+
+    enc = resolve(scheme_class_name).new(random_encryption_key)
+
+    # Generate a prime number of bytes, so that the plaintext does not
+    # subdivide into blocks. This will allow us to find situations where
+    # block offsets are not used for reading. A 24-bit prime we get is
+    # 14896667, which is just over 14 megabytes
+    amount_of_plain_bytes = OpenSSL::BN.generate_prime(24).to_i
+    plain_bytes = rng.bytes(amount_of_plain_bytes)
+
+    source_io = StringIO.new(plain_bytes)
+    enc_io = StringIO.new.binmode
+    enc_io.write("HDR") # emulate a header
+    enc.streaming_encrypt(from_plaintext_io: source_io, into_ciphertext_io: enc_io)
+
+    enc_io.seek(3) # Move to the offset where ciphertext starts
+
+    decrypted_io = StringIO.new.binmode
+    enc.streaming_decrypt(from_ciphertext_io: enc_io, into_plaintext_io: decrypted_io)
+    assert_equal decrypted_io.size, source_io.size, "#{scheme_class_name} should have decrypted the entire message"
+    assert_equal plain_bytes, decrypted_io.string, "#{scheme_class_name} Bytes mismatch when decrypting the entire message"
+  end
+
+  def assert_allows_random_access(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    random_encryption_key = rng.bytes(64)
+
+    enc = resolve(scheme_class_name).new(random_encryption_key)
+
+    # Generate a prime number of bytes, so that the plaintext does not
+    # subdivide into blocks. This will allow us to find situations where
+    # block offsets are not used for reading. A 24-bit prime we get is
+    # 14896667, which is just over 14 megabytes
+    amount_of_plain_bytes = OpenSSL::BN.generate_prime(24).to_i
+    plain_bytes = rng.bytes(amount_of_plain_bytes)
+
+    source_io = StringIO.new(plain_bytes)
+    enc_io = StringIO.new.binmode
+    enc_io.write("HDR") # emulate a header
+    enc.streaming_encrypt(from_plaintext_io: source_io, into_ciphertext_io: enc_io)
+
+    enc_io.seek(3) # Move to the offset where ciphertext starts
+
+    ranges = [
+      0..0, # The first byte
+      2..71, # Bytes that overlap block boundaries
+      78..91, # A random located byte
+      (amount_of_plain_bytes - 1)..(amount_of_plain_bytes - 1), # The last byte
+      0..(amount_of_plain_bytes - 1) # The entire monty, but via ranges
+    ]
+    ranges += 8.times.map do
+      r_begin = rng.rand(0..(amount_of_plain_bytes - 1))
+      n_bytes = rng.rand(1..1204)
+      r_begin..(r_begin + n_bytes)
+    end
+
+    ranges.each do |range|
+      enc_io.seek(3) # Emulate the header already did get read
+
+      expected = plain_bytes[range]
+      next unless expected
+
+      got = enc.decrypt_range(from_ciphertext_io: enc_io, range: range)
+
+      assert got, "#{scheme_class_name} Range #{range} should have been decrypted but no bytes were output"
+      assert_equal expected.bytesize, got.bytesize, "#{scheme_class_name} Range #{range} should have decrypted #{expected.bytesize} bytes but decrypted #{got.bytesize}"
+      assert_equal expected, got, "#{scheme_class_name} Range #{range} bytes mismatch (#{expected[0..16].inspect} expected but #{got[0..16].inspect} decrypted"
+    end
+  end
+
+  def resolve(module_name)
+    module_name.split("::").reduce(Kernel) do |namespace, const_name|
+      namespace.const_get(const_name)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "block_cipher_kit"
+require "minitest/autorun"

data/test/test_known_ciphertext.rb

@@ -0,0 +1,88 @@
+require_relative "test_helper"
+
+class TestKnownCiphertext < Minitest::Test
+  PREAMBLE = <<~ERR
+    This file is used as known plaintext for testing encryption schemes.
+    It is designed to be a decent input harness: its size in bytes is a prime,
+    so it will require padding to be produced if a cipher needs padding, and it
+    will not subdivide into any standard block sizes. The subsequent content is
+    not a hoax or a spoof. Bytes following this line are generated using the
+    Ruby Random RNG, which is seeded with 42 - the answer to Life, Universe and
+    Everything. You can verify that it is indeed so by generating the bytes yourself:
+      Random.new(42).bytes(prime_used_to_size_file - preamble_byte_length)
+    And now, enjoy randomness!
+    =====================================================================
+  ERR
+
+  SCHEME_NAMES = [
+    "BlockCipherKit::AES256CFBScheme",
+    "BlockCipherKit::AES256CFBCIVScheme",
+    "BlockCipherKit::AES256CTRScheme",
+    "BlockCipherKit::AES256GCMScheme",
+    "BlockCipherKit::AES256CBCScheme"
+  ]
+  SCHEME_NAMES_INCLUDING_PASSTHRU = SCHEME_NAMES + ["BlockCipherKit::PassthruScheme"]
+
+  SCHEME_NAMES_INCLUDING_PASSTHRU.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} produces deterministic ciphertext" do
+      assert_stable_ciphertext(scheme_class_name)
+    end
+  end
+
+  def io_with_known_plaintext
+    StringIO.new.binmode.tap do |out|
+      # Generate a prime number of bytes, so that the plaintext does not
+      # subdivide into blocks. This will allow us to find situations where
+      # block offsets are not used for reading. To get this number, we used
+      # OpenSSL::BN.generate_prime(12).to_i
+      amount_of_plain_bytes = 3623
+      n_bytes_of_randomness = amount_of_plain_bytes - PREAMBLE.bytesize
+      out.write(PREAMBLE)
+      out.write(Random.new(42).bytes(n_bytes_of_randomness))
+      out.rewind
+    end
+  end
+
+  def assert_stable_ciphertext(scheme_class_name)
+    key = Random.new(21).bytes(64) # The scheme will use as many as it needs
+    iv_rng = Random.new(42) # Ensure the cipher generates a deterministic IV, so that ciphertext comes out the same
+    scheme = resolve(scheme_class_name).new(key, iv_generator: iv_rng)
+
+    out = StringIO.new.binmode
+    known_plaintext_path = __dir__ + "/known_ciphertexts/known_plain.bin"
+    File.open(known_plaintext_path, "rb") do |f|
+      scheme.streaming_encrypt(from_plaintext_io: f, into_ciphertext_io: out)
+    end
+    out.rewind
+
+    known_ciphertext_path = __dir__ + "/known_ciphertexts/" + scheme.class.to_s.split("::").last + ".ciphertext.bin"
+    File.open(known_ciphertext_path, "rb") do |f|
+      assert_equal f.size, out.size, "The output of the scheme must be the same size as the known ciphertext"
+      while (chunk = f.read(1024))
+        assert_equal chunk, out.read(1024)
+      end
+    end
+  end
+
+  def regenerate_reference_files!
+    key = Random.new(21).bytes(64) # The scheme will use as many as it needs
+    iv_rng = Random.new(42) # Ensure the cipher generates a deterministic IV, so that ciphertext comes out the same
+    scheme = resolve(scheme_class_name).new(key, iv_generator: iv_rng)
+
+    known_plaintext_path = __dir__ + "/known_ciphertexts/known_plain.bin"
+    File.open(known_plaintext_path, "wb") do |f|
+      IO.copy_stream(io_with_known_plaintext, f)
+    end
+
+    known_ciphertext_path = __dir__ + "/known_ciphertexts/" + scheme.class.to_s.split("::").last + ".ciphertext.bin"
+    File.open(known_ciphertext_path, "wb") do |f|
+      scheme.streaming_encrypt(from_plaintext_io: io_with_known_plaintext, into_ciphertext_io: f)
+    end
+  end
+
+  def resolve(module_name)
+    module_name.split("::").reduce(Kernel) do |namespace, const_name|
+      namespace.const_get(const_name)
+    end
+  end
+end