block_cipher_kit 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ffa6157fd34839dbc9c8af5cd121b647974d3c869ce61fb50f5d3027f8fb3c2
+  data.tar.gz: 8c14d6643ef3635d8e5ce8a66cbb16b30748b5e205989aacb3169842405c59f2
+SHA512:
+  metadata.gz: b1c94c2b391c0bfe8f51ee94fd79563dbac77de43db7617eee679cca9adff6821a4e840152a091fe41bfdde1257875e7ed9d1d20bb77bcb5c19e888b1127478f
+  data.tar.gz: 281cfb7fc70c84629fb5a15226fc560053ba183dd0b3ad75d8b819eded71b61f534541a5aa486e794d6d73a1d9cddc2affaea3147406ae86f23673418c7d4e6c

data/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  - push
+
+env:
+  BUNDLE_PATH: vendor/bundle
+
+jobs:
+  test_and_lint_minimum_ruby:
+    name: Tests/Lint (2.7)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+          bundler-cache: true
+      - name: "Tests"
+        run: bundle exec rake test --backtrace
+      - name: "Lint"
+        run: bundle exec rake standard
+  test_recent_ruby:
+    name: Tests (3.4)
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+      - name: "Tests"
+        run: bundle exec rake test --backtrace

data/.gitignore

@@ -0,0 +1,57 @@
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# Rubocop
+rubocop.html
+
+# bundler
+.bundle
+Gemfile.lock
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+.DS_Store
+
+tmp
+.ruby-version
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc
+
+# Rubocop report
+rubocop.html
+

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 2.7

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,136 @@
+# block_cipher_kit
+
+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:
+
+* AES-256-CBC (limited random read access, requires reading to end of source)
+* 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)
+
+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.
+
+The following rules hold true for any given Scheme:
+
+* Ciphertext output for known plaintext, randomness source and encryption key of every scheme will come out exactly the same (a scheme encrypts deterministically).
+* Plaintext output for known ciphertext and encryption key of every scheme will come out exactly the same (a scheme decrypts deterministically).
+* The scheme's output will stay exactly the same throughout the versioning of the gem, provided the underlying cipher (OpenSSL or other) is available on the host system.
+
+Schemes are versioned. We give a guarantee they are not going to change once this gem is at version `1.0.0` or higher, every scheme becomes "frozen" once it is published with the gem.
+
+## Interop
+
+Data written by the schemes is compatible with the "bare" uses of the ciphers, layouts are as follows:
+
+* AES-256-CBC - Layout is `[ IV - 16 bytes) ][ Ciphertext in 16 byte blocks, no padding ]`
+* AES-256-CFB - Layout is `[ IV - 16 bytes) ][ Ciphertext in 16 byte blocks ]`
+* AES-256-CTR - Layout is `[ nonce - 4 bytes][ IV - 8 bytes ][ Ciphertext in 16 byte blocks ]`
+* AES-256-GCM - Layout is `[ nonce - 4 bytes][ IV - 8 bytes ][ Ciphertext in 16 byte blocks ][ Validation tag - 16 bytes ]`
+* AES-256-CFB-CIV - Layout is `[ Ciphertext in 16 byte blocks ]`. The `encryption_key` must be `[ IV - 16 bytes][ key - 32 bytes]` (IV is not stored with ciphertext)
+
+You should thus be able to build either a decryptor that outputs in a format compatible with a given Scheme, or an encryptor that produces data valid for that Scheme,
+in any language that provides standard AES cipher constructions.
+
+## Which scheme to use?
+
+Please do some research as the topic is vast. GCM is quite good, I found CBC to be good for files as well. Be aware that both GCM and CTR have a limit of about 64GB of ciphertext before the block counter rolls over.
+
+## Basic streaming use
+
+Imagine you want to encrypt some data in a streaming manner with AES-256-CTR, and data is stored in files:
+
+```ruby
+File.open(plain_file_path, "rb", "rb") do |from|
+  File.open(plain_file_path + ".enc", "wb") do |into|
+    scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+    scheme.streaming_encrypt(from_plaintext_io: from, into_ciphertext_io: into)
+  end
+end
+```
+
+To decrypt the same file
+
+```ruby
+File.open(encrypted_file_path, "rb") do |from|
+  File.open(encrypted_file_path + ".plain", "wb") do |into|
+    scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+    scheme.streaming_decrypt(from_ciphertext_io: from, into_plaintext_io: into)
+  end
+end
+```
+
+Note that in both of these cases:
+
+* Only `read` will be called on the source IO (`from_ciphertext_io` and `from_plaintext_io`). They do not need to support `pos`, `seek` or `rewind`.
+* Only `write` will be called on the destination IO (`to_ciphertext_io` and `to_plaintext_io`). They do not need to support `pos`, `seek` or `rewind`.
+
+## Streaming encryption / decryption "head to tail" with blocks
+
+To use streaming encryption, writing the plaintext the data as you go:
+
+```
+File.open(plain_file_path + ".enc", "wb") do |into|
+  scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+  scheme.streaming_encrypt(into_ciphertext_io: into) do |sink|
+    sink.write("This is some very secret data")
+    sink.write("Very secret indeed")
+  end
+end
+```
+
+The `sink` will be an object that responds to `write` (it can also be used with `IO.copy_stream`).
+
+To use streaming decryption, reading the plaintext data as you go:
+
+```ruby
+File.open(encrypted_file_path, "rb") do |from|
+  scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+  scheme.streaming_encrypt(from_ciphertext_io: from) do |decrypted_chunk_of_plaintext|
+    $stdout.puts "Decrypted: #{decrypted_chunk_of_plaintext.inspect}"
+  end
+end
+```
+
+## Random access reads
+
+For random access, you can either recover a String in binary encoding:
+
+```ruby
+File.open(encrypted_file_path, "rb") do |from|
+  scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+  scheme.decrypt_range(from_ciphertext_io: from, range: 15..16) #=> "ab"
+end
+```
+
+or pass an IO to receive the decrypted data:
+
+```ruby
+File.open(encrypted_file_path, "rb") do |from|
+  scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+  scheme.streaming_decrypt_range(from_ciphertext_io: from, range: 15..16, into_plaintext_io: $stdout) #=> "ab" gets printed to STDOUT
+end
+```
+
+or a block (will be called for every meaningful chunk of decrypted data, repeatedly):
+
+```ruby
+File.open(encrypted_file_path, "rb") do |from|
+  scheme = BlockCipherKit::AES256CTRScheme.new(encryption_key)
+  scheme.streaming_decrypt_range(from_ciphertext_io: from, range: 15..) do |decrypted_chunk_of_plaintext|
+    $stderr.puts "Decrypted #{decrypted_chunk_of_plaintext.inspect}"
+  end
+end
+```
+
+For both `streaming_decrypt_range` and `decrypt_range`:
+
+* The source IO (`from_ciphertext_io`) **must** support `pos`, `size`, `seek` and `read`
+* The destination IO must only support `write`

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "standard/rake"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :format do
+  `bundle exec standardrb --fix`
+  `bundle exec magic_frozen_string_literal .`
+end
+
+task default: [:test, :standard]

data/block_cipher_kit.gemspec

@@ -0,0 +1,37 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "block_cipher_kit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "block_cipher_kit"
+  spec.version = BlockCipherKit::VERSION
+  spec.authors = ["Julik Tarkhanov", "Sebastian van Hesteren"]
+  spec.email = ["me@julik.nl"]
+  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"
+
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Do not depend on openssl explicitly, we have a warning in the code for this
+  # spec.add_dependency "openssl"
+
+  spec.add_development_dependency "minitest"
+  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"
+  # redcarpet is needed for the yard gem to enable Github Flavored Markdown
+  spec.add_development_dependency "redcarpet"
+
+  # Sord and sorbet-runtime are somewhat Ruby version dependent so wait with this
+  # until we have everything YARD-documented
+  # spec.add_development_dependency "sord"
+end

data/lib/block_cipher_kit/aes_256_cbc_scheme.rb

@@ -0,0 +1,56 @@
+require "securerandom"
+
+class BlockCipherKit::AES256CBCScheme < BlockCipherKit::BaseScheme
+  IV_LENGTH = 16
+
+  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))
+  end
+
+  def required_encryption_key_length
+    32
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    cipher = OpenSSL::Cipher.new("aes-256-cbc")
+    cipher.decrypt
+    cipher.iv = from_ciphertext_io.read(IV_LENGTH)
+    cipher.key = @key
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, destination_io: into_plaintext_io, &blk)
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    random_iv = @iv_generator.bytes(IV_LENGTH)
+    cipher = OpenSSL::Cipher.new("aes-256-cbc")
+    cipher.encrypt
+    cipher.iv = random_iv
+    cipher.key = @key
+    into_ciphertext_io.write(random_iv)
+    write_copy_stream_via_cipher(source_io: from_plaintext_io, cipher: cipher, destination_io: into_ciphertext_io, &blk)
+  end
+
+  def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
+    block_size = 16
+    n_bytes_to_decrypt = range.end - range.begin + 1
+    n_blocks_to_skip, offset_into_first_block = range.begin.divmod(block_size)
+
+    cipher = OpenSSL::Cipher.new("aes-256-cbc")
+    cipher.decrypt
+    cipher.key = @key
+
+    # We need to read the IV either from the start of the IO (the initial IV)
+    # or from the block preceding the first block we need to decrypt
+    from_ciphertext_io.seek(from_ciphertext_io.pos + (n_blocks_to_skip * block_size))
+    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)
+
+    # 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)
+  end
+end

data/lib/block_cipher_kit/aes_256_cfb_civ_scheme.rb

@@ -0,0 +1,35 @@
+require "tempfile"
+
+class BlockCipherKit::AES256CFBCIVScheme < BlockCipherKit::BaseScheme
+  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))
+  end
+
+  def required_encryption_key_length
+    48
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    cipher = OpenSSL::Cipher.new("aes-256-cfb")
+    cipher.decrypt
+    cipher.iv = @iv
+    cipher.key = @key
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, destination_io: into_plaintext_io, &blk)
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    cipher = OpenSSL::Cipher.new("aes-256-cfb")
+    cipher.encrypt
+    cipher.iv = @iv
+    cipher.key = @key
+    write_copy_stream_via_cipher(source_io: from_plaintext_io, cipher: cipher, destination_io: into_ciphertext_io, &blk)
+  end
+
+  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)
+    streaming_decrypt(from_ciphertext_io: from_ciphertext_io, into_plaintext_io: lens)
+  end
+end

data/lib/block_cipher_kit/aes_256_cfb_scheme.rb

@@ -0,0 +1,37 @@
+class BlockCipherKit::AES256CFBScheme < BlockCipherKit::BaseScheme
+  IV_LENGTH = 16
+
+  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))
+  end
+
+  def required_encryption_key_length
+    32
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    cipher = OpenSSL::Cipher.new("aes-256-cfb")
+    cipher.decrypt
+    cipher.iv = from_ciphertext_io.read(IV_LENGTH)
+    cipher.key = @key
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, destination_io: into_plaintext_io, &blk)
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    iv = @iv_generator.bytes(16)
+    cipher = OpenSSL::Cipher.new("aes-256-cfb")
+    cipher.encrypt
+    cipher.iv = iv
+    cipher.key = @key
+    into_ciphertext_io.write(iv)
+    write_copy_stream_via_cipher(source_io: from_plaintext_io, cipher: cipher, destination_io: into_ciphertext_io, &blk)
+  end
+
+  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)
+    streaming_decrypt(from_ciphertext_io: from_ciphertext_io, into_plaintext_io: lens)
+  end
+end

data/lib/block_cipher_kit/aes_256_ctr_scheme.rb

@@ -0,0 +1,87 @@
+class BlockCipherKit::AES256CTRScheme < BlockCipherKit::BaseScheme
+  NONCE_LENGTH_BYTES = 4
+  IV_LENGTH_BYTES = 8
+
+  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))
+  end
+
+  def required_encryption_key_length
+    32
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    nonce_and_iv = @iv_generator.bytes(NONCE_LENGTH_BYTES + IV_LENGTH_BYTES)
+    into_ciphertext_io.write(nonce_and_iv)
+
+    cipher = OpenSSL::Cipher.new("aes-256-ctr")
+    cipher.encrypt
+    cipher.iv = ctr_iv(nonce_and_iv, _for_block_n = 0)
+    cipher.key = @key
+    write_copy_stream_via_cipher(source_io: from_plaintext_io, cipher: cipher, destination_io: into_ciphertext_io, &blk)
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    nonce_and_iv = from_ciphertext_io.read(NONCE_LENGTH_BYTES + IV_LENGTH_BYTES)
+
+    cipher = OpenSSL::Cipher.new("aes-256-ctr")
+    cipher.decrypt
+    cipher.iv = ctr_iv(nonce_and_iv, _for_block_n = 0)
+    cipher.key = @key
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, cipher: cipher, destination_io: into_plaintext_io, &blk)
+  end
+
+  def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
+    block_size = 16
+    n_bytes_to_read = range.end - range.begin + 1
+    n_blocks_to_skip, offset_into_first_block = range.begin.divmod(block_size)
+
+    nonce_and_iv = from_ciphertext_io.read(NONCE_LENGTH_BYTES + IV_LENGTH_BYTES)
+    ciphertext_starts_at = from_ciphertext_io.pos
+
+    cipher = OpenSSL::Cipher.new("aes-256-ctr")
+    cipher.decrypt
+    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)
+
+    # 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))
+    n_blocks_to_read = (n_bytes_to_read.to_f / block_size).ceil + 1
+    read_copy_stream_via_cipher(source_io: from_ciphertext_io, destination_io: lens, cipher: cipher, read_limit: n_blocks_to_read * block_size)
+  end
+
+  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
+    # It consists of:
+    # * a nonce (which should be the same across all blocks) - 4 bytes,
+    # * a chunk of the initial IV bytes - this is used as the actual IV - 8 bytes
+    # * and the counter, encoded as a big endian uint - 4 bytes
+    #
+    # So, while the OpenSSL Cipher reports iv_len to be 16 bytes, it is lying -
+    # even if it uses the IV to split it into a nonce + iv part, 4 bytes will be...zeroed?
+    # ignored? something else?
+    # Either way: for the nonce we can consume a part of our initial IV, for the block IV
+    # we can consume the rest of the initial IV, and the last 4 bytes will be the counter.
+    # The rest of the state will be maintained by the Cipher, luckily.
+    # nonce = iv_initial.byteslice(0, 4)
+    # iv_part = iv_initial.byteslice(3, 8)
+    #
+    # Also... the counter resets once we got more than 0xFFFFFFFF blocks?
+    # It seems in its infinite wisdom the library we are using (whichever) will do
+    # whatever the system integer overflow does?..
+    # https://stackoverflow.com/questions/66790768/aes256-ctr-mode-behavior-on-counter-overflow-rollover
+    # https://crypto.stackexchange.com/a/71210
+    # https://crypto.stackexchange.com/a/71196
+    # But for the counter to overflow we would need our input to be more than 68719476720 bytes.
+    # That is just short of 64 gigabytes (!). Maybe we need a backstop for that. Or maybe we don't.
+    raise ArgumentError unless nonce_and_iv.bytesize == 12
+    nonce_and_iv.b + [for_block_n + 1].pack("N")
+  end
+end

data/lib/block_cipher_kit/aes_256_gcm_scheme.rb

@@ -0,0 +1,108 @@
+class BlockCipherKit::AES256GCMScheme < BlockCipherKit::BaseScheme
+  IV_LENGTH = 12
+
+  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))
+  end
+
+  def required_encryption_key_length
+    32
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    iv = @iv_generator.bytes(IV_LENGTH)
+    into_ciphertext_io.write(iv)
+
+    cipher = OpenSSL::Cipher.new("aes-256-gcm")
+    cipher.encrypt
+    cipher.iv = iv
+    cipher.key = @key
+    cipher.auth_data = @auth_data
+
+    write_copy_stream_via_cipher(source_io: from_plaintext_io, cipher: cipher, destination_io: into_ciphertext_io, &blk)
+
+    tag = cipher.auth_tag
+    into_ciphertext_io.write(tag)
+  end
+
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    # Read the IV
+    iv = from_ciphertext_io.read(IV_LENGTH)
+    start_at = from_ciphertext_io.pos
+
+    # Read the auth tag, which we store after the ciphertext. This is streaming
+    # decrypt, but we still assume random access is available for from_ciphertext_io.
+    # We can access the ciphertext without tag validation but then it would be the same
+    # "downgrade" to CTR as in decrypt_range.
+    tag_len = 16
+    from_ciphertext_io.seek(from_ciphertext_io.size - tag_len)
+    auth_tag_from_io_tail = from_ciphertext_io.read(tag_len)
+
+    # From the docs:
+    # When decrypting, the authenticated data must be set after key, iv and especially
+    # after the authentication tag has been set. I.e. set it only after calling #decrypt,
+    # key=, #iv= and #auth_tag= first.
+    cipher = OpenSSL::Cipher.new("aes-256-gcm")
+    cipher.decrypt
+    cipher.iv = iv
+    cipher.key = @key
+    cipher.auth_tag = auth_tag_from_io_tail
+    cipher.auth_data = @auth_data
+
+    from_ciphertext_io.seek(start_at)
+
+    # We need to be careful not to read our auth tag along with the blocks,
+    # because we appended it to the ciphertext ourselves - if the cipher considers
+    # it part of ciphertext the validation will fail
+    n_bytes_to_read_excluding_auth_tag = from_ciphertext_io.size - from_ciphertext_io.pos - tag_len
+
+    # read_copy_stream_via_cipher will also call .final performing the validation
+    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:)
+    # 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
+    # why the counter in the IV gets wound by 2 every time
+    # we move from block to block.
+    block_and_tag_size = 16 + 16
+
+    n_blocks_to_skip, offset_into_first_block = range.begin.divmod(block_and_tag_size)
+    n_bytes_to_read = range.end - range.begin + 1
+    n_blocks_to_read = ((offset_into_first_block + n_bytes_to_read) / block_and_tag_size.to_f).ceil
+
+    initial_iv_from_input = from_ciphertext_io.read(12)
+    ciphertext_starts_at = from_ciphertext_io.pos
+
+    # This is not a typo: we use GCM for encrypting the entire file and for decrypting the entire file, but to
+    # have access to random blocks we need to downgrade to CTR, since we can't validate the tag anyway
+    # This is a widely known trick, see
+    # https://stackoverflow.com/questions/49228671/aes-gcm-decryption-bypassing-authentication-in-java/49244840#49244840
+    # What we are doing here is not very secure
+    # because we lose the authencation of the cipher (this does not verify the tag). But we can't actually
+    # verify the tag without having decrypted the entire message.
+    cipher = OpenSSL::Cipher.new("aes-256-ctr")
+    cipher.decrypt
+    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
+    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
+  end
+
+  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
+    # initial counter value is 2 (as if there was a block before), see
+    # https://stackoverflow.com/a/49244840
+    ctr = (2 + (for_block_n * 2))
+    initial_iv_from_input.b + [ctr].pack("N")
+  end
+end

data/lib/block_cipher_kit/base_scheme.rb

@@ -0,0 +1,43 @@
+class BlockCipherKit::BaseScheme
+  def streaming_decrypt(from_ciphertext_io:, into_plaintext_io: nil, &blk)
+    raise "Unimplemented"
+  end
+
+  def streaming_encrypt(into_ciphertext_io:, from_plaintext_io: nil, &blk)
+    raise "Unimplemented"
+  end
+
+  def streaming_decrypt_range(from_ciphertext_io:, range:, into_plaintext_io: nil, &blk)
+    raise "Unimplemented"
+  end
+
+  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 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)
+    IO.copy_stream(source_io, cipher_io, read_limit)
+    # Some cases require us to skip authentication which gets performed in cipher.final
+    # - like decrypting a few blocks of CBC without decrypting the last block. This skips cipher
+    # authentication but is required for random access.
+    writable.write(cipher.final) if finalize_cipher
+  end
+
+  def write_copy_stream_via_cipher(cipher:, destination_io:, source_io: nil, read_limit: nil, &block_accepting_writable_io)
+    w = BlockCipherKit::CipherIO.new(destination_io, cipher)
+    if !source_io && block_accepting_writable_io && !read_limit
+      block_accepting_writable_io.call(w)
+    elsif !source_io && block_accepting_writable_io && read_limit
+      raise "write_copy_stream_via_cipher cannot enforce read_limit when writing via a block"
+    elsif source_io && !block_accepting_writable_io
+      IO.copy_stream(source_io, w, read_limit)
+    else
+      raise ArgumentError, "Either source_io: or a block accepting a writable IO must be provided"
+    end
+    destination_io.write(cipher.final)
+  end
+end