dstu_core 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2334ab3aa0124cebb58c7581ae4aeb17da063c86cc204c81c4520d2828e31f5
+  data.tar.gz: ed3fd69afa6c610c3ab0400b57df533d1884a1b7890b87f3cba4dbf3578a4d1f
+SHA512:
+  metadata.gz: 8e1f3bd238c2610b0d49f299d5491da7edcb8c44ad64ec2a1dae830909e5c731e6be51133373179da81ca370e0adbfd7296e23cb0feb4548fe6c15fbcb58886e
+  data.tar.gz: 8239f6561bb4ab5882b40d75c415cbb45dc6c607d46bb9737fa32dbfc7121a219a6f30d5497d1b3f26eae767cdbd1901f7a77d9b3eb1b1cc48fbdc1d9fac62be

data/README.md

@@ -0,0 +1,90 @@
+# 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.
+
+## Installing (from source)
+
+```sh
+gem install bundler
+bundle install
+bundle exec rake compile
+ruby -Ilib -e 'require "dstu_core"; DstuCore.self_test'
+```
+
+`magnus`/`rb_sys` need a matching Ruby + C toolchain to build the native extension — a real
+`gcc`/`clang` install, not just Ruby itself. On Windows specifically, install the **DevKit**
+variant of Ruby (bundles a matching MSYS2/mingw-w64-ucrt toolchain — a plain Ruby install has no
+compiler wired up at all):
+
+```
+winget install --id RubyInstallerTeam.RubyWithDevKit.3.3 --exact
+```
+
+`rb-sys`'s `bindgen` step also needs a `libclang` that matches Ruby's own mingw-ucrt target — a
+generic pre-existing Windows LLVM install parses Ruby's headers incorrectly. Install the matching
+MSYS2 package and point `LIBCLANG_PATH` at it:
+
+```
+pacman -S --needed mingw-w64-ucrt-x86_64-clang   # via `ridk` or an MSYS2 shell
+export LIBCLANG_PATH="/path/to/msys64/ucrt64/bin"
+```
+
+`bundle exec rake compile` builds the Rust extension and copies it into `lib/dstu_core/`.
+`DstuCore.self_test` re-runs `dstu_core::selftest::run()` (`docs/TASKS.md` T-161) against the
+exact compiled build and raises `DstuCore::Error` if anything official-vector-level is wrong — the
+first thing to run after any build to confirm it actually works, not just compiled.
+
+This crate is its own Cargo workspace, split across `Cargo.toml` (the workspace root) and
+`ext/dstu_core_rb/Cargo.toml` (the actual crate) — separate from the repo root
+(`docs/DECISIONS.md` D-119) — build/test it from inside this directory, not from the repo root.
+A **source** install (the steps above) needs this repo's own `crates/dstu-core` alongside it, since
+`ext/dstu_core_rb/Cargo.toml` depends on it by relative path — it cannot install standalone outside
+this repo. `rake native gem` instead builds a precompiled, platform-tagged gem that ships the
+compiled extension directly and installs anywhere (see `docs/DECISIONS.md` D-136).
+
+## Usage
+
+Every method/class below lives directly on the `DstuCore` module (no further nesting). Every
+`String` this binding touches is binary (`ASCII-8BIT`) — `.b`/`force_encoding("BINARY")` a UTF-8
+string before comparing it against a decrypted result. See `examples/` for complete, runnable
+scripts, and `spec/` for the full correctness/rejection/misuse suite each one is verified against
+(D-64/D-65).
+
+```ruby
+require "dstu_core"
+
+key = DstuCore.secretbox_keygen
+sealed = DstuCore.secretbox_seal(key, "a message worth protecting")
+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_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_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`. |
+| `crypto_stream` | `stream_keygen`, `stream_encrypt`, `stream_decrypt` | Strumok-256 keystream — **unauthenticated**, `stream_decrypt` never fails on tampered input. `examples/misc.rb`. |
+| `randombytes` | `randombytes_buf` | CSPRNG-backed random bytes. `examples/misc.rb`. |
+| — | `self_test`, `DstuCore::Error` | Runtime KAT self-check (T-161); the one exception class every crypto-operation failure raises (`ArgumentError` covers caller-input mistakes like a wrong-length key instead). |
+
+## Testing
+
+```sh
+bundle exec rubocop
+bundle exec rspec
+```
+
+`cargo build -p uacrypt --release` (from the repo root) first if you want
+`spec/secretstream_spec.rb`'s live `uacrypt` CLI interop test to actually run instead of being
+`skip`ped. `cargo xtask ruby` (from the repo root) runs this whole sequence, including that build
+step and `rake compile`, in one command.

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rb_sys/extensiontask"
+require "rspec/core/rake_task"
+
+GEMSPEC = Gem::Specification.load("dstu_core.gemspec")
+
+RbSys::ExtensionTask.new("dstu_core_rb", GEMSPEC) do |ext|
+  ext.lib_dir = "lib/dstu_core"
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task build: :compile
+task default: %i[compile spec]

data/lib/dstu_core/secretstream.rb

@@ -0,0 +1,188 @@
+# 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
+# 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.
+#
+# **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
+# function (`RString::to_bytes`, D-134). A caller passing UTF-8 text must `.b`/
+# `force_encoding("BINARY")` before comparing against the decrypted result, or the comparison sees
+# 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.
+  SECRETSTREAM_CHUNK_BYTES = 8 * 1024
+  SECRETSTREAM_AUTH_TAG_BYTES = 16
+
+  # Write-only wrapper: buffers input and pushes each full 8 KiB chunk to `out` as it fills, hiding
+  # the header/tag/framing bookkeeping entirely.
+  #
+  #   File.open("out.bin", "wb") do |f|
+  #     DstuCore::SecretStreamWriter.open(key, f) { |w| w.write("a whole file, incrementally") }
+  #   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
+    end
+
+    # Block form: yields a writer, then closes it - **only on the success path**. The D-118
+    # pitfall this deliberately avoids: Ruby's own "always runs, even on error" cleanup idiom
+    # (`ensure`, the shape `File.open`/`Zlib::GzipWriter.wrap` both use) would finalize (emit the
+    # `Final` chunk) even when the block raised partway through, producing a stream that looks
+    # complete but silently drops data - violates D-65's "no partial output treated as valid on
+    # failure." If a truncated-but-decryptable prefix is genuinely wanted, call `close` explicitly
+    # inside a `rescue` clause instead.
+    def self.open(key, out)
+      writer = new(key, out)
+      yield writer
+      writer.close
+      writer
+    end
+
+    def closed?
+      @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.
+    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..) || +""
+      end
+      data.bytesize
+    end
+
+    alias << write
+
+    # Flushes any buffered bytes as the stream's Final chunk. Idempotent - safe to call more than
+    # once, matching normal Ruby `IO#close` semantics.
+    def close
+      return if @closed
+
+      push_chunk(SECRETSTREAM_TAG_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)
+    end
+  end
+
+  # Read-only, chunk-iterating wrapper: reads and decrypts one chunk from `inp` at a time.
+  # `include Enumerable` gives `to_a`/`map`/etc. for free; `read_all` joins every plaintext chunk
+  # into one `String`, bounded only by available memory (the same caveat `crypto_secretbox`
+  # already carries). Raises `DstuCore::Error` on authentication failure or truncation - a
+  # dropped/tampered/reordered chunk, or a stream that ends before a Final chunk, both fail closed
+  # rather than yielding wrong plaintext.
+  #
+  #   File.open("out.bin", "rb") do |f|
+  #     plaintext = DstuCore::SecretStreamReader.open(key, f, &:read_all)
+  #   end
+  class SecretStreamReader
+    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
+    end
+
+    def self.open(key, inp)
+      reader = new(key, inp)
+      yield reader
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      yield next_chunk until @done
+    end
+
+    def read_all
+      each.to_a.join
+    end
+
+    # No-op - present for symmetry with SecretStreamWriter and Ruby's own IO-like `close` idiom.
+    def close; end
+
+    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)
+
+        @done = true
+      end
+      plaintext
+    end
+
+    def read_exact(size, what)
+      pieces = []
+      remaining = size
+      while remaining.positive?
+        piece = @inp.read(remaining)
+        break unless piece
+
+        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
+
+      data
+    end
+  end
+end

data/lib/dstu_core/version.rb

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

data/lib/dstu_core.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "dstu_core/version"
+require "dstu_core/dstu_core_rb"
+require_relative "dstu_core/secretstream"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: dstu_core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- dstu-core contributors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-13 00:00:00.000000000 Z
+dependencies: []
+description: Ruby bindings for dstu-core (Ukrainian DSTU cryptographic standards)
+  - provisional, not yet published to RubyGems.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/dstu_core.rb
+- lib/dstu_core/3.1/dstu_core_rb.so
+- lib/dstu_core/3.2/dstu_core_rb.so
+- lib/dstu_core/3.3/dstu_core_rb.so
+- lib/dstu_core/3.4/dstu_core_rb.so
+- lib/dstu_core/secretstream.rb
+- lib/dstu_core/version.rb
+homepage: https://github.com/user137/uacrypt
+licenses:
+- MIT
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for dstu-core (Ukrainian DSTU cryptographic standards)
+test_files: []