omq-blake3zmq 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ad881032a9ee2f62f9109d025e7eed78115dd86b2360f40a1edfab3f66a9fba
-  data.tar.gz: a4632fbf7ee8346a84042064d917d46e6af3573779ee44a126a234be9895e782
+  metadata.gz: f303db5348da7fbd1c223fc9159414f530a10db03de06a6b51ce0708731262c0
+  data.tar.gz: 697ef532c927f8c4e1f0d380e5a023c50004ba1e995b91b4152ead7be46eabc3
 SHA512:
-  metadata.gz: 56c18fb8e7f70d70a7ba1abfaa3e23a2874f4cf56b26c49ad35117634c23a6cd77093be4b06fb00f39371dc1ffa8cf51d9ccd80c839fd64ac23f68530ce5525e
-  data.tar.gz: 4cd8f8f1b27fcfcb1e6c209ded268c064f370d77d6dff5748d4eee324d5b5ed092b8876dc418b86c64e6cb17f87fdd74c07566dba95bb129bca89bbbbb690fc2
+  metadata.gz: 477e5dca0140c73bc6bb312a0bd3c053462a989a035539b54ebd54ac933e5113916755de2869499532d4d2b52c9890a67415ae2fc80dd06c254ff3f58a0d9edc
+  data.tar.gz: 3fcc887fb323cd0bd8cfd0cdc5bd59519e6627a3874a5fa63ca4a430021531d5149b02619c72f8c17b903c0b792310570d559c71e8c2dbacf000692bd7dcec3d

data/README.md

@@ -62,7 +62,7 @@ server.mechanism = Protocol::ZMTP::Mechanism::Blake3.server(
 )
 server.bind("tcp://127.0.0.1:9999")
 
-# Client socket (keys optional — omit for anonymous/ephemeral identity)
+# Client socket (keys optional; omit for anonymous/ephemeral identity)
 client = OMQ::REQ.new
 client.mechanism = Protocol::ZMTP::Mechanism::Blake3.client(
   server_key: server_pk,
@@ -72,6 +72,75 @@ client.mechanism = Protocol::ZMTP::Mechanism::Blake3.client(
 client.connect("tcp://127.0.0.1:9999")
 ```
 
+## Wire format
+
+### Handshake
+
+Four ZMTP command frames over plain TCP:
+
+```
+Client                              Server
+  |                                    |
+  |-- HELLO (C', hello_box) ---------> |  232 bytes
+  |                                    |
+  | <-- WELCOME (welcome_box) -------- |  224 bytes
+  |                                    |
+  |-- INITIATE (cookie, init_box) ---> |  variable
+  |                                    |
+  | <-- READY (ready_box) ------------ |  variable
+  |                                    |
+  |====== encrypted data phase ========|
+```
+
+HELLO carries the client's ephemeral public key `C'` and a box proving
+knowledge of the server's permanent public key `S`. WELCOME returns the
+server's ephemeral key `S'` inside a stateless cookie. INITIATE sends
+back the cookie plus the client's permanent key `C` and a vouch binding
+`C'` to `C`. READY confirms the session.
+
+### Data phase
+
+Every post-handshake frame (data and command) is AEAD-encrypted:
+
+```
++-----------+----------------+------------------+-----------+
+| flags     | length         | ciphertext       | tag       |
+| (1 byte)  | (1 or 8 bytes) | (N bytes)        | (32 bytes)|
++-----------+----------------+------------------+-----------+
+```
+
+The `flags` byte and `length` bytes are authenticated as AAD. No counter
+is sent on the wire; both peers derive per-message nonces from a
+synchronized monotonic counter and a session-unique nonce prefix.
+
+Unlike CurveZMQ, SUBSCRIBE/CANCEL/JOIN/LEAVE/PING/PONG/ERROR are all
+AEAD-encrypted. CurveZMQ sends these in plaintext, leaking subscription
+topics, group memberships, and heartbeat content.
+
+## Constants
+
+| Constant | Value |
+|---|---|
+| Key size | 32 bytes |
+| Nonce size | 24 bytes |
+| Tag size | 32 bytes |
+| Cookie size | 152 bytes (24 nonce + 96 payload + 32 tag) |
+| Mechanism name | `BLAKE3` (6 octets, null-padded to 20) |
+| Protocol ID | `BLAKE3ZMQ-1.0` |
+| HELLO body | 232 bytes |
+| WELCOME body | 224 bytes |
+
+## 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** |
+
+BLAKE3ZMQ has 9 bytes less overhead per message despite a larger tag.
+
 ## Benchmarks
 
 CurveZMQ (RbNaCl/libsodium) vs BLAKE3ZMQ (Rust native ChaCha20-BLAKE3 + C native X25519).
@@ -113,15 +182,6 @@ 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
 
 ```

data/lib/omq/blake3zmq/crypto.rb

@@ -13,7 +13,7 @@ module OMQ
       CryptoError = ChaCha20Blake3::DecryptionError
       TAG_SIZE    = ChaCha20Blake3::TAG_SIZE
       Cipher      = ChaCha20Blake3::Cipher
-      Stream      = ChaCha20Blake3::Stream
+      Session     = ChaCha20Blake3::Session
 
 
       # X25519 public key wrapper.

data/lib/omq/blake3zmq/mechanism.rb

@@ -19,7 +19,7 @@ module Protocol
       #   backend::Cipher.new(key)
       #     #encrypt(nonce, plaintext, aad:) -> ciphertext+tag
       #     #decrypt(nonce, ciphertext+tag, aad:) -> plaintext
-      #   backend::Stream.new(key, nonce)
+      #   backend::Session.new(enc_key, auth_key, nonce)
       #     #encrypt(plaintext, aad:) -> ciphertext+tag
       #     #decrypt(ciphertext+tag, aad:) -> plaintext
       #   backend::Hash.digest(input) -> 32 bytes
@@ -100,8 +100,8 @@ module Protocol
             end
           end
 
-          @send_stream = nil
-          @recv_stream = nil
+          @send_session = nil
+          @recv_session = nil
         end
 
 
@@ -110,8 +110,8 @@ module Protocol
         # @param source [Blake3] the original mechanism being duplicated
         def initialize_dup(source)
           super
-          @send_stream = nil
-          @recv_stream = nil
+          @send_session = nil
+          @recv_session = nil
         end
 
 
@@ -183,7 +183,7 @@ module Protocol
           end
           aad = wire_flags + length_bytes
 
-          ct = @send_stream.encrypt(body, aad: aad)
+          ct = @send_session.encrypt(body, aad: aad)
 
           wire = String.new(encoding: Encoding::BINARY, capacity: aad.bytesize + frame_size)
           wire << aad << ct
@@ -215,7 +215,7 @@ module Protocol
           aad = wire_flags + length_bytes
 
           begin
-            pt = @recv_stream.decrypt(frame.body, aad: aad)
+            pt = @recv_session.decrypt(frame.body, aad: aad)
           rescue @crypto::CryptoError
             raise Error, "decryption failed"
           end
@@ -616,17 +616,19 @@ module Protocol
         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)
+          c2s_enc_key  = kdf("#{PROTOCOL_ID} client->server enc key", ikm)
+          c2s_auth_key = kdf("#{PROTOCOL_ID} client->server auth key", ikm)
+          c2s_nonce    = kdf8("#{PROTOCOL_ID} client->server nonce", ikm)
+          s2c_enc_key  = kdf("#{PROTOCOL_ID} server->client enc key", ikm)
+          s2c_auth_key = kdf("#{PROTOCOL_ID} server->client auth key", ikm)
+          s2c_nonce    = kdf8("#{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)
+            @send_session = @crypto::Session.new(c2s_enc_key, c2s_auth_key, c2s_nonce)
+            @recv_session = @crypto::Session.new(s2c_enc_key, s2c_auth_key, s2c_nonce)
           else
-            @send_stream = @crypto::Stream.new(s2c_key, s2c_nonce)
-            @recv_stream = @crypto::Stream.new(c2s_key, c2s_nonce)
+            @send_session = @crypto::Session.new(s2c_enc_key, s2c_auth_key, s2c_nonce)
+            @recv_session = @crypto::Session.new(c2s_enc_key, c2s_auth_key, c2s_nonce)
           end
         end
 
@@ -645,6 +647,11 @@ module Protocol
         end
 
 
+        def kdf8(context, material)
+          @crypto::Hash.derive_key(context, material, size: 8)
+        end
+
+
         def kdf24(context, material)
           @crypto::Hash.derive_key(context, material, size: NONCE_SIZE)
         end

data/lib/omq/blake3zmq/version.rb

@@ -3,6 +3,6 @@
 module OMQ
   # BLAKE3-based encryption mechanism for ZMTP connections.
   module Blake3ZMQ
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omq-blake3zmq
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrik Wenger
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: x25519
   requirement: !ruby/object:Gem::Requirement