dstu_core 0.1.0-aarch64-linux → 0.5.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04231940a4a2760de82c62093446a0099ebc582476c77f27e1de9f1bc724d28d'
-  data.tar.gz: a4c132c59df4aea211bc245999ba8d45ea4005c9271daf39ad2491df1a58ded7
+  metadata.gz: d25697754c4bacdf34799f7f30030d32452ebb98dad7b51be4936ce50fd49b75
+  data.tar.gz: d0d537156e83fb2e88a7fe01667de9a3ba35c54f1c70149f9b5f8c59b97b787d
 SHA512:
-  metadata.gz: ea595bac5cca8e8339b6c3ad4a0f09b59121fba7947e428f55caf1eef2950cefe7fa8dc6b78d3e596b066f17298c974c84f539eec7585cb9917a1a277d02fbfe
-  data.tar.gz: 4c862e95bb724478ae656f5decb35ee4a5f67456de9e80f055bff2c6989690fb13ed0185871a55be6f4f71595d9933704166b473a353ad194f89dbcafd19e7f4
+  metadata.gz: 7048b087b76cfbba8fc78c64f3e1680125671d59ba840fa6caafddaba1ba970a8f194a7ac11366bf485935ccc7e058d98663871d1ffe531792f583724bbfe340
+  data.tar.gz: 38d44e88e422e45e008b2281d16b7523b2cd0a4446e3c6c303ccf5ca32e69b5dda4fe47063a7bf2653a71a2ae0d5d7dd957975105b940b0906338e0bcfceb8d8

data/README.md

@@ -1,11 +1,21 @@
 # dstu-core (Ruby bindings)
 
-**Provisional — not published to RubyGems, not independently audited.** See the root project's
-`docs/SECURITY.md` and `docs/DECISIONS.md` for the full threat model and per-construction status.
-This binding wraps the full `dstu_core::crypto_*` surface (`docs/bindings-strategy.md` T-160) —
-install from source as shown below.
+**Pre-1.0. Not independently audited.** See the root project's `docs/SECURITY.md` and
+`docs/DECISIONS.md` for the full threat model and per-construction status. This binding wraps the
+full `dstu_core::crypto_*` surface (`docs/bindings-strategy.md` T-160).
 
-## Installing (from source)
+## Installing
+
+```sh
+gem install dstu_core
+```
+
+```ruby
+require "dstu_core"
+DstuCore.self_test
+```
+
+## Building from source (contributors)
 
 ```sh
 gem install bundler
@@ -64,12 +74,13 @@ raise unless DstuCore.secretbox_open(key, sealed) == "a message worth protecting
 | Module | Methods/classes | Notes |
 |---|---|---|
 | `crypto_secretbox` | `secretbox_keygen`, `secretbox_seal`, `secretbox_open` | Single-message authenticated encryption. `examples/secretbox.rb`. |
-| `crypto_box` | `box_keygen`, `box_public_key`, `box_seal`, `box_open` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `box_seal`/`box_open` are not memory-bounded — the whole message is held in memory. `examples/box.rb`. |
-| `crypto_box512` | `box512_keygen`, `box512_public_key`, `box512_seal`, `box512_open` | `l(p)=512`/E512/1 sibling of `crypto_box` (T-193/T-204). `examples/box512.rb`. |
+| `crypto_box` | `box_keygen`, `box_public_key`, `box_seal`, `box_open`, `BoxWriter`, `BoxReader` | Public-key encryption (hybrid via KDF over `hazmat::dstu9041`, `l(p)=256`, D-169). `box_seal`/`box_open` hold the whole message in memory; `BoxWriter`/`BoxReader` write and read the same bytes (format v3) chunk by chunk, as `uacrypt box-seal`/`box-open` do. `examples/box.rb`. |
+| `crypto_box384` | `box384_keygen`, `box384_public_key`, `box384_seal`, `box384_open`, `Box384Writer`, `Box384Reader` | `l(p)=384`/E384/1 sibling of `crypto_box` (T-297). `examples/box384.rb`. |
+| `crypto_box512` | `box512_keygen`, `box512_public_key`, `box512_seal`, `box512_open`, `Box512Writer`, `Box512Reader` | `l(p)=512`/E512/1 sibling of `crypto_box` (T-193/T-204). `examples/box512.rb`. |
 | `crypto_secretstream` | `secretstream_keygen`, `SecretStreamPushState`, `SecretStreamPullState`, `SecretStreamWriter`, `SecretStreamReader` | Chunked streaming AEAD. `SecretStreamWriter`/`Reader` (modeled on stdlib's own `Zlib::GzipWriter`/`GzipReader`) wire format matches `uacrypt encrypt`/`decrypt` exactly (D-118). `examples/secretstream_file.rb`. |
 | `crypto_sign` | `sign_keygen`, `sign_verifying_key`, `sign_message`, `sign_verify` | DSTU 4145 `m=163` digital signatures, deterministic nonce (no RNG dependency). `examples/sign.rb`. |
 | `crypto_sign257` | `sign257_keygen`, `sign257_verifying_key`, `sign257_message`, `sign257_verify` | `m=257` sibling of `crypto_sign` (T-199/T-204) — the curve real Diia-issued qualified signatures use. `examples/sign257.rb`. |
-| `crypto_pwhash` | `pwhash_hash_password`, `pwhash_verify_password`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `examples/password_hashing.rb`. |
+| `crypto_pwhash` | `pwhash_hash_password`, `pwhash_verify_password`, `pwhash_derive_key`, `PWHASH_INTERACTIVE`/`PWHASH_MODERATE`/`PWHASH_SENSITIVE`, `PassphraseWriter`, `PassphraseReader` | Argon2id (the one deliberately non-DSTU component, D-49/D-50). `pwhash_derive_key` equals libsodium's `crypto_pwhash`. `PassphraseWriter`/`PassphraseReader` write and read the files `uacrypt encrypt --passphrase` makes (D-219/D-240); each runs Argon2id at 256 MiB once. `examples/password_hashing.rb`. |
 | `crypto_auth` | `auth_keygen`, `auth`, `auth_verify` | Keyed message authentication (Kupyna-KMAC). `examples/misc.rb`. |
 | `crypto_kdf` | `kdf_keygen`, `kdf_derive_subkey` | Deterministic subkey derivation. `examples/misc.rb`. |
 | `crypto_generichash` | `kupyna256`, `kupyna512`, `Kupyna256Hasher`, `Kupyna512Hasher` | One-shot and streaming Kupyna hashing. `examples/misc.rb`. |

data/lib/dstu_core/secretstream.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
 # `crypto_secretstream` idiomatic wrapper (docs/DECISIONS.md D-118, docs/bindings-strategy.md
-# T-160 step 3) - hides chunk/tag/header bookkeeping behind `write`/`each`, built in pure Ruby on
-# top of the low-level SecretStreamPushState/SecretStreamPullState the compiled extension already
-# exposes (step 2), rather than new Rust glue. Modeled on stdlib's own
+# T-160 step 3) - hides chunk/tag/header bookkeeping behind `write`/`each`. The framing itself
+# (record layout, length rules, Final, trailing data) is dstu-core's stream-file codec, exposed as
+# SecretStreamFileEncryptor/SecretStreamFileDecryptor (T-284); this file does only I/O. Modeled on
+# stdlib's own
 # Zlib::GzipWriter/Zlib::GzipReader - the same "wraps an IO, transforms chunks transparently"
 # shape, the closest Ruby-native precedent for this problem (matching Python's file-like object,
 # Node's stream.Transform).
 #
 # **Wire format matches `uacrypt encrypt`/`decrypt` exactly**
 # (crates/uacrypt/src/lib.rs's `run_secretstream_encrypt`/`run_secretstream_decrypt`, D-68):
-# `header (32 bytes)` followed by one record per chunk, `tag_byte (1) || chunk_len_u32_le (4) ||
-# ciphertext (chunk_len) || auth_tag (16)`, chunks capped at 8 KiB (matching
-# `SECRETSTREAM_CHUNK_BYTES`, not an independent choice) - a file `SecretStreamWriter` writes is
-# decryptable by `uacrypt decrypt` and vice versa.
+# `version (1) || header (32 bytes)` followed by one record per chunk, `tag_byte (1) ||
+# chunk_len_u32_le (4) || ciphertext (chunk_len) || auth_tag (16)`. Every record but the Final one is
+# exactly 8 KiB (`SECRETSTREAM_CHUNK_BYTES`, part of the format since D-208, not an independent
+# choice) - a file `SecretStreamWriter` writes is decryptable by `uacrypt decrypt` and vice versa.
+# The shared vectors in crates/dstu-core/tests/vectors/secretstream-file/ pin this.
 #
 # **Every `String` this wrapper touches is binary (`ASCII-8BIT`/`BINARY`)**, both what it writes
 # to `out`/`inp` and what `#read_all`/`#each` yield - matching every underlying `crypto_*` wrapper
@@ -22,10 +24,12 @@
 # differing encodings and fails even when the bytes match (`"привіт".b == "привіт"` is `false` in
 # Ruby) - this is a caller-side encoding-compare gotcha, not a bug in this wrapper.
 module DstuCore
-  # Matches crates/uacrypt/src/lib.rs's SECRETSTREAM_CHUNK_BYTES exactly - required for
-  # wire-format interop with `uacrypt encrypt`/`decrypt`, not an independent choice.
+  # dstu-core's crypto_secretstream::CHUNK_BYTES and wire constants (D-208); the codec enforces
+  # them, these stay as public constants.
   SECRETSTREAM_CHUNK_BYTES = 8 * 1024
   SECRETSTREAM_AUTH_TAG_BYTES = 16
+  # Matches dstu-core's crypto_secretstream::FORMAT_VERSION (D-208); the shared vectors pin it.
+  SECRETSTREAM_FORMAT_VERSION = 2
 
   # Write-only wrapper: buffers input and pushes each full 8 KiB chunk to `out` as it fills, hiding
   # the header/tag/framing bookkeeping entirely.
@@ -35,12 +39,7 @@ module DstuCore
   #   end
   class SecretStreamWriter
     def initialize(key, out)
-      @out = out
-      @out.binmode if @out.respond_to?(:binmode)
-      @push = SecretStreamPushState.new(key)
-      @out.write(@push.header)
-      @buf = +""
-      @closed = false
+      start(SecretStreamFileEncryptor.new(key), out)
     end
 
     # Block form: yields a writer, then closes it - **only on the success path**. The D-118
@@ -61,18 +60,21 @@ module DstuCore
       @closed
     end
 
-    # Buffers `data`, pushing any now-complete 8 KiB chunks immediately. The trailing partial (or
-    # exactly-8-KiB) chunk is always held back until `close`, since only `close` knows no more
-    # data is coming - the same one-chunk-ahead reasoning `uacrypt encrypt` itself uses to tag the
-    # true last chunk `Final`, not an extra empty one after it.
+    # Buffers `data`, sealing every full 8 KiB chunk that is certain not to be the last one. The
+    # trailing partial (or exactly-8-KiB) chunk is held back until `close`, since only `close`
+    # knows no more data is coming - an exact multiple of 8 KiB must end in a full Final record
+    # (D-208). Full chunks are cut from `data` by offset, so one large write costs linear time
+    # (T-276).
     def write(data)
       raise IOError, "closed stream" if @closed
 
-      @buf << data.b
-      while @buf.bytesize > SECRETSTREAM_CHUNK_BYTES
-        push_chunk(SECRETSTREAM_TAG_MESSAGE, @buf.byteslice(0, SECRETSTREAM_CHUNK_BYTES))
-        @buf = @buf.byteslice(SECRETSTREAM_CHUNK_BYTES..) || +""
+      data = data.b
+      pos = top_up_buffer(data)
+      while data.bytesize - pos > SECRETSTREAM_CHUNK_BYTES
+        @out.write(@enc.seal_chunk(data.byteslice(pos, SECRETSTREAM_CHUNK_BYTES)))
+        pos += SECRETSTREAM_CHUNK_BYTES
       end
+      @buf << data.byteslice(pos..)
       data.bytesize
     end
 
@@ -83,19 +85,36 @@ module DstuCore
     def close
       return if @closed
 
-      push_chunk(SECRETSTREAM_TAG_FINAL, @buf)
+      @out.write(@enc.seal_final(@buf))
       @buf = +""
       @closed = true
     end
 
     private
 
-    def push_chunk(tag, data)
-      ciphertext, auth_tag = @push.push(tag, data)
-      @out.write([tag].pack("C"))
-      @out.write([data.bytesize].pack("V"))
-      @out.write(ciphertext)
-      @out.write(auth_tag)
+    def start(enc, out)
+      @out = out
+      @out.binmode if @out.respond_to?(:binmode)
+      @enc = enc
+      @buf = +""
+      @closed = false
+      @out.write(@enc.prefix)
+    end
+
+    # Adds `data` to the held-back chunk if it all fits; otherwise tops that chunk up to a full one
+    # and seals it, since more data follows. Returns how many bytes of `data` it consumed.
+    def top_up_buffer(data)
+      return 0 if @buf.empty?
+
+      if @buf.bytesize + data.bytesize <= SECRETSTREAM_CHUNK_BYTES
+        @buf << data
+        return data.bytesize
+      end
+      taken = SECRETSTREAM_CHUNK_BYTES - @buf.bytesize
+      @buf << data.byteslice(0, taken)
+      @out.write(@enc.seal_chunk(@buf))
+      @buf = +""
+      taken
     end
   end
 
@@ -113,11 +132,8 @@ module DstuCore
     include Enumerable
 
     def initialize(key, inp)
-      @inp = inp
-      @inp.binmode if @inp.respond_to?(:binmode)
-      header = read_exact(32, "header")
-      @pull = SecretStreamPullState.new(key, header)
-      @done = false
+      bind(inp)
+      start(SecretStreamFileDecryptor.new(key))
     end
 
     def self.open(key, inp)
@@ -128,7 +144,10 @@ module DstuCore
     def each
       return enum_for(:each) unless block_given?
 
-      yield next_chunk until @done
+      until @done
+        plaintext = step
+        yield plaintext unless plaintext.empty?
+      end
     end
 
     def read_all
@@ -140,34 +159,41 @@ module DstuCore
 
     private
 
-    def next_chunk
-      tag_byte = read_exact(1, "chunk tag").unpack1("C")
-      chunk_len = read_exact(4, "chunk length").unpack1("V")
-      # `chunk_len` is untrusted wire input, read before any tag verification - reject an
-      # oversized declared length before acting on it (`read_exact` would otherwise try to
-      # accumulate up to `chunk_len` bytes from `inp`, which for a socket/pipe could mean
-      # gigabytes before ever failing). Matches `uacrypt decrypt`'s own
-      # `CliError::SecretstreamChunkTooLarge` bound (`crates/uacrypt/src/lib.rs`).
-      if chunk_len > SECRETSTREAM_CHUNK_BYTES
-        raise DstuCore::Error,
-              "secretstream chunk too large: declared #{chunk_len} bytes, max #{SECRETSTREAM_CHUNK_BYTES}"
-      end
-      ciphertext = read_exact(chunk_len, "chunk ciphertext")
-      auth_tag = read_exact(SECRETSTREAM_AUTH_TAG_BYTES, "chunk auth tag")
-      tag, plaintext = @pull.pull(tag_byte, ciphertext, auth_tag)
-      if tag == SECRETSTREAM_TAG_FINAL
-        # Matches `uacrypt decrypt`'s own `CliError::SecretstreamTrailingData` check - reject
-        # bytes remaining after `Final` rather than silently ignoring them. Checked before
-        # `plaintext` is returned, so a trailing-data stream never yields this last chunk either
-        # via `each` or `read_all`.
-        raise DstuCore::Error, "trailing data after the secretstream's Final chunk" if @inp.read(1)
+    def bind(inp)
+      @inp = inp
+      @inp.binmode if @inp.respond_to?(:binmode)
+    end
+
+    def start(dec)
+      @dec = dec
+      @done = false
+      # The version byte and header, read now so a wrong version fails at construction.
+      2.times { step }
+    end
+
+    # The bytes in front of the stream file (a box prefix, a passphrase-file header); a shorter
+    # input cannot be opened at all.
+    def read_prefix(size, what)
+      prefix = read_up_to(size)
+      raise Error, "input too short to contain a #{what}" if prefix.bytesize < size
 
+      prefix
+    end
+
+    # Feeds the codec one `next_len` read: the plaintext that read released (possibly empty), or
+    # at end of input the Final chunk's (after which the stream is done).
+    def step
+      want = @dec.next_len
+      data = read_up_to(want)
+      if data.bytesize < want
         @done = true
+        return @dec.finish
       end
-      plaintext
+      @dec.feed(data)
     end
 
-    def read_exact(size, what)
+    # Reads until `size` bytes arrived or `inp` ended; a short result means end of input.
+    def read_up_to(size)
       pieces = []
       remaining = size
       while remaining.positive?
@@ -177,12 +203,71 @@ module DstuCore
         pieces << piece
         remaining -= piece.bytesize
       end
-      data = pieces.join
-      if data.bytesize != size
-        raise DstuCore::Error, "truncated secretstream: expected #{size} bytes for #{what}, got #{data.bytesize}"
-      end
+      pieces.join.b
+    end
+  end
+
+  # crypto_box sealed to `public_key` as a stream (format v3, T-265/T-269): the same bytes
+  # `box_seal` returns, written chunk by chunk; `box_open`/BoxReader read them.
+  class BoxWriter < SecretStreamWriter
+    def initialize(public_key, out) # rubocop:disable Lint/MissingSuper
+      start(SecretStreamFileEncryptor.box_seal(public_key), out)
+    end
+  end
+
+  # Reads a crypto_box stream (or a `box_seal` blob) with bounded memory.
+  class BoxReader < SecretStreamReader
+    def initialize(secret_key, inp) # rubocop:disable Lint/MissingSuper
+      bind(inp)
+      start(SecretStreamFileDecryptor.box_open(secret_key, read_prefix(BOX_OPEN_STREAM_PREFIX_BYTES, "sealed message")))
+    end
+  end
+
+  # crypto_box384 counterpart of BoxWriter.
+  class Box384Writer < SecretStreamWriter
+    def initialize(public_key, out) # rubocop:disable Lint/MissingSuper
+      start(SecretStreamFileEncryptor.box384_seal(public_key), out)
+    end
+  end
+
+  # crypto_box384 counterpart of BoxReader.
+  class Box384Reader < SecretStreamReader
+    def initialize(secret_key, inp) # rubocop:disable Lint/MissingSuper
+      bind(inp)
+      start(SecretStreamFileDecryptor.box384_open(secret_key, read_prefix(BOX384_OPEN_STREAM_PREFIX_BYTES, "sealed message")))
+    end
+  end
+
+  # crypto_box512 counterpart of BoxWriter.
+  class Box512Writer < SecretStreamWriter
+    def initialize(public_key, out) # rubocop:disable Lint/MissingSuper
+      start(SecretStreamFileEncryptor.box512_seal(public_key), out)
+    end
+  end
+
+  # crypto_box512 counterpart of BoxReader.
+  class Box512Reader < SecretStreamReader
+    def initialize(secret_key, inp) # rubocop:disable Lint/MissingSuper
+      bind(inp)
+      start(SecretStreamFileDecryptor.box512_open(secret_key, read_prefix(BOX512_OPEN_STREAM_PREFIX_BYTES, "sealed message")))
+    end
+  end
+
+  # A passphrase file (D-219/D-240) - the bytes `uacrypt encrypt --passphrase` writes. `new` runs
+  # Argon2id (256 MiB, t=3, about a second) before writing anything.
+  class PassphraseWriter < SecretStreamWriter
+    def initialize(passphrase, out) # rubocop:disable Lint/MissingSuper
+      start(SecretStreamFileEncryptor.passphrase_seal(passphrase), out)
+    end
+  end
 
-      data
+  # Reads a passphrase file. The header is checked before Argon2 runs; a wrong passphrase raises
+  # DstuCore::Error at the first record.
+  class PassphraseReader < SecretStreamReader
+    def initialize(passphrase, inp) # rubocop:disable Lint/MissingSuper
+      bind(inp)
+      header = read_prefix(PASSPHRASE_FILE_HEADER_BYTES, "passphrase file header")
+      start(SecretStreamFileDecryptor.passphrase_open(header, passphrase))
     end
   end
 end

data/lib/dstu_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DstuCore
-  VERSION = "0.1.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: dstu_core
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.5.0
 platform: aarch64-linux
 authors:
 - dstu-core contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies: []
 description: Ruby bindings for dstu-core (Ukrainian DSTU cryptographic standards)
-  - provisional, not yet published to RubyGems.
+  - not independently audited.
 email: 
 executables: []
 extensions: []