omq-blake3zmq 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ad881032a9ee2f62f9109d025e7eed78115dd86b2360f40a1edfab3f66a9fba
+  data.tar.gz: a4632fbf7ee8346a84042064d917d46e6af3573779ee44a126a234be9895e782
+SHA512:
+  metadata.gz: 56c18fb8e7f70d70a7ba1abfaa3e23a2874f4cf56b26c49ad35117634c23a6cd77093be4b06fb00f39371dc1ffa8cf51d9ccd80c839fd64ac23f68530ce5525e
+  data.tar.gz: 4cd8f8f1b27fcfcb1e6c209ded268c064f370d77d6dff5748d4eee324d5b5ed092b8876dc418b86c64e6cb17f87fdd74c07566dba95bb129bca89bbbbb690fc2

data/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026, Patrik Wenger
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# BLAKE3ZMQ
+
+> [!WARNING]
+> This is experimental and the gem is not maintained by cryptographers.
+> It has not been independently audited. For production, use CurveZMQ instead.
+
+BLAKE3ZMQ is a security mechanism for [OMQ](https://github.com/paddor/omq)
+that replaces [CurveZMQ](https://rfc.zeromq.org/spec/26/) with modern
+primitives:
+
+* **X25519** key exchange (perfect forward secrecy)
+* **ChaCha20-BLAKE3** AEAD (32-byte authentication tags)
+* **BLAKE3** transcript hash and key derivation
+
+It implements the `Protocol::ZMTP::Mechanism::Blake3` class for use with
+[protocol-zmtp](https://github.com/paddor/protocol-zmtp).
+
+See [RFC.md](RFC.md) for the full protocol specification.
+
+## Features
+
+* 4-message handshake (HELLO, WELCOME, INITIATE, READY)
+* Transcript hash binding across all handshake messages; all post-handshake frames (including commands) AEAD-encrypted, unlike CurveZMQ
+* Deterministic nonces (no per-message randomness needed)
+* 32 bytes overhead per message (no wire nonce, no command wrapper)
+* Stateless server until client authentication (cookie mechanism)
+* Mutual authentication or server-only (anonymous client) modes
+* Works out of the box (native C X25519 + Rust AEAD included)
+* Crypto-backend-agnostic (can substitute your own primitives)
+
+## Installation
+
+```ruby
+gem "omq-blake3zmq"
+```
+
+Batteries included: ships with [x25519](https://github.com/RubyCrypto/x25519)
+(native C) and [chacha20blake3](https://github.com/paddor/chacha20blake3)
+(Rust native).
+
+## Usage
+
+```ruby
+require "omq"
+require "omq/blake3zmq"
+
+Crypto = OMQ::Blake3ZMQ::Crypto
+
+# Generate or load keys
+server_sk = Crypto::PrivateKey.generate
+server_pk = server_sk.public_key.to_s
+
+client_sk = Crypto::PrivateKey.generate
+client_pk = client_sk.public_key.to_s
+
+# Server socket
+server = OMQ::REP.new
+server.mechanism = Protocol::ZMTP::Mechanism::Blake3.server(
+  public_key: server_pk,
+  secret_key: server_sk.to_s,
+  authenticator: ->(peer) { peer.public_key.to_s == client_pk },
+)
+server.bind("tcp://127.0.0.1:9999")
+
+# Client socket (keys optional — omit for anonymous/ephemeral identity)
+client = OMQ::REQ.new
+client.mechanism = Protocol::ZMTP::Mechanism::Blake3.client(
+  server_key: server_pk,
+  public_key: client_pk,
+  secret_key: client_sk.to_s,
+)
+client.connect("tcp://127.0.0.1:9999")
+```
+
+## Benchmarks
+
+CurveZMQ (RbNaCl/libsodium) vs BLAKE3ZMQ (Rust native ChaCha20-BLAKE3 + C native X25519).
+
+Ruby 4.0.2, x86_64 Linux.
+
+### Handshake latency (100 rounds)
+
+| | Time | Per handshake |
+|---|---:|---:|
+| CurveZMQ/RbNaCl | 226 ms | 2.26 ms |
+| BLAKE3ZMQ | 120 ms | 1.20 ms |
+| **Speedup** | | **1.9x** |
+
+### Message encrypt + decrypt throughput (20,000 messages)
+
+| Size | CurveZMQ/RbNaCl | BLAKE3ZMQ | Speedup |
+|---:|---:|---:|---:|
+| 64 B | 8.4 MB/s | 16.1 MB/s | 1.9x |
+| 256 B | 38.0 MB/s | 51.4 MB/s | 1.4x |
+| 1 KB | 88.1 MB/s | 137.5 MB/s | 1.6x |
+| 4 KB | 196.3 MB/s | 265.5 MB/s | 1.4x |
+| 16 KB | 289.1 MB/s | 387.1 MB/s | 1.3x |
+| 64 KB | 413.3 MB/s | 452.4 MB/s | 1.1x |
+| 128 KB | 426.4 MB/s | 527.0 MB/s | 1.2x |
+| 256 KB | 428.7 MB/s | 538.0 MB/s | 1.3x |
+
+### Full round-trip (handshake + 1,000 messages over UNIXSocket)
+
+| Size | CurveZMQ/RbNaCl | BLAKE3ZMQ | Speedup |
+|---:|---:|---:|---:|
+| 64 B | 69.4 ms (0.9 MB/s) | 50.8 ms (1.3 MB/s) | 1.4x |
+| 1 KB | 54.6 ms (18.7 MB/s) | 62.6 ms (16.3 MB/s) | 0.9x |
+| 64 KB | 281.7 ms (232.6 MB/s) | 242.2 ms (270.6 MB/s) | 1.2x |
+
+Run benchmarks yourself:
+
+```
+OMQ_DEV=1 bundle exec ruby bench/throughput.rb
+```
+
+## Per-message overhead
+
+| | BLAKE3ZMQ | CurveZMQ |
+|---|---:|---:|
+| Tag size | 32 bytes | 16 bytes |
+| Counter on wire | 0 bytes | 8 bytes |
+| Command wrapper | none | 17 bytes |
+| **Total** | **32 bytes** | **41 bytes** |
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+```
+
+## License
+
+[ISC](LICENSE)

data/lib/omq/blake3zmq/crypto.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "chacha20blake3"
+require "digest/blake3"
+require "x25519"
+require "securerandom"
+
+module OMQ
+  module Blake3ZMQ
+
+    # Default crypto backend: x25519 (native C) + chacha20blake3 (Rust native).
+    module Crypto
+      CryptoError = ChaCha20Blake3::DecryptionError
+      TAG_SIZE    = ChaCha20Blake3::TAG_SIZE
+      Cipher      = ChaCha20Blake3::Cipher
+      Stream      = ChaCha20Blake3::Stream
+
+
+      # X25519 public key wrapper.
+      class PublicKey
+        attr_reader :key
+
+
+        # @param bytes [String] 32-byte public key
+        def initialize(bytes)
+          bytes = bytes.to_s if bytes.respond_to?(:to_bytes)
+          @key  = X25519::MontgomeryU.new(bytes.b)
+        end
+
+
+        # Returns the raw 32-byte public key.
+        #
+        # @return [String] 32-byte binary string
+        def to_s
+          @key.to_bytes
+        end
+      end
+
+
+      # X25519 private key wrapper with key generation and Diffie-Hellman.
+      class PrivateKey
+        # Generates a new random private key.
+        #
+        # @return [PrivateKey]
+        def self.generate
+          new(X25519::Scalar.generate.to_bytes)
+        end
+
+
+        # @param bytes [String] 32-byte secret key
+        def initialize(bytes)
+          @key = X25519::Scalar.new(bytes.b)
+        end
+
+
+        # Returns the corresponding public key.
+        #
+        # @return [PublicKey]
+        def public_key
+          PublicKey.new(@key.public_key.to_bytes)
+        end
+
+
+        # Returns the raw 32-byte secret key.
+        #
+        # @return [String] 32-byte binary string
+        def to_s
+          @key.to_bytes
+        end
+
+
+        # Performs X25519 Diffie-Hellman with a peer's public key.
+        #
+        # @param peer_public_key [PublicKey] peer's public key
+        # @return [String] 32-byte shared secret
+        def diffie_hellman(peer_public_key)
+          pk = case peer_public_key
+               when PublicKey
+                 peer_public_key.key
+               else
+                 X25519::MontgomeryU.new(peer_public_key.to_s.b)
+               end
+
+          @key.diffie_hellman(pk).to_bytes
+        end
+      end
+
+
+      # BLAKE3 hashing and key derivation functions.
+      module Hash
+        module_function
+
+        # Computes a 32-byte BLAKE3 digest.
+        #
+        # @param input [String] data to hash
+        # @return [String] 32-byte binary digest
+        def digest(input)
+          Digest::Blake3.digest(input)
+        end
+
+
+        # Derives a key using BLAKE3 key derivation.
+        #
+        # @param context [String] domain separation context string
+        # @param material [String] input keying material
+        # @param size [Integer] output length in bytes (default 32)
+        # @return [String] derived key bytes
+        def derive_key(context, material, size: 32)
+          ChaCha20Blake3.derive_key(context, material, length: size)
+        end
+      end
+
+
+      module_function
+
+
+      # Generates cryptographically secure random bytes.
+      #
+      # @param n [Integer] number of bytes to generate
+      # @return [String] random binary string
+      def random_bytes(n)
+        SecureRandom.random_bytes(n)
+      end
+    end
+  end
+end

data/lib/omq/blake3zmq/mechanism.rb

@@ -0,0 +1,687 @@
+# frozen_string_literal: true
+
+module Protocol
+  module ZMTP
+    module Mechanism
+      # BLAKE3ZMQ security mechanism.
+      #
+      # Provides X25519 key exchange, ChaCha20-BLAKE3 AEAD encryption, and
+      # BLAKE3 transcript hashing for ZMTP 3.1 connections.
+      #
+      # Crypto-backend-agnostic: pass any module that provides the required
+      # interface via the +crypto:+ parameter.
+      #
+      # The crypto backend must provide:
+      #   backend::PrivateKey.generate / .new(bytes)
+      #     #public_key -> PublicKey, #to_s -> 32 bytes, #diffie_hellman(pub) -> 32 bytes
+      #   backend::PublicKey.new(bytes)
+      #     #to_s -> 32 bytes
+      #   backend::Cipher.new(key)
+      #     #encrypt(nonce, plaintext, aad:) -> ciphertext+tag
+      #     #decrypt(nonce, ciphertext+tag, aad:) -> plaintext
+      #   backend::Stream.new(key, nonce)
+      #     #encrypt(plaintext, aad:) -> ciphertext+tag
+      #     #decrypt(ciphertext+tag, aad:) -> plaintext
+      #   backend::Hash.digest(input) -> 32 bytes
+      #   backend::Hash.derive_key(context, material) -> 32 bytes
+      #   backend::Hash.derive_key(context, material, size: n) -> n bytes
+      #   backend.random_bytes(n) -> n bytes
+      #   backend::CryptoError (exception class)
+      #   backend::TAG_SIZE = 32
+      #
+      class Blake3
+        MECHANISM_NAME = "BLAKE3"
+        PROTOCOL_ID    = "BLAKE3ZMQ-1.0"
+        TAG_SIZE       = 32
+        KEY_SIZE       = 32
+        NONCE_SIZE     = 24
+
+
+        # Creates a BLAKE3 server mechanism.
+        #
+        # @param public_key [String] 32 bytes
+        # @param secret_key [String] 32 bytes
+        # @param crypto [Module] crypto backend
+        # @param authenticator [#call, nil] called with a {PeerInfo} during
+        #   authentication; must return truthy to allow the connection.
+        #   When nil, any client with a valid vouch is accepted.
+        # @return [Blake3]
+        def self.server(public_key:, secret_key:, crypto: OMQ::Blake3ZMQ::Crypto, authenticator: nil)
+          new(public_key:, secret_key:, crypto:, as_server: true, authenticator:)
+        end
+
+
+        # Creates a BLAKE3 client mechanism.
+        #
+        # @param server_key [String] 32 bytes (server permanent public key)
+        # @param crypto [Module] crypto backend
+        # @param public_key [String, nil] 32 bytes (or nil for auto-generated ephemeral identity)
+        # @param secret_key [String, nil] 32 bytes (or nil for auto-generated ephemeral identity)
+        # @return [Blake3]
+        def self.client(server_key:, crypto: OMQ::Blake3ZMQ::Crypto, public_key: nil, secret_key: nil)
+          new(public_key:, secret_key:, server_key:, crypto:, as_server: false)
+        end
+
+
+        # Initializes a new BLAKE3 mechanism instance.
+        #
+        # @param public_key [String, nil] 32-byte permanent public key
+        # @param secret_key [String, nil] 32-byte permanent secret key
+        # @param server_key [String, nil] 32-byte server permanent public key (client only)
+        # @param crypto [Module] crypto backend module
+        # @param as_server [Boolean] whether this instance acts as a server
+        # @param authenticator [#call, nil] optional authenticator for server mode
+        def initialize(public_key: nil, secret_key: nil, server_key: nil, crypto: OMQ::Blake3ZMQ::Crypto, as_server: false, authenticator: nil)
+          @crypto        = crypto
+          @as_server     = as_server
+          @authenticator = authenticator
+
+          if as_server
+            validate_key!(public_key, "public_key")
+            validate_key!(secret_key, "secret_key")
+
+            @permanent_public = crypto::PublicKey.new(public_key.b)
+            @permanent_secret = crypto::PrivateKey.new(secret_key.b)
+            @cookie_key       = crypto.random_bytes(KEY_SIZE)
+          else
+            validate_key!(server_key, "server_key")
+
+            @server_public = crypto::PublicKey.new(server_key.b)
+
+            if public_key && secret_key
+              validate_key!(public_key, "public_key")
+              validate_key!(secret_key, "secret_key")
+
+              @permanent_public = crypto::PublicKey.new(public_key.b)
+              @permanent_secret = crypto::PrivateKey.new(secret_key.b)
+            else
+              @permanent_secret = crypto::PrivateKey.generate
+              @permanent_public = @permanent_secret.public_key
+            end
+          end
+
+          @send_stream = nil
+          @recv_stream = nil
+        end
+
+
+        # Resets stream state when duplicating the mechanism.
+        #
+        # @param source [Blake3] the original mechanism being duplicated
+        def initialize_dup(source)
+          super
+          @send_stream = nil
+          @recv_stream = nil
+        end
+
+
+        # Whether this mechanism encrypts traffic.
+        #
+        # @return [Boolean] always true
+        def encrypted?
+          true
+        end
+
+
+        # Returns a maintenance task that rotates the server cookie key.
+        #
+        # @return [Hash, nil] a hash with +:interval+ (seconds) and +:task+ (Proc), or nil for clients
+        def maintenance
+          return unless @as_server
+
+          {
+            interval: 60,
+            task:     -> { @cookie_key = @crypto.random_bytes(KEY_SIZE) }
+          }.freeze
+        end
+
+
+        # Performs the BLAKE3ZMQ handshake over the given IO.
+        #
+        # Delegates to the client or server handshake depending on role.
+        #
+        # @param io [#write, #read_exactly] transport IO
+        # @param as_server [Boolean] ignored (role is set at construction)
+        # @param socket_type [String] ZMTP socket type name
+        # @param identity [String] socket identity
+        # @param metadata [Hash{String => String}, nil] extra READY properties
+        # @return [Hash] peer metadata including +:peer_socket_type+, +:peer_identity+, +:peer_properties+
+        def handshake!(io, as_server:, socket_type:, identity:, metadata: nil)
+          if @as_server
+            server_handshake!(io, socket_type:, identity:, metadata:)
+          else
+            client_handshake!(io, socket_type:, identity:, metadata:)
+          end
+        end
+
+
+        # Encrypts a ZMTP frame body for transmission.
+        #
+        # The AEAD AAD per RFC §10.3 is `flags_byte || length_bytes` —
+        # every wire byte that is not itself encrypted. This binds the
+        # full wire envelope (including the LONG bit and the size
+        # field) so any single-bit modification fails verification.
+        #
+        # @param body [String] plaintext frame body
+        # @param more [Boolean] whether the MORE flag is set
+        # @param command [Boolean] whether this is a command frame
+        # @return [String] wire-encoded encrypted frame (header + ciphertext)
+        def encrypt(body, more: false, command: false)
+          flags  = 0
+          flags |= 0x01 if more
+          flags |= 0x04 if command
+
+          # ChaCha20-BLAKE3 ciphertext is plaintext + 32-byte tag.
+          frame_size = body.bytesize + TAG_SIZE
+
+          if frame_size > 255
+            wire_flags = (flags | 0x02).chr
+            length_bytes = [frame_size].pack("Q>")
+          else
+            wire_flags = flags.chr
+            length_bytes = frame_size.chr
+          end
+          aad = wire_flags + length_bytes
+
+          ct = @send_stream.encrypt(body, aad: aad)
+
+          wire = String.new(encoding: Encoding::BINARY, capacity: aad.bytesize + frame_size)
+          wire << aad << ct
+        end
+
+
+        # Decrypts an encrypted ZMTP frame.
+        #
+        # The AAD is reconstructed from the exact wire bytes the codec
+        # parsed: the flags byte (with LONG bit if the frame was long)
+        # and the length encoding that followed it.
+        #
+        # @param frame [Codec::Frame] encrypted frame with body, more?, and command? attributes
+        # @return [Codec::Frame] decrypted frame
+        # @raise [Error] if decryption fails
+        def decrypt(frame)
+          flags  = 0
+          flags |= 0x01 if frame.more?
+          flags |= 0x04 if frame.command?
+
+          frame_size = frame.body.bytesize
+          if frame_size > 255
+            wire_flags = (flags | 0x02).chr
+            length_bytes = [frame_size].pack("Q>")
+          else
+            wire_flags = flags.chr
+            length_bytes = frame_size.chr
+          end
+          aad = wire_flags + length_bytes
+
+          begin
+            pt = @recv_stream.decrypt(frame.body, aad: aad)
+          rescue @crypto::CryptoError
+            raise Error, "decryption failed"
+          end
+
+          Codec::Frame.new(pt, more: frame.more?, command: frame.command?)
+        end
+
+
+        private
+
+
+        # ----------------------------------------------------------------
+        # Client-side handshake
+        # ----------------------------------------------------------------
+
+        def client_handshake!(io, socket_type:, identity:, metadata: nil)
+          # Generate ephemeral keypair
+          cn_secret = @crypto::PrivateKey.generate
+          cn_public = cn_secret.public_key
+
+          # Exchange greetings
+          our_greeting = Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: false)
+          io.write(our_greeting)
+          io.flush
+          peer_greeting_bytes = io.read_exactly(Codec::Greeting::SIZE)
+          peer_greeting = Codec::Greeting.decode(peer_greeting_bytes)
+
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise Error, "expected #{MECHANISM_NAME} mechanism, got #{peer_greeting[:mechanism]}"
+          end
+
+
+          # h0 = H("BLAKE3ZMQ-1.0" || client_greeting || server_greeting)
+          h = hash(PROTOCOL_ID + our_greeting + peer_greeting_bytes)
+
+          # --- HELLO ---
+          dh1         = cn_secret.diffie_hellman(@server_public)
+          validate_dh!(dh1, "dh1")
+          hello_key   = kdf("#{PROTOCOL_ID} HELLO key", dh1)
+          hello_nonce = kdf24("#{PROTOCOL_ID} HELLO nonce", cn_public.to_s)
+          hello_box   = @crypto::Cipher.new(hello_key).encrypt(hello_nonce, "\x00" * 64, aad: "HELLO")
+
+          hello = "".b
+          hello << "\x05HELLO"
+          hello << "\x01\x00"           # version 1.0
+          hello << cn_public.to_s       # 32 bytes
+          hello << ("\x00" * 96)        # padding (HELLO 232 ≥ WELCOME 224, anti-amplification)
+          hello << hello_box            # 64 + 32(tag) = 96 bytes
+
+          hello_wire = Codec::Frame.new(hello, command: true).to_wire
+          io.write(hello_wire)
+          io.flush
+
+          # h1 = H(h0 || HELLO_wire_bytes)
+          h = hash(h + hello_wire)
+
+          # --- Read WELCOME ---
+          welcome_frame = Codec::Frame.read_from(io)
+          raise Error, "expected command frame" unless welcome_frame.command?
+          welcome_cmd = Codec::Command.from_body(welcome_frame.body)
+          raise Error, "expected WELCOME, got #{welcome_cmd.name}" unless welcome_cmd.name == "WELCOME"
+
+          welcome_data = welcome_cmd.data
+          welcome_box_size = KEY_SIZE + 152 + TAG_SIZE  # S'(32) + cookie(152) + tag(32) = 216
+          raise Error, "WELCOME wrong size" unless welcome_data.bytesize == welcome_box_size
+
+          welcome_key   = kdf("#{PROTOCOL_ID} WELCOME key", dh1)
+          welcome_nonce = kdf24("#{PROTOCOL_ID} WELCOME nonce", h)
+          begin
+            welcome_plain = @crypto::Cipher.new(welcome_key).decrypt(welcome_nonce, welcome_data, aad: "WELCOME")
+          rescue @crypto::CryptoError
+            raise Error, "WELCOME decryption failed"
+          end
+
+          sn_public = @crypto::PublicKey.new(welcome_plain.byteslice(0, KEY_SIZE))
+          cookie    = welcome_plain.byteslice(KEY_SIZE..)
+
+          # h2 = H(h1 || WELCOME_wire_bytes)
+          h = hash(h + welcome_frame.to_wire)
+
+          # --- INITIATE ---
+          dh2 = cn_secret.diffie_hellman(sn_public)
+          validate_dh!(dh2, "dh2")
+
+          initiate_key   = kdf("#{PROTOCOL_ID} INITIATE key", dh2 + h)
+          initiate_nonce = kdf24("#{PROTOCOL_ID} INITIATE nonce", dh2 + h)
+
+          props = { "Socket-Type" => socket_type, "Identity" => identity }
+          props.merge!(metadata) if metadata && !metadata.empty?
+          metadata_bytes = Codec::Command.encode_properties(props)
+
+          dh3 = @permanent_secret.diffie_hellman(sn_public)
+          validate_dh!(dh3, "dh3")
+
+          vouch_key   = kdf("#{PROTOCOL_ID} VOUCH key", dh3)
+          vouch_nonce = kdf24("#{PROTOCOL_ID} VOUCH nonce", dh3)
+          vouch_box   = @crypto::Cipher.new(vouch_key).encrypt(
+            vouch_nonce, cn_public.to_s + @server_public.to_s, aad: "VOUCH"
+          )
+
+          initiate_plaintext = @permanent_public.to_s + vouch_box + metadata_bytes
+
+          initiate_box = @crypto::Cipher.new(initiate_key).encrypt(
+            initiate_nonce, initiate_plaintext, aad: "INITIATE"
+          )
+
+          initiate = "".b
+          initiate << "\x08INITIATE"
+          initiate << cookie
+          initiate << initiate_box
+
+          initiate_wire = Codec::Frame.new(initiate, command: true).to_wire
+          io.write(initiate_wire)
+          io.flush
+
+          # h3 = H(h2 || INITIATE_wire_bytes)
+          h = hash(h + initiate_wire)
+
+          # --- Read READY ---
+          ready_frame = Codec::Frame.read_from(io)
+          raise Error, "expected command frame" unless ready_frame.command?
+          ready_cmd = Codec::Command.from_body(ready_frame.body)
+
+          if ready_cmd.name == "ERROR"
+            reason = ready_cmd.data.bytesize > 0 ? ready_cmd.data.byteslice(1..) : ""
+            raise Error, "server rejected: #{reason}"
+          end
+          raise Error, "expected READY, got #{ready_cmd.name}" unless ready_cmd.name == "READY"
+
+          ready_key   = kdf("#{PROTOCOL_ID} READY key", dh2 + h)
+          ready_nonce = kdf24("#{PROTOCOL_ID} READY nonce", dh2 + h)
+          begin
+            ready_plain = @crypto::Cipher.new(ready_key).decrypt(ready_nonce, ready_cmd.data, aad: "READY")
+          rescue @crypto::CryptoError
+            raise Error, "READY decryption failed"
+          end
+
+          peer_props       = Codec::Command.decode_properties(ready_plain)
+          peer_socket_type = peer_props["Socket-Type"]
+          peer_identity    = peer_props["Identity"] || ""
+
+          # h4 = H(h3 || READY_wire_bytes)
+          h = hash(h + ready_frame.to_wire)
+
+          # Derive session keys
+          derive_session_keys!(h, dh2, as_client: true)
+
+          {
+            peer_socket_type:,
+            peer_identity:,
+            peer_properties: peer_props,
+            peer_major:      peer_greeting[:major],
+            peer_minor:      peer_greeting[:minor],
+          }
+        end
+
+
+        # ----------------------------------------------------------------
+        # Server-side handshake
+        # ----------------------------------------------------------------
+
+        def server_handshake!(io, socket_type:, identity:, metadata: nil)
+          # Exchange greetings
+          our_greeting = Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: true)
+          io.write(our_greeting)
+          io.flush
+          peer_greeting_bytes = io.read_exactly(Codec::Greeting::SIZE)
+          peer_greeting = Codec::Greeting.decode(peer_greeting_bytes)
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise Error, "expected #{MECHANISM_NAME} mechanism, got #{peer_greeting[:mechanism]}"
+          end
+
+
+          # h0 = H("BLAKE3ZMQ-1.0" || client_greeting || server_greeting)
+          # Note: peer is the client here
+          h = hash(PROTOCOL_ID + peer_greeting_bytes + our_greeting)
+
+          # --- Read HELLO ---
+          hello_frame = Codec::Frame.read_from(io)
+          raise Error, "expected command frame" unless hello_frame.command?
+          hello_cmd = Codec::Command.from_body(hello_frame.body)
+          raise Error, "expected HELLO, got #{hello_cmd.name}" unless hello_cmd.name == "HELLO"
+
+          hdata = hello_cmd.data
+          raise Error, "HELLO wrong size (#{hdata.bytesize})" unless hdata.bytesize == 226
+
+          # version(2) + C'(32) + padding(96) + hello_box(96)
+          cn_public_bytes = hdata.byteslice(2, KEY_SIZE)
+          hello_box_data  = hdata.byteslice(130, 96)
+
+          cn_public = @crypto::PublicKey.new(cn_public_bytes)
+          dh1       = @permanent_secret.diffie_hellman(cn_public)
+          validate_dh!(dh1, "dh1")
+
+          hello_key   = kdf("#{PROTOCOL_ID} HELLO key", dh1)
+          hello_nonce = kdf24("#{PROTOCOL_ID} HELLO nonce", cn_public_bytes)
+          begin
+            @crypto::Cipher.new(hello_key).decrypt(hello_nonce, hello_box_data, aad: "HELLO")
+          rescue @crypto::CryptoError
+            raise Error, "HELLO decryption failed"
+          end
+
+
+          # h1 = H(h0 || HELLO_wire_bytes)
+          h = hash(h + hello_frame.to_wire)
+
+          # --- WELCOME ---
+          sn_secret = @crypto::PrivateKey.generate
+          sn_public = sn_secret.public_key
+
+          # Cookie carries C' || s' || h1. Putting h2 in the cookie
+          # would be Catch-22 — h2 = H(h1 || welcome_wire) and
+          # welcome_wire embeds the cookie itself. By carrying h1
+          # instead, the server can reconstruct welcome_wire on
+          # INITIATE (chacha20-blake3 with fixed key+nonce+plaintext
+          # is deterministic) and recompute h2 = H(h1 || reconstructed)
+          # without holding any per-connection state across WELCOME.
+          cookie_nonce = @crypto.random_bytes(NONCE_SIZE)
+          cookie_key   = kdf("#{PROTOCOL_ID} cookie", @cookie_key)
+          cookie_box   = @crypto::Cipher.new(cookie_key).encrypt(
+            cookie_nonce, cn_public.to_s + sn_secret.to_s + h, aad: "COOKIE"
+          )
+          cookie = cookie_nonce + cookie_box  # 24 + 96 + 32(tag) = 152 bytes
+
+          # Welcome box: encrypt S' || cookie
+          welcome_key   = kdf("#{PROTOCOL_ID} WELCOME key", dh1)
+          welcome_nonce = kdf24("#{PROTOCOL_ID} WELCOME nonce", h)
+          welcome_box   = @crypto::Cipher.new(welcome_key).encrypt(
+            welcome_nonce, sn_public.to_s + cookie, aad: "WELCOME"
+          )
+
+          welcome = "".b
+          welcome << "\x07WELCOME"
+          welcome << welcome_box
+
+          welcome_wire = Codec::Frame.new(welcome, command: true).to_wire
+          io.write(welcome_wire)
+          io.flush
+
+          # h2 = H(h1 || WELCOME_wire_bytes)
+          h = hash(h + welcome_wire)
+
+          # Server is stateless here — discard sn_secret.
+          # In practice we keep it for the test/simple path;
+          # a high-performance server would rely solely on the cookie.
+
+          # --- Read INITIATE ---
+          init_frame = Codec::Frame.read_from(io)
+          raise Error, "expected command frame" unless init_frame.command?
+          init_cmd = Codec::Command.from_body(init_frame.body)
+          raise Error, "expected INITIATE, got #{init_cmd.name}" unless init_cmd.name == "INITIATE"
+
+          idata = init_cmd.data
+          raise Error, "INITIATE too short" if idata.bytesize < 152 + TAG_SIZE
+
+          # Decrypt cookie to recover C' || s' || h1
+          recv_cookie       = idata.byteslice(0, 152)
+          recv_cookie_nonce = recv_cookie.byteslice(0, NONCE_SIZE)
+          recv_cookie_box   = recv_cookie.byteslice(NONCE_SIZE..)
+
+          begin
+            cookie_plain = @crypto::Cipher.new(cookie_key).decrypt(
+              recv_cookie_nonce, recv_cookie_box, aad: "COOKIE"
+            )
+          rescue @crypto::CryptoError
+            raise Error, "INITIATE cookie verification failed"
+          end
+
+          raise Error, "cookie plaintext wrong size" unless cookie_plain.bytesize == 96
+          cn_public = @crypto::PublicKey.new(cookie_plain.byteslice(0, KEY_SIZE))
+          sn_secret = @crypto::PrivateKey.new(cookie_plain.byteslice(KEY_SIZE, KEY_SIZE))
+          recovered_h1 = cookie_plain.byteslice(2 * KEY_SIZE, 32)
+
+          # Recompute h2 from the cookie's h1 + a deterministic
+          # reconstruction of welcome_wire. chacha20-blake3 with the
+          # same (key, nonce, plaintext, aad) yields the same
+          # ciphertext+tag, so we get back the exact bytes we sent.
+          recovered_dh1 = @permanent_secret.diffie_hellman(cn_public)
+          validate_dh!(recovered_dh1, "dh1 (cookie path)")
+          recovered_welcome_key   = kdf("#{PROTOCOL_ID} WELCOME key", recovered_dh1)
+          recovered_welcome_nonce = kdf24("#{PROTOCOL_ID} WELCOME nonce", recovered_h1)
+          sn_public_bytes         = sn_secret.public_key.to_s
+          recovered_welcome_box   = @crypto::Cipher.new(recovered_welcome_key).encrypt(
+            recovered_welcome_nonce,
+            sn_public_bytes + recv_cookie,
+            aad: "WELCOME"
+          )
+          recovered_welcome = "".b
+          recovered_welcome << "\x07WELCOME" << recovered_welcome_box
+          recovered_welcome_wire = Codec::Frame.new(recovered_welcome, command: true).to_wire
+          h_recovered = hash(recovered_h1 + recovered_welcome_wire)
+          # Whether we trust our retained `h` or the recovered one
+          # depends on whether the implementation actually went stateless.
+          # Either should match; assert for safety in the test/simple
+          # path, then proceed with `h` either way. Truly stateless
+          # implementations would replace `h` with `h_recovered` here.
+          h = h_recovered
+
+          dh2 = sn_secret.diffie_hellman(cn_public)
+          validate_dh!(dh2, "dh2")
+
+          initiate_key   = kdf("#{PROTOCOL_ID} INITIATE key", dh2 + h)
+          initiate_nonce = kdf24("#{PROTOCOL_ID} INITIATE nonce", dh2 + h)
+
+          initiate_ciphertext = idata.byteslice(152..)
+          begin
+            initiate_plain = @crypto::Cipher.new(initiate_key).decrypt(
+              initiate_nonce, initiate_ciphertext, aad: "INITIATE"
+            )
+          rescue @crypto::CryptoError
+            raise Error, "INITIATE decryption failed"
+          end
+
+
+          # Always parse C(32) + vouch_box(96) + metadata
+          raise Error, "INITIATE plaintext too short" if initiate_plain.bytesize < KEY_SIZE + 96
+
+          client_permanent = @crypto::PublicKey.new(initiate_plain.byteslice(0, KEY_SIZE))
+          vouch_box        = initiate_plain.byteslice(KEY_SIZE, 96)
+          metadata_bytes   = initiate_plain.byteslice(KEY_SIZE + 96..) || "".b
+
+          # Verify vouch
+          dh3 = sn_secret.diffie_hellman(client_permanent)
+          validate_dh!(dh3, "dh3")
+          vouch_key   = kdf("#{PROTOCOL_ID} VOUCH key", dh3)
+          vouch_nonce = kdf24("#{PROTOCOL_ID} VOUCH nonce", dh3)
+          begin
+            vouch_plain = @crypto::Cipher.new(vouch_key).decrypt(vouch_nonce, vouch_box, aad: "VOUCH")
+          rescue @crypto::CryptoError
+            raise Error, "INITIATE vouch verification failed"
+          end
+
+          raise Error, "vouch wrong size" unless vouch_plain.bytesize == 64
+          vouch_cn     = vouch_plain.byteslice(0, KEY_SIZE)
+          vouch_server = vouch_plain.byteslice(KEY_SIZE, KEY_SIZE)
+
+          unless vouch_cn == cn_public.to_s
+            raise Error, "vouch client transient key mismatch"
+          end
+          unless vouch_server == @permanent_public.to_s
+            raise Error, "vouch server key mismatch"
+          end
+
+          if @authenticator
+            # Authenticator runs against the long-term public key; the
+            # identity (a runtime metadata field) is parsed later from
+            # initiate_plain. Pass an empty identity, matching the
+            # CURVE mechanism's authenticator-side convention.
+            peer = PeerInfo.new(public_key: client_permanent, identity: "")
+            unless @authenticator.call(peer)
+              send_error(io, "client key not authorized")
+              raise Error, "client key not authorized"
+            end
+          end
+
+
+          # h3 = H(h2 || INITIATE_wire_bytes)
+          h = hash(h + init_frame.to_wire)
+
+          # --- READY ---
+          ready_props = { "Socket-Type" => socket_type, "Identity" => identity }
+          ready_props.merge!(metadata) if metadata && !metadata.empty?
+          ready_metadata = Codec::Command.encode_properties(ready_props)
+
+          ready_key   = kdf("#{PROTOCOL_ID} READY key", dh2 + h)
+          ready_nonce = kdf24("#{PROTOCOL_ID} READY nonce", dh2 + h)
+          ready_box   = @crypto::Cipher.new(ready_key).encrypt(ready_nonce, ready_metadata, aad: "READY")
+
+          ready = "".b
+          ready << "\x05READY"
+          ready << ready_box
+
+          ready_wire = Codec::Frame.new(ready, command: true).to_wire
+          io.write(ready_wire)
+          io.flush
+
+          # h4 = H(h3 || READY_wire_bytes)
+          h = hash(h + ready_wire)
+
+          props = Codec::Command.decode_properties(metadata_bytes)
+
+          derive_session_keys!(h, dh2, as_client: false)
+
+          {
+            peer_socket_type: props["Socket-Type"],
+            peer_identity:    props["Identity"] || "",
+            peer_properties:  props,
+            peer_major:       peer_greeting[:major],
+            peer_minor:       peer_greeting[:minor],
+          }
+        end
+
+
+        # ----------------------------------------------------------------
+        # Session key derivation
+        # ----------------------------------------------------------------
+
+        def derive_session_keys!(h4, dh2, as_client:)
+          ikm = h4 + dh2
+
+          c2s_key   = kdf("#{PROTOCOL_ID} client->server key", ikm)
+          c2s_nonce = kdf24("#{PROTOCOL_ID} client->server nonce", ikm)
+          s2c_key   = kdf("#{PROTOCOL_ID} server->client key", ikm)
+          s2c_nonce = kdf24("#{PROTOCOL_ID} server->client nonce", ikm)
+
+          if as_client
+            @send_stream = @crypto::Stream.new(c2s_key, c2s_nonce)
+            @recv_stream = @crypto::Stream.new(s2c_key, s2c_nonce)
+          else
+            @send_stream = @crypto::Stream.new(s2c_key, s2c_nonce)
+            @recv_stream = @crypto::Stream.new(c2s_key, c2s_nonce)
+          end
+        end
+
+
+        # ----------------------------------------------------------------
+        # Crypto helpers
+        # ----------------------------------------------------------------
+
+        def hash(input)
+          @crypto::Hash.digest(input)
+        end
+
+
+        def kdf(context, material)
+          @crypto::Hash.derive_key(context, material)
+        end
+
+
+        def kdf24(context, material)
+          @crypto::Hash.derive_key(context, material, size: NONCE_SIZE)
+        end
+
+
+        def send_error(io, reason)
+          error_body = "".b
+          error_body << "\x05ERROR"
+          error_body << reason.bytesize.chr << reason.b
+          io.write(Codec::Frame.new(error_body, command: true).to_wire)
+          io.flush
+        rescue IOError
+          # connection may already be broken
+        end
+
+
+        def validate_key!(key, name)
+          if key.nil?
+            raise ArgumentError, "#{name} is required"
+          end
+
+          unless key.b.bytesize == KEY_SIZE
+            raise ArgumentError, "#{name} must be 32 bytes (got #{key.b.bytesize})"
+          end
+        end
+
+
+        ZERO_DH = ("\x00" * KEY_SIZE).b.freeze
+
+
+        def validate_dh!(shared_secret, label)
+          if shared_secret == ZERO_DH
+            raise Error, "#{label} produced all-zero output (low-order point)"
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/omq/blake3zmq/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OMQ
+  # BLAKE3-based encryption mechanism for ZMTP connections.
+  module Blake3ZMQ
+    VERSION = "0.3.0"
+  end
+end

data/lib/omq/blake3zmq.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# BLAKE3ZMQ security mechanism for OMQ.
+#
+# Usage:
+#   require "omq/blake3zmq"
+
+require "protocol/zmtp"
+
+require_relative "blake3zmq/version"
+require_relative "blake3zmq/crypto"
+require_relative "blake3zmq/mechanism"

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: omq-blake3zmq
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Patrik Wenger
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: protocol-zmtp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: blake3-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: chacha20blake3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: x25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: BLAKE3ZMQ security mechanism (X25519 + ChaCha20-BLAKE3 AEAD) for the
+  OMQ pure-Ruby ZeroMQ library.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omq/blake3zmq.rb
+- lib/omq/blake3zmq/crypto.rb
+- lib/omq/blake3zmq/mechanism.rb
+- lib/omq/blake3zmq/version.rb
+homepage: https://github.com/paddor/omq-blake3zmq
+licenses:
+- ISC
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: BLAKE3ZMQ security mechanism for OMQ
+test_files: []