block_cipher_kit 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ffa6157fd34839dbc9c8af5cd121b647974d3c869ce61fb50f5d3027f8fb3c2
-  data.tar.gz: 8c14d6643ef3635d8e5ce8a66cbb16b30748b5e205989aacb3169842405c59f2
+  metadata.gz: 20609183e16f9958a035b581945c5d891851a85df83cbd19741b3e94efe3a676
+  data.tar.gz: bee694246cdd3eae36af264e7fb3b90dc3179c22203f82e38d028a3733ee99a5
 SHA512:
-  metadata.gz: b1c94c2b391c0bfe8f51ee94fd79563dbac77de43db7617eee679cca9adff6821a4e840152a091fe41bfdde1257875e7ed9d1d20bb77bcb5c19e888b1127478f
-  data.tar.gz: 281cfb7fc70c84629fb5a15226fc560053ba183dd0b3ad75d8b819eded71b61f534541a5aa486e794d6d73a1d9cddc2affaea3147406ae86f23673418c7d4e6c
+  metadata.gz: ac9365aa614c6b9f88fdad333da7577f6b2e1080430df7bafdbb15aba14f031183269407423e6ba79ba6757d9851f141bc09af7c82ed692830f95a7ca9d3ea48
+  data.tar.gz: 5620bce257285e2c18be847ce3557cc5876136562b4c5f619c6eda9c7d761de884dee493f218ae781879af17e7dd94ab7aa6fe7d1f58e884453ac1da1ab07673

data/.gitignore

@@ -55,3 +55,4 @@ tmp
 # Rubocop report
 rubocop.html
 
+pkg/*.gem

data/README.md

@@ -2,18 +2,17 @@
 
 Is a small shim on top of a few block ciphers. It is useful for encrypting and decrypting data stored in files, or accessible via IOs. The main addition from using "bare" ciphers is the addition of random access reads where it can be realised.
 
-The following constructions are currently implemented:
+The gem provides a number of **schemes** which are known, mostly correct ways to use a particular block cipher. You can use those schemes to do block encryption and decryption.
+The following schemes are currently implemented:
 
-* AES-256-CBC (limited random read access, requires reading to end of source)
+* AES-256-CBC (random read access with overhead of 3 blocks)
 * AES-256-CFB (limited random read access, requires reading to start offset)
 * AES-256-CFB-CIV - CIV for "concatenated IV", The IV is provided together with the encryption key (assumes unique key per message (limited random read access, requires reading to start offset) - 
-* AES-256-CTR (with random read access)
-* AES-256-GCM (with random read access via CTR, random read access does not validate)
+* AES-256-CTR (random read access)
+* AES-256-GCM (random read access via CTR, random read access does not validate)
 
 Most likely ChaCha20 cam be added fairly easily.
 
-The gem provides a number of **schemes** which are known, mostly correct ways to use a particular block cipher. You can use those schemes to do block encryption and decryption.
-
 ## What is a "scheme"?
 
 A scheme is a crypto **construction** - a particular way to use a particular block cipher. In this gem, the schemes are guaranteed not to change between releases. Once a scheme is part of the gem, you will be able to use that scheme to read data you have encrypted using that scheme. Most of the **schemes** provided by the gem are constructed from standard AES block ciphers, used in a standard, transparent manner.

data/Rakefile

@@ -15,4 +15,12 @@ task :format do
   `bundle exec magic_frozen_string_literal .`
 end
 
-task default: [:test, :standard]
+task :generate_typedefs do
+  `bundle exec sord rbi/block_cipher_kit.rbi`
+end
+
+# When building the gem, generate typedefs beforehand,
+# so that they get included
+Rake::Task["build"].enhance(["generate_typedefs"])
+
+task default: [:test, :standard, :generate_typedefs]

data/block_cipher_kit.gemspec

@@ -10,7 +10,12 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
   spec.summary = "A thin toolkit for working with block cipher encryption."
   spec.description = "A thin toolkit for working with block cipher encryption."
+
   spec.homepage = "https://github.com/julik/block_cipher_kit"
+  # The homepage link on rubygems.org only appears if you add homepage_uri. Just spec.homepage is not enough.
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
   spec.required_ruby_version = ">= 2.7.0"
 
@@ -27,7 +32,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake"
   spec.add_development_dependency "magic_frozen_string_literal"
   spec.add_development_dependency "standard", "1.28.5" # Needed for 2.6
-  spec.add_development_dependency "yard"
+
+  spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "sord"
   # redcarpet is needed for the yard gem to enable Github Flavored Markdown
   spec.add_development_dependency "redcarpet"
 

data/lib/block_cipher_kit/aes_256_cbc_scheme.rb

@@ -3,10 +3,12 @@ require "securerandom"
 class BlockCipherKit::AES256CBCScheme < BlockCipherKit::BaseScheme
   IV_LENGTH = 16
 
+  # @param encryption_key[String] a String in binary encoding containing the key for the cipher
+  # @param iv_generator[Random,SecureRandom] RNG that can output bytes. A deterministic substitute can be used for testing.
   def initialize(encryption_key, iv_generator: SecureRandom)
     raise ArgumentError, "#{required_encryption_key_length} bytes of key material needed, at the minimum" unless encryption_key.bytesize >= required_encryption_key_length
     @iv_generator = iv_generator
-    @key = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(0, 32))
+    @key = encryption_key.byteslice(0, 32)
   end
 
   def required_encryption_key_length
@@ -36,6 +38,10 @@ class BlockCipherKit::AES256CBCScheme < BlockCipherKit::BaseScheme
     n_bytes_to_decrypt = range.end - range.begin + 1
     n_blocks_to_skip, offset_into_first_block = range.begin.divmod(block_size)
 
+    # We need to read ahead to know well whether to call "final" on the cipher
+    n_blocks_to_read = (n_bytes_to_decrypt.to_f / block_size).ceil + 2
+    n_bytes_to_read = (n_blocks_to_read * block_size)
+
     cipher = OpenSSL::Cipher.new("aes-256-cbc")
     cipher.decrypt
     cipher.key = @key
@@ -46,11 +52,13 @@ class BlockCipherKit::AES256CBCScheme < BlockCipherKit::BaseScheme
     cipher.iv = from_ciphertext_io.read(IV_LENGTH)
 
     writable = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
-    lens_range = offset_into_first_block...(offset_into_first_block + n_bytes_to_decrypt)
-    lens = BlockCipherKit::IOLens.new(writable, lens_range)
+    lens = BlockCipherKit::WriteWindowIO.new(writable, offset_into_first_block, n_bytes_to_decrypt)
 
-    # TODO: it seems that if we read only the blocks we touch, we need to call cipher.final to get all the output - the cipher buffers,
-    # but if we call .final without having read the entire ciphertext the cipher will barf. This needs to be fixed as it is certainly possible with CBC.
-    read_copy_stream_via_cipher(source_io: from_ciphertext_io, destination_io: lens, cipher: cipher, finalize_cipher: true, read_limit: from_ciphertext_io.size - from_ciphertext_io.pos)
+    # We need to know whether we are going to be finishing our read with a block that may be shorter than
+    # block_size. In that case we must call `.final` on the cipher so that it releases us the decrypted
+    # plaintext instead of waiting for the remainder of the bits the last block consists of
+    bytes_remaining = from_ciphertext_io.size - from_ciphertext_io.pos
+    do_finalize = bytes_remaining < n_bytes_to_read
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, destination_io: lens, cipher: cipher, finalize_cipher: do_finalize, read_limit: n_bytes_to_read)
   end
 end

data/lib/block_cipher_kit/aes_256_cfb_civ_scheme.rb

@@ -1,10 +1,11 @@
 require "tempfile"
 
 class BlockCipherKit::AES256CFBCIVScheme < BlockCipherKit::BaseScheme
+  # @param encryption_key[String] a String in binary encoding containing the IV concatenated with the key for the cipher
   def initialize(encryption_key, **)
     raise ArgumentError, "#{required_encryption_key_length} bytes of key material needed, at the minimum" unless encryption_key.bytesize >= required_encryption_key_length
-    @iv = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(0, 16))
-    @key = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(16, 32))
+    @iv = encryption_key.byteslice(0, 16)
+    @key = encryption_key.byteslice(16, 32)
   end
 
   def required_encryption_key_length
@@ -29,7 +30,7 @@ class BlockCipherKit::AES256CFBCIVScheme < BlockCipherKit::BaseScheme
 
   def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
     writable = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
-    lens = BlockCipherKit::IOLens.new(writable, range)
+    lens = BlockCipherKit::WriteWindowIO.new(writable, range.begin, range.end - range.begin + 1)
     streaming_decrypt(from_ciphertext_io: from_ciphertext_io, into_plaintext_io: lens)
   end
 end

data/lib/block_cipher_kit/aes_256_cfb_scheme.rb

@@ -4,7 +4,7 @@ class BlockCipherKit::AES256CFBScheme < BlockCipherKit::BaseScheme
   def initialize(encryption_key, iv_generator: SecureRandom)
     raise ArgumentError, "#{required_encryption_key_length} bytes of key material needed, at the minimum" unless encryption_key.bytesize >= required_encryption_key_length
     @iv_generator = iv_generator
-    @key = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(0, 32))
+    @key = encryption_key.byteslice(0, 32)
   end
 
   def required_encryption_key_length
@@ -30,8 +30,10 @@ class BlockCipherKit::AES256CFBScheme < BlockCipherKit::BaseScheme
   end
 
   def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
+    # There is potential, but I don't have time for this at the moment
+    # https://crypto.stackexchange.com/a/87007
     writable = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
-    lens = BlockCipherKit::IOLens.new(writable, range)
+    lens = BlockCipherKit::WriteWindowIO.new(writable, range.begin, range.end - range.begin + 1)
     streaming_decrypt(from_ciphertext_io: from_ciphertext_io, into_plaintext_io: lens)
   end
 end

data/lib/block_cipher_kit/aes_256_ctr_scheme.rb

@@ -2,10 +2,12 @@ class BlockCipherKit::AES256CTRScheme < BlockCipherKit::BaseScheme
   NONCE_LENGTH_BYTES = 4
   IV_LENGTH_BYTES = 8
 
+  # @param encryption_key[String] a String in binary encoding containing the key for the cipher
+  # @param iv_generator[Random,SecureRandom] RNG that can output bytes. A deterministic substitute can be used for testing.
   def initialize(encryption_key, iv_generator: SecureRandom)
     raise ArgumentError, "#{required_encryption_key_length} bytes of key material needed, at the minimum" unless encryption_key.bytesize >= required_encryption_key_length
     @iv_generator = iv_generator
-    @key = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(0, 32))
+    @key = encryption_key.byteslice(0, 32)
   end
 
   def required_encryption_key_length
@@ -46,9 +48,8 @@ class BlockCipherKit::AES256CTRScheme < BlockCipherKit::BaseScheme
     cipher.key = @key
     cipher.iv = ctr_iv(nonce_and_iv, n_blocks_to_skip) # Set the counter for the first block we will be reading
 
-    lens_range = offset_into_first_block...(offset_into_first_block + n_bytes_to_read)
     writable = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
-    lens = BlockCipherKit::IOLens.new(writable, lens_range)
+    lens = BlockCipherKit::WriteWindowIO.new(writable, offset_into_first_block, n_bytes_to_read)
 
     # With CTR we do not need to read until the end of ciphertext as the cipher does not validate
     from_ciphertext_io.seek(ciphertext_starts_at + (n_blocks_to_skip * block_size))
@@ -56,6 +57,8 @@ class BlockCipherKit::AES256CTRScheme < BlockCipherKit::BaseScheme
     read_copy_stream_via_cipher(source_io: from_ciphertext_io, destination_io: lens, cipher: cipher, read_limit: n_blocks_to_read * block_size)
   end
 
+  private
+
   def ctr_iv(nonce_and_iv, for_block_n)
     # The IV is the counter block
     # see spec https://datatracker.ietf.org/doc/html/rfc3686#section-4

data/lib/block_cipher_kit/aes_256_gcm_scheme.rb

@@ -1,11 +1,14 @@
 class BlockCipherKit::AES256GCMScheme < BlockCipherKit::BaseScheme
   IV_LENGTH = 12
 
+  # @param encryption_key[String] a String in binary encoding containing the key for the cipher
+  # @param iv_generator[Random,SecureRandom] RNG that can output bytes. A deterministic substitute can be used for testing.
+  # @param auth_data[String] optional auth data for the cipher. If provided, this auth data will be used to write ciphertext and to validate.
   def initialize(encryption_key, iv_generator: SecureRandom, auth_data: "")
     raise ArgumentError, "#{required_encryption_key_length} bytes of key material needed, at the minimum" unless encryption_key.bytesize >= required_encryption_key_length
     @iv_generator = iv_generator
-    @auth_data = BlockCipherKit::KeyMaterial.new(auth_data.b)
-    @key = BlockCipherKit::KeyMaterial.new(encryption_key.byteslice(0, 32))
+    @auth_data = auth_data.b
+    @key = encryption_key.byteslice(0, 32)
   end
 
   def required_encryption_key_length
@@ -63,7 +66,11 @@ class BlockCipherKit::AES256GCMScheme < BlockCipherKit::BaseScheme
     read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, read_limit: n_bytes_to_read_excluding_auth_tag, destination_io: into_plaintext_io, &blk)
   end
 
-  def decrypt_range(from_ciphertext_io:, range:)
+  # Range decryption with GCM is performed by downgrading the GCM cipher to a CTR cipher, validation
+  # gets skipped.
+  #
+  # @see BaseScheme#streaming_decrypt_range
+  def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
     # GCM uses 16 byte blocks, but it writes the block
     # and the tag of 16 bytes. So actual block boundaries
     # are at 2x AES block size of 16 bytes. This is also
@@ -90,13 +97,15 @@ class BlockCipherKit::AES256GCMScheme < BlockCipherKit::BaseScheme
     cipher.iv = ctr_iv(initial_iv_from_input, n_blocks_to_skip) # Set the IV for the first block we will be reading
     cipher.key = @key
 
-    buf = StringIO.new.binmode
+    writable = BlockCipherKit::BlockWritable.new(into_plaintext_io, &blk)
+    lens = BlockCipherKit::WriteWindowIO.new(writable, offset_into_first_block, n_bytes_to_read)
+
     from_ciphertext_io.seek(ciphertext_starts_at + (n_blocks_to_skip * block_and_tag_size))
-    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, read_limit: n_blocks_to_read * block_and_tag_size, destination_io: buf)
-    buf.seek(offset_into_first_block) # Discard the bytes beyound the offset
-    buf.read(n_bytes_to_read) # return just the amount of bytes requested
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, read_limit: n_blocks_to_read * block_and_tag_size, destination_io: lens)
   end
 
+  private
+
   def ctr_iv(initial_iv_from_input, for_block_n)
     raise ArgumentError unless initial_iv_from_input.bytesize == 12
     # The counter gets incremented twice per block with GCM and the

data/lib/block_cipher_kit/base_scheme.rb

@@ -1,22 +1,97 @@
 class BlockCipherKit::BaseScheme
+  # Decrypts the entire ciphered message, reading ciphertext out of `from_ciphertext_io`
+  # until its `read` returns `nil` (until EOF is implicitly reached). The scheme
+  # will also read any data at the start of the IO that it requires for
+  # operation, and consume the IO until exhaustion.
+  #
+  # @param from_ciphertext_io[StraightReadableIO] An IO-ish that responds to `read` with one argument,
+  #     ciphertext will be read from that IO
+  # @param into_plaintext_io[WritableIO] An IO-ish that responds to `write` with one argument.
+  #     If into_plaintext_io is not provided, the block passed to the method will receive
+  #     String objects in binary encoding with chunks of decrypted ciphertext. The sizing
+  #     of the chunks is defined by the cipher and the read size used by `IO.copy_stream`
+  # @yield [String] the chunk of decrypted bytes
+  # @return [void]
   def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
     raise "Unimplemented"
   end
 
+  # Encrypts the entire ciphered message, reading plaintext either from the `from_plaintext_io`
+  # until its `read` returns `nil` (until EOF is implicitly reached) or from writes to
+  # the object it yields (for streaming writes).
+  #
+  # The scheme will also write any leading data at the start of the output that should prefix the
+  # ciphertext (usually the IV) and any trailing data after the ciphertext (like a validation
+  # tag for cipher authentication) into the `into_ciphertext_io`.
+  #
+  # @param from_plaintext_io[StraightReadableIO,nil] An IO-ish that responds to `read` with one argument.
+  #     If from_plaintext_io is not provided, the block passed to the method will receive
+  #     an IO-ish object that responds to `#write` that plaintext can be written into.
+  # @param into_ciphertext_io[WritableIO] An IO-ish that responds to `write` with one argument,
+  # @yield [#write] IO-ish writable that accepts strings of plaintext into `#write`
+  # @return [void]
   def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
     raise "Unimplemented"
   end
 
+  # Decrypts the desired range of the ciphered message, reading ciphertext out of `from_ciphertext_io`.
+  # Reading requires the `from_ciphertext_io` to be seekable - it must support `#pos`, `#read`and `#seek`.
+  # The decrypted plaintext either gets written into `into_plaintext_io` if it is provided, or yielded
+  # to the passed block in String chunks.
+  #
+  # @param from_ciphertext_io[RandomReadIO] Ciphertext will be read from that IO. The IO must support random access.
+  # @param range[Range] range of bytes in plaintext offsets to decrypt. Endless ranges are supported.
+  # @param into_plaintext_io[WritableIO] An IO-ish that responds to `write` with one argument.
+  #     If into_plaintext_io is not provided, the block passed to the method will receive
+  #     String objects in binary encoding with chunks of decrypted ciphertext. The sizing
+  #     of the chunks is defined by the cipher and the read size used by `IO.copy_stream`
+  # @yield [String] the chunk of decrypted bytes
+  # @return [void]
   def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
     raise "Unimplemented"
   end
 
+  # Decrypts the desired range of the ciphered message, reading ciphertext out of `from_ciphertext_io`.
+  # Reading requires the `from_ciphertext_io` to be seekable - it must support `#pos`, `#read`and `#seek`.
+  # The decrypted plaintext gets returned as a single concatenated String.
+  #
+  # @param from_ciphertext_io[RandomReadIO] Ciphertext will be read from that IO. The IO must support random access.
+  # @param range[Range] range of bytes in plaintext offsets to decrypt. Endless ranges are supported.
+  # @return [String] the decrypted bytes located at the given offset range inside the plaintext
   def decrypt_range(from_ciphertext_io:, range:)
     buf = StringIO.new.binmode
     streaming_decrypt_range(from_ciphertext_io: from_ciphertext_io, range: range, into_plaintext_io: buf)
     buf.string
   end
 
+  def inspect
+    # A reimplementation of #inspect based largely on
+    # https://alchemists.io/articles/ruby_object_inspection
+    pattern = +""
+    values = []
+
+    instance_variables.each do |name|
+      pattern << "#{name}=%s "
+      ivar_value = instance_variable_get(name)
+      if ivar_value.is_a?(String) && key_material_instance_variable_names.include?(name)
+        values.push("[SENSITIVE(#{ivar_value.bytesize * 8} bits)]")
+      else
+        values.push(ivar_value.inspect)
+      end
+    end
+
+    format "#<%s:%#018x #{pattern.strip}>", self.class, object_id << 1, *values
+  end
+
+  private
+
+  # The names of instance variables which contain key material and need to be masked in the
+  # output of BaseScheme#inspect. This prevents us from leaking the key, while allowing each
+  # subclass to define which ivars it considers sensitive.
+  def key_material_instance_variable_names
+    [:@key, :@iv]
+  end
+
   def read_copy_stream_via_cipher(source_io:, cipher:, read_limit: nil, destination_io: nil, finalize_cipher: true, &block_accepting_byte_chunks)
     writable = BlockCipherKit::BlockWritable.new(destination_io, &block_accepting_byte_chunks)
     cipher_io = BlockCipherKit::CipherIO.new(writable, cipher)

data/lib/block_cipher_kit/block_writable.rb

@@ -1,20 +1,24 @@
+# :nodoc:
 # 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)
+  def self.new(io = nil, &blk)
     if (!io && !blk) || (io && blk)
       raise ArgumentError, "BlockWritable requires io or a block, but not both"
     end
-    @io = io
+    # If the IO is given, it is better to just pass it through
+    # as IO.copy_stream will do optimisations for native IOs like
+    # File, Socket etc.
+    return io if io
+    super(&blk)
+  end
+
+  def initialize(&blk)
     @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
+    @blk.call(string.b)
     string.bytesize
   end
 end

data/lib/block_cipher_kit/cipher_io.rb

@@ -1,5 +1,6 @@
 # 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
+# :nodoc:
 class BlockCipherKit::CipherIO
   def initialize(io, cipher)
     @io = io

data/lib/block_cipher_kit/io_types.rb

@@ -0,0 +1,39 @@
+# Used as a stand-in for any IO-ish that responds to #read. This module is defined for YARD docs
+# so that Sorbet has a proper type definition.
+module StraightReadableIO
+  # @param n[Integer] how many bytes to read from the IO
+  # @return [String,nil] a String in binary encoding or nil
+  def read(n)
+  end
+end
+
+# Used as a stand-in for any IO-ish that responds to `#read`, `#seek`, `#pos` and `#size`
+# This module is defined for YARD docs so that Sorbet has a proper type definition.
+module RandomReadIO
+  # @param n[Integer] how many bytes to read from the IO
+  # @return [String,nil] a String in binary encoding or nil
+  def read(n)
+  end
+
+  # @param to_absolute_offset[Integer] the absolute offset in the IO to seek to
+  # @return [0]
+  def seek(to_absolute_offset)
+  end
+
+  # @return [Integer] current position in the IO
+  def pos
+  end
+
+  # @return [Integer] the total size of the data in the IO
+  def size
+  end
+end
+
+# Used as a stand-in for any IO that responds to `#write`
+# This module is defined for YARD docs so that Sorbet has a proper type definition.
+module WritableIO
+  # @param string[String] the bytes to write into the IO
+  # @return [Integer] the amount of bytes consumed. Will usually be `bytes.bytesize`
+  def write(string)
+  end
+end

data/lib/block_cipher_kit/read_window_io.rb

@@ -0,0 +1,35 @@
+class BlockCipherKit::ReadWindowIO
+  def initialize(io, starting_at_offset, window_size)
+    @io = io
+    @starting_at_offset = starting_at_offset.to_i
+    @window_size = window_size.to_i
+    @pos = 0
+  end
+
+  def size
+    @window_size
+  end
+
+  attr_reader :pos
+
+  def read(n_bytes)
+    return "" if n_bytes == 0 # As hardcoded for all Ruby IO objects
+    raise ArgumentError, "negative length #{n_bytes} given" if n_bytes < 0 # also as per Ruby IO objects
+
+    window_limit = @starting_at_offset + @window_size
+    wants_upto = @starting_at_offset + @pos + n_bytes
+
+    read_limit = [window_limit, wants_upto].compact.min
+    actual_n = read_limit - (@starting_at_offset + @pos)
+    return if actual_n <= 0
+
+    @io.seek(@starting_at_offset + @pos)
+    @io.read(actual_n).tap { @pos += actual_n }
+  end
+
+  def seek(to_offset_in_window)
+    raise ArgumentError, "negative seek destination #{to_offset_in_window}" if to_offset_in_window < 0 # also as per Ruby IO objects
+    @pos = to_offset_in_window
+    0
+  end
+end

data/lib/block_cipher_kit/version.rb

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

data/lib/block_cipher_kit/{io_lens.rb → write_window_io.rb}

@@ -1,10 +1,11 @@
 # 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)
+# :nodoc:
+class BlockCipherKit::WriteWindowIO
+  def initialize(io, offset, size)
+    @range = Range.new(offset, offset + size - 1)
     @io = io
-    @range = range
     @pos = 0
   end
 

data/lib/block_cipher_kit.rb

@@ -17,10 +17,16 @@ end
 
 require "securerandom"
 module BlockCipherKit
-  autoload :IOLens, __dir__ + "/block_cipher_kit/io_lens.rb"
+  autoload :WriteWindowIO, __dir__ + "/block_cipher_kit/write_window_io.rb"
+  autoload :ReadWindowIO, __dir__ + "/block_cipher_kit/read_window_io.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"
+
+  # private_constant :WriteWindowIO
+  # private_constant :ReadWindowIO
+  # private_constant :BlockWritable
+  # private_constant :CipherIO
+
   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"
@@ -28,5 +34,4 @@ module BlockCipherKit
   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/rbi/block_cipher_kit.rbi

@@ -0,0 +1,420 @@
+# typed: strong
+module BlockCipherKit
+  VERSION = T.let("0.0.3", T.untyped)
+
+  # 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
+  # :nodoc:
+  class CipherIO
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "cipher", using untyped
+    sig { params(io: T.untyped, cipher: T.untyped).void }
+    def initialize(io, cipher); end
+
+    # sord omit - no YARD type given for "bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(bytes: T.untyped).returns(T.untyped) }
+    def write(bytes); end
+  end
+
+  class BaseScheme
+    # Decrypts the entire ciphered message, reading ciphertext out of `from_ciphertext_io`
+    # until its `read` returns `nil` (until EOF is implicitly reached). The scheme
+    # will also read any data at the start of the IO that it requires for
+    # operation, and consume the IO until exhaustion.
+    # 
+    # _@param_ `from_ciphertext_io` — An IO-ish that responds to `read` with one argument, ciphertext will be read from that IO
+    # 
+    # _@param_ `into_plaintext_io` — An IO-ish that responds to `write` with one argument. If into_plaintext_io is not provided, the block passed to the method will receive String objects in binary encoding with chunks of decrypted ciphertext. The sizing of the chunks is defined by the cipher and the read size used by `IO.copy_stream`
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    # Encrypts the entire ciphered message, reading plaintext either from the `from_plaintext_io`
+    # until its `read` returns `nil` (until EOF is implicitly reached) or from writes to
+    # the object it yields (for streaming writes).
+    # 
+    # The scheme will also write any leading data at the start of the output that should prefix the
+    # ciphertext (usually the IV) and any trailing data after the ciphertext (like a validation
+    # tag for cipher authentication) into the `into_ciphertext_io`.
+    # 
+    # _@param_ `from_plaintext_io` — An IO-ish that responds to `read` with one argument. If from_plaintext_io is not provided, the block passed to the method will receive an IO-ish object that responds to `#write` that plaintext can be written into.
+    # 
+    # _@param_ `into_ciphertext_io` — An IO-ish that responds to `write` with one argument,
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    # Decrypts the desired range of the ciphered message, reading ciphertext out of `from_ciphertext_io`.
+    # Reading requires the `from_ciphertext_io` to be seekable - it must support `#pos`, `#read`and `#seek`.
+    # The decrypted plaintext either gets written into `into_plaintext_io` if it is provided, or yielded
+    # to the passed block in String chunks.
+    # 
+    # _@param_ `from_ciphertext_io` — Ciphertext will be read from that IO. The IO must support random access.
+    # 
+    # _@param_ `range` — range of bytes in plaintext offsets to decrypt. Endless ranges are supported.
+    # 
+    # _@param_ `into_plaintext_io` — An IO-ish that responds to `write` with one argument. If into_plaintext_io is not provided, the block passed to the method will receive String objects in binary encoding with chunks of decrypted ciphertext. The sizing of the chunks is defined by the cipher and the read size used by `IO.copy_stream`
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+
+    # Decrypts the desired range of the ciphered message, reading ciphertext out of `from_ciphertext_io`.
+    # Reading requires the `from_ciphertext_io` to be seekable - it must support `#pos`, `#read`and `#seek`.
+    # The decrypted plaintext gets returned as a single concatenated String.
+    # 
+    # _@param_ `from_ciphertext_io` — Ciphertext will be read from that IO. The IO must support random access.
+    # 
+    # _@param_ `range` — range of bytes in plaintext offsets to decrypt. Endless ranges are supported.
+    # 
+    # _@return_ — the decrypted bytes located at the given offset range inside the plaintext
+    sig { params(from_ciphertext_io: RandomReadIO, range: T::Range[T.untyped]).returns(String) }
+    def decrypt_range(from_ciphertext_io:, range:); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def inspect; end
+
+    # sord omit - no YARD return type given, using untyped
+    # The names of instance variables which contain key material and need to be masked in the
+    # output of BaseScheme#inspect. This prevents us from leaking the key, while allowing each
+    # subclass to define which ivars it considers sensitive.
+    sig { returns(T.untyped) }
+    def key_material_instance_variable_names; end
+
+    # sord omit - no YARD type given for "source_io:", using untyped
+    # sord omit - no YARD type given for "cipher:", using untyped
+    # sord omit - no YARD type given for "read_limit:", using untyped
+    # sord omit - no YARD type given for "destination_io:", using untyped
+    # sord omit - no YARD type given for "finalize_cipher:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig do
+      params(
+        source_io: T.untyped,
+        cipher: T.untyped,
+        read_limit: T.untyped,
+        destination_io: T.untyped,
+        finalize_cipher: T.untyped,
+        block_accepting_byte_chunks: T.untyped
+      ).returns(T.untyped)
+    end
+    def read_copy_stream_via_cipher(source_io:, cipher:, read_limit: nil, destination_io: nil, finalize_cipher: true, &block_accepting_byte_chunks); end
+
+    # sord omit - no YARD type given for "cipher:", using untyped
+    # sord omit - no YARD type given for "destination_io:", using untyped
+    # sord omit - no YARD type given for "source_io:", using untyped
+    # sord omit - no YARD type given for "read_limit:", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig do
+      params(
+        cipher: T.untyped,
+        destination_io: T.untyped,
+        source_io: T.untyped,
+        read_limit: T.untyped,
+        block_accepting_writable_io: T.untyped
+      ).returns(T.untyped)
+    end
+    def write_copy_stream_via_cipher(cipher:, destination_io:, source_io: nil, read_limit: nil, &block_accepting_writable_io); end
+  end
+
+  # :nodoc:
+  # 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 BlockWritable
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(io: T.untyped, blk: T.untyped).returns(T.untyped) }
+    def self.new(io = nil, &blk); end
+
+    sig { params(blk: T.untyped).void }
+    def initialize(&blk); end
+
+    # sord omit - no YARD type given for "string", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(string: T.untyped).returns(T.untyped) }
+    def write(string); end
+  end
+
+  class ReadWindowIO
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "starting_at_offset", using untyped
+    # sord omit - no YARD type given for "window_size", using untyped
+    sig { params(io: T.untyped, starting_at_offset: T.untyped, window_size: T.untyped).void }
+    def initialize(io, starting_at_offset, window_size); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def size; end
+
+    # sord omit - no YARD type given for "n_bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(n_bytes: T.untyped).returns(T.untyped) }
+    def read(n_bytes); end
+
+    # sord omit - no YARD type given for "to_offset_in_window", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(to_offset_in_window: T.untyped).returns(T.untyped) }
+    def seek(to_offset_in_window); end
+
+    # sord omit - no YARD type given for :pos, using untyped
+    # Returns the value of attribute pos.
+    sig { returns(T.untyped) }
+    attr_reader :pos
+  end
+
+  class PassthruScheme < BlockCipherKit::BaseScheme
+    sig { void }
+    def initialize; end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+  end
+
+  # Allows you to pass through the writes of a particular byte range only, discarding the rest
+  # :nodoc:
+  class WriteWindowIO
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "offset", using untyped
+    # sord omit - no YARD type given for "size", using untyped
+    sig { params(io: T.untyped, offset: T.untyped, size: T.untyped).void }
+    def initialize(io, offset, size); end
+
+    # sord omit - no YARD type given for "bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(bytes: T.untyped).returns(T.untyped) }
+    def write(bytes); end
+
+    # sord omit - no YARD type given for "range_a", using untyped
+    # sord omit - no YARD type given for "range_b", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # lifted from https://github.com/julik/range_utils/blob/master/lib/range_utils.rb
+    sig { params(range_a: T.untyped, range_b: T.untyped).returns(T.untyped) }
+    def intersection_of(range_a, range_b); end
+  end
+
+  class AES256CBCScheme < BlockCipherKit::BaseScheme
+    IV_LENGTH = T.let(16, T.untyped)
+
+    # sord warn - SecureRandom wasn't able to be resolved to a constant in this project
+    # _@param_ `encryption_key` — a String in binary encoding containing the key for the cipher
+    # 
+    # _@param_ `iv_generator` — RNG that can output bytes. A deterministic substitute can be used for testing.
+    sig { params(encryption_key: String, iv_generator: T.any(Random, SecureRandom)).void }
+    def initialize(encryption_key, iv_generator: SecureRandom); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def required_encryption_key_length; end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+  end
+
+  class AES256CFBScheme < BlockCipherKit::BaseScheme
+    IV_LENGTH = T.let(16, T.untyped)
+
+    # sord omit - no YARD type given for "encryption_key", using untyped
+    # sord omit - no YARD type given for "iv_generator:", using untyped
+    sig { params(encryption_key: T.untyped, iv_generator: T.untyped).void }
+    def initialize(encryption_key, iv_generator: SecureRandom); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def required_encryption_key_length; end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+  end
+
+  class AES256CTRScheme < BlockCipherKit::BaseScheme
+    NONCE_LENGTH_BYTES = T.let(4, T.untyped)
+    IV_LENGTH_BYTES = T.let(8, T.untyped)
+
+    # sord warn - SecureRandom wasn't able to be resolved to a constant in this project
+    # _@param_ `encryption_key` — a String in binary encoding containing the key for the cipher
+    # 
+    # _@param_ `iv_generator` — RNG that can output bytes. A deterministic substitute can be used for testing.
+    sig { params(encryption_key: String, iv_generator: T.any(Random, SecureRandom)).void }
+    def initialize(encryption_key, iv_generator: SecureRandom); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def required_encryption_key_length; end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+
+    # sord omit - no YARD type given for "nonce_and_iv", using untyped
+    # sord omit - no YARD type given for "for_block_n", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(nonce_and_iv: T.untyped, for_block_n: T.untyped).returns(T.untyped) }
+    def ctr_iv(nonce_and_iv, for_block_n); end
+  end
+
+  class AES256GCMScheme < BlockCipherKit::BaseScheme
+    IV_LENGTH = T.let(12, T.untyped)
+
+    # sord warn - SecureRandom wasn't able to be resolved to a constant in this project
+    # _@param_ `encryption_key` — a String in binary encoding containing the key for the cipher
+    # 
+    # _@param_ `iv_generator` — RNG that can output bytes. A deterministic substitute can be used for testing.
+    # 
+    # _@param_ `auth_data` — optional auth data for the cipher. If provided, this auth data will be used to write ciphertext and to validate.
+    sig { params(encryption_key: String, iv_generator: T.any(Random, SecureRandom), auth_data: String).void }
+    def initialize(encryption_key, iv_generator: SecureRandom, auth_data: ""); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def required_encryption_key_length; end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    # Range decryption with GCM is performed by downgrading the GCM cipher to a CTR cipher, validation
+    # gets skipped.
+    # 
+    # _@see_ `BaseScheme#streaming_decrypt_range`
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+
+    # sord omit - no YARD type given for "initial_iv_from_input", using untyped
+    # sord omit - no YARD type given for "for_block_n", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(initial_iv_from_input: T.untyped, for_block_n: T.untyped).returns(T.untyped) }
+    def ctr_iv(initial_iv_from_input, for_block_n); end
+  end
+
+  class AES256CFBCIVScheme < BlockCipherKit::BaseScheme
+    # _@param_ `encryption_key` — a String in binary encoding containing the IV concatenated with the key for the cipher
+    sig { params(encryption_key: String).void }
+    def initialize(encryption_key); end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def required_encryption_key_length; end
+
+    sig { params(from_ciphertext_io: StraightReadableIO, into_plaintext_io: T.nilable(WritableIO), blk: T.untyped).void }
+    def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk); end
+
+    sig { params(into_ciphertext_io: WritableIO, from_plaintext_io: T.nilable(StraightReadableIO), blk: T.untyped).void }
+    def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk); end
+
+    sig do
+      params(
+        from_ciphertext_io: RandomReadIO,
+        range: T::Range[T.untyped],
+        into_plaintext_io: T.nilable(WritableIO),
+        blk: T.untyped
+      ).void
+    end
+    def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk); end
+  end
+end
+
+# Used as a stand-in for any IO-ish that responds to #read. This module is defined for YARD docs
+# so that Sorbet has a proper type definition.
+module StraightReadableIO
+  # _@param_ `n` — how many bytes to read from the IO
+  # 
+  # _@return_ — a String in binary encoding or nil
+  sig { params(n: Integer).returns(T.nilable(String)) }
+  def read(n); end
+end
+
+# Used as a stand-in for any IO-ish that responds to `#read`, `#seek`, `#pos` and `#size`
+# This module is defined for YARD docs so that Sorbet has a proper type definition.
+module RandomReadIO
+  # _@param_ `n` — how many bytes to read from the IO
+  # 
+  # _@return_ — a String in binary encoding or nil
+  sig { params(n: Integer).returns(T.nilable(String)) }
+  def read(n); end
+
+  # _@param_ `to_absolute_offset` — the absolute offset in the IO to seek to
+  sig { params(to_absolute_offset: Integer).returns(Integer) }
+  def seek(to_absolute_offset); end
+
+  # _@return_ — current position in the IO
+  sig { returns(Integer) }
+  def pos; end
+
+  # _@return_ — the total size of the data in the IO
+  sig { returns(Integer) }
+  def size; end
+end
+
+# Used as a stand-in for any IO that responds to `#write`
+# This module is defined for YARD docs so that Sorbet has a proper type definition.
+module WritableIO
+  # _@param_ `string` — the bytes to write into the IO
+  # 
+  # _@return_ — the amount of bytes consumed. Will usually be `bytes.bytesize`
+  sig { params(string: String).returns(Integer) }
+  def write(string); end
+end

data/test/read_window_io_test.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class BlockCipherKit::ReadWindowTest < Minitest::Test
+  def test_read_window
+    text = "mary had a little lamb, riding on a pony"
+
+    window = BlockCipherKit::ReadWindowIO.new(StringIO.new(text), 0, 0)
+    assert_nil window.read(1)
+
+    window = BlockCipherKit::ReadWindowIO.new(StringIO.new(text), 0, 4)
+    assert_equal "m", window.read(1)
+    assert_equal "a", window.read(1)
+    assert_equal "ry", window.read(2)
+    assert_nil window.read(1)
+
+    io = StringIO.new(text)
+    window = BlockCipherKit::ReadWindowIO.new(io, 0, 4)
+    assert_equal 0, window.pos
+    assert_equal "m", window.read(1)
+    assert_equal 1, window.pos
+
+    io.seek(0)
+    assert_equal "a", window.read(1)
+    assert_equal 0, window.seek(0)
+
+    window = BlockCipherKit::ReadWindowIO.new(StringIO.new(text), 8, 23)
+    assert_equal " a l", window.read(4)
+    assert_equal "ittle la", window.read(8)
+
+    window = BlockCipherKit::ReadWindowIO.new(StringIO.new(text), 8, text.bytesize)
+    assert_equal " a little lamb, riding on a pony", window.read(400)
+    assert_nil window.read(1)
+  end
+end

data/test/schemes_test.rb

@@ -25,6 +25,12 @@ class SchemesTest < Minitest::Test
     end
   end
 
+  SCHEME_NAMES_INCLUDING_PASSTHRU.each do |scheme_class_name|
+    define_method "test_scheme #{scheme_class_name} encrypts and decrypts an empty message" do
+      assert_encrypts_and_decrypts_empty_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)
@@ -73,6 +79,20 @@ class SchemesTest < Minitest::Test
     assert_equal ciphertexts.length, ciphertexts.uniq.length
   end
 
+  def assert_encrypts_and_decrypts_empty_message(scheme_class_name)
+    rng = Random.new(Minitest.seed)
+    key = rng.bytes(48)
+
+    scheme = resolve(scheme_class_name).new(key)
+    ciphered_io = StringIO.new
+    scheme.streaming_encrypt(from_plaintext_io: StringIO.new, into_ciphertext_io: ciphered_io)
+
+    ciphered_io.rewind
+    decrypted = StringIO.new
+    scheme.streaming_decrypt(from_ciphertext_io: ciphered_io, into_plaintext_io: decrypted)
+    assert_equal 0, decrypted.size
+  end
+
   def assert_encrypts_from_block_and_io(scheme_class_name)
     rng = Random.new(Minitest.seed)
     encryption_key = rng.bytes(64)

data/test/write_window_io_test.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: block_cipher_kit
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-15 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -69,6 +69,20 @@ dependencies:
         version: 1.28.5
 - !ruby/object:Gem::Dependency
   name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: sord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -118,13 +132,13 @@ files:
 - lib/block_cipher_kit/base_scheme.rb
 - lib/block_cipher_kit/block_writable.rb
 - lib/block_cipher_kit/cipher_io.rb
-- lib/block_cipher_kit/io_lens.rb
-- lib/block_cipher_kit/key_material.rb
+- lib/block_cipher_kit/io_types.rb
 - lib/block_cipher_kit/passthru_scheme.rb
+- lib/block_cipher_kit/read_window_io.rb
 - lib/block_cipher_kit/version.rb
+- lib/block_cipher_kit/write_window_io.rb
+- rbi/block_cipher_kit.rbi
 - test/cipher_io_test.rb
-- test/io_lens_test.rb
-- test/key_material_test.rb
 - test/known_ciphertexts/AES256CBCScheme.ciphertext.bin
 - test/known_ciphertexts/AES256CFBCIVScheme.ciphertext.bin
 - test/known_ciphertexts/AES256CFBScheme.ciphertext.bin
@@ -132,13 +146,18 @@ files:
 - test/known_ciphertexts/AES256GCMScheme.ciphertext.bin
 - test/known_ciphertexts/PassthruScheme.ciphertext.bin
 - test/known_ciphertexts/known_plain.bin
+- test/read_window_io_test.rb
 - test/schemes_test.rb
 - test/test_helper.rb
 - test/test_known_ciphertext.rb
+- test/write_window_io_test.rb
 homepage: https://github.com/julik/block_cipher_kit
 licenses:
 - MIT
 metadata:
+  homepage_uri: https://github.com/julik/block_cipher_kit
+  source_code_uri: https://github.com/julik/block_cipher_kit
+  changelog_uri: https://github.com/julik/block_cipher_kit/blob/main/CHANGELOG.md
   allowed_push_host: https://rubygems.org
 post_install_message:
 rdoc_options: []

data/lib/block_cipher_kit/key_material.rb

@@ -1,16 +0,0 @@
-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/test/io_lens_test.rb

@@ -1,30 +0,0 @@
-# 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

@@ -1,12 +0,0 @@
-# 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