omq-curve 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 48930d7cc53900ad0b80f8a1cbf67527d54f344b2007862ff7e4dfae3355c9d2
+  data.tar.gz: 63ac0a03357e5a25c105dcef908ab305a14ad82a6e722dd6e6af79dde4b1718f
+SHA512:
+  metadata.gz: 006b7c5beb7168df20aa59d67e08f9ab17bd7ac26d46882582dd64d6641325e91e32bfebf09280e81912c2ff91bab0c043a28cf12009e636e2fa1427c1a45fff
+  data.tar.gz: e99ea6004f4a3dc693ae9792cd9be5420a1b059a07a5da79b736aae002a9d657378e0fe30c2754942c55d81654563d4084f176060660cd92a5814b5ba59b4baf

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-03-25
+
+Initial release. CurveZMQ (RFC 26) encryption for OMQ.
+
+- Curve25519-XSalsa20-Poly1305 encryption and authentication
+- 4-step handshake (HELLO/WELCOME/INITIATE/READY)
+- Anti-amplification and server statelessness per RFC 26
+- Client authentication via allowlist or custom callable
+- Z85 key encoding/decoding
+- Requires libsodium via rbnacl

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,284 @@
+# OMQ-CURVE
+
+CurveZMQ ([RFC 26](https://rfc.zeromq.org/spec/26/)) encryption for [OMQ](https://github.com/paddor/omq). Adds Curve25519 authenticated encryption to any OMQ socket over tcp or ipc.
+
+Interoperates with libzmq, CZMQ, pyzmq, and any other ZMTP 3.1 peer that speaks CURVE.
+
+## Install
+
+Requires libsodium on the system (the `rbnacl` gem calls it via FFI).
+
+```sh
+# Debian/Ubuntu
+sudo apt install libsodium-dev
+
+# macOS
+brew install libsodium
+```
+
+```sh
+gem install omq-curve
+# or in Gemfile
+gem 'omq-curve'
+```
+
+## Quick Start
+
+```ruby
+require 'omq/curve'
+require 'async'
+
+# Generate keypairs (once, store securely)
+server_key = RbNaCl::PrivateKey.generate
+client_key = RbNaCl::PrivateKey.generate
+
+Async do |task|
+  # --- Server ---
+  rep = OMQ::REP.new
+  rep.mechanism        = :curve
+  rep.curve_server     = true
+  rep.curve_public_key = server_key.public_key.to_s
+  rep.curve_secret_key = server_key.to_s
+  rep.bind('tcp://*:5555')
+
+  task.async do
+    msg = rep.receive
+    rep << msg.map(&:upcase)
+  end
+
+  # --- Client ---
+  req = OMQ::REQ.new
+  req.mechanism        = :curve
+  req.curve_server_key = server_key.public_key.to_s  # must know server's public key
+  req.curve_public_key = client_key.public_key.to_s
+  req.curve_secret_key = client_key.to_s
+  req.connect('tcp://localhost:5555')
+
+  req << 'hello'
+  puts req.receive.inspect  # => ["HELLO"]
+ensure
+  req&.close
+  rep&.close
+end
+```
+
+## Key Generation
+
+Keys are 32-byte Curve25519 keypairs. Generate them with rbnacl:
+
+```ruby
+require 'omq/curve'
+
+key = RbNaCl::PrivateKey.generate
+
+# Binary (32 bytes each) — use for socket options
+key.public_key.to_s  # => "\xCC\xA9\x9F..." (32 bytes)
+key.to_s             # => "\xAE\x8E\xC4..." (32 bytes)
+```
+
+### Persisting keys
+
+Never store secret keys in plaintext in source control. Options:
+
+```ruby
+# Environment variables (hex-encoded)
+ENV['OMQ_SERVER_SECRET'] = RbNaCl::Util.bin2hex(key.to_s)
+# ... later ...
+secret = RbNaCl::Util.hex2bin(ENV.fetch('OMQ_SERVER_SECRET'))
+
+# Or use Z85 (ZeroMQ's printable encoding, 40 chars for 32 bytes)
+z85_public = OMQ::Z85.encode(key.public_key.to_s)  # => "rq5+e..." (40 chars)
+z85_secret = OMQ::Z85.encode(key.to_s)
+
+# Decode back to binary
+OMQ::Z85.decode(z85_public)  # => 32-byte binary string
+```
+
+### Key file convention
+
+A simple pattern for file-based key storage:
+
+```ruby
+# Generate and save (once)
+key = RbNaCl::PrivateKey.generate
+File.write('server.key', OMQ::Z85.encode(key.to_s), perm: 0o600)
+File.write('server.pub', OMQ::Z85.encode(key.public_key.to_s))
+
+# Load
+secret = OMQ::Z85.decode(File.read('server.key'))
+public = OMQ::Z85.decode(File.read('server.pub'))
+```
+
+## Z85 Encoding
+
+[Z85](https://rfc.zeromq.org/spec/32/) is ZeroMQ's printable encoding for binary keys. It uses an 85-character alphabet and produces 40 characters for a 32-byte key — safe for config files, environment variables, and CLI arguments.
+
+```ruby
+binary = RbNaCl::Random.random_bytes(32)
+z85    = OMQ::Z85.encode(binary)   # => 40-char ASCII string
+binary = OMQ::Z85.decode(z85)      # => 32-byte binary string
+```
+
+Z85 keys are compatible with libzmq's `zmq_curve_keypair()` output and tools like `curve_keygen`.
+
+## Socket Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `mechanism` | `:null`, `:curve` | Security mechanism (default `:null`) |
+| `curve_server` | Boolean | `true` for the CURVE server side |
+| `curve_public_key` | String (32 bytes) | Our permanent public key |
+| `curve_secret_key` | String (32 bytes) | Our permanent secret key |
+| `curve_server_key` | String (32 bytes) | Server's public key (clients only) |
+| `curve_authenticator` | Set, `#call`, nil | Client key authenticator (server only, see below) |
+
+Set options before `bind`/`connect`:
+
+```ruby
+sock = OMQ::REP.new
+sock.mechanism        = :curve
+sock.curve_server     = true
+sock.curve_public_key = public_key
+sock.curve_secret_key = secret_key
+sock.bind('tcp://*:5555')
+```
+
+## Client vs Server
+
+In CURVE, "server" and "client" refer to the **cryptographic roles**, not the network topology. The CURVE server is the side that clients authenticate against.
+
+- **CURVE server**: has a well-known public key that clients must know in advance. Typically the `bind` side, but not necessarily.
+- **CURVE client**: knows the server's public key and proves its own identity during the handshake.
+
+Any socket type can be either the CURVE server or client:
+
+```ruby
+# ROUTER as CURVE server (typical)
+router = OMQ::ROUTER.new
+router.mechanism    = :curve
+router.curve_server = true
+# ...
+
+# PUB as CURVE server
+pub = OMQ::PUB.new
+pub.mechanism    = :curve
+pub.curve_server = true
+# ...
+```
+
+## Authentication
+
+By default, any client that knows the server's public key can connect. Use `curve_authenticator` to restrict access.
+
+### Allowlist (Set of keys)
+
+```ruby
+allowed = Set[client1_pub, client2_pub]
+
+rep = OMQ::REP.new
+rep.mechanism           = :curve
+rep.curve_server        = true
+rep.curve_public_key    = server_pub
+rep.curve_secret_key    = server_sec
+rep.curve_authenticator = allowed
+rep.bind('tcp://*:5555')
+```
+
+Unauthorized clients are disconnected during the handshake — no READY is sent and no messages are exchanged.
+
+### Custom authenticator (callable)
+
+For dynamic lookups, logging, or rate limiting, pass anything that responds to `#call`:
+
+```ruby
+rep.curve_authenticator = ->(client_public_key) {
+  # client_public_key is a 32-byte binary string
+  db_lookup(client_public_key) || false
+}
+```
+
+Return truthy to allow, falsy to reject. The authenticator runs during the CURVE handshake (after vouch verification, before READY), so rejected clients never reach the application layer.
+
+### Loading keys from files
+
+```ruby
+allowed = Set.new(
+  Dir['keys/clients/*.pub'].map { |f| OMQ::Z85.decode(File.read(f)) }
+)
+rep.curve_authenticator = allowed
+```
+
+### Note on ZAP
+
+libzmq uses [ZAP (RFC 27)](https://rfc.zeromq.org/spec/27/) for authentication — an inproc REQ/REP protocol between the socket and a ZAP handler. OMQ skips this indirection and lets you pass the authenticator directly. The effect is the same: client keys are checked during the handshake.
+
+## Managing Many Keys
+
+### One keypair per service
+
+The simplest model: each service has one keypair. Clients are configured with the server's public key. Key rotation means deploying a new keypair and updating all clients.
+
+```ruby
+# config/keys.yml (public keys only — safe to commit)
+api_gateway: "rq5+eJ..."
+worker_pool: "x8Kn2P..."
+```
+
+### Per-client keys with a key store
+
+For finer-grained access control, give each client its own keypair and maintain a server-side allowlist:
+
+```ruby
+# Server-side key store (flat file, database, vault, etc.)
+ALLOWED_CLIENTS = Set.new(
+  File.readlines('authorized_keys.txt', chomp: true)
+      .map { |z85| OMQ::Z85.decode(z85) }
+)
+
+rep.curve_authenticator = ALLOWED_CLIENTS
+```
+
+### Key rotation
+
+CURVE's perfect forward secrecy means rotating the permanent keypair doesn't compromise past traffic — each connection uses ephemeral session keys that are destroyed on disconnect.
+
+To rotate a server key:
+
+1. Generate a new keypair
+2. Configure the server with the new key
+3. Update clients with the new server public key
+4. Restart — new connections use the new key, existing connections continue with the old session keys until they disconnect
+
+## Performance
+
+CURVE adds ~70% latency overhead and ~35–40% throughput cost compared to NULL, dominated by libsodium FFI call overhead. See [bench/README.md](bench/README.md) for full results.
+
+| | NULL | CURVE |
+|---|---|---|
+| Latency (ipc) | 113 µs | 195 µs |
+| Throughput (ipc, 64 B) | 25.5k/s | 16.4k/s |
+
+## Interoperability
+
+OMQ-CURVE interoperates with any ZMTP 3.1 CURVE implementation. Verified against libzmq 4.3.5 via CZTop in both directions (OMQ↔libzmq) with REQ/REP and DEALER/ROUTER.
+
+## How It Works
+
+The [CurveZMQ](http://curvezmq.org/) handshake establishes a secure session in 4 steps:
+
+1. **HELLO** — client sends its transient public key + proof it knows the server's key
+2. **WELCOME** — server sends its transient public key in an encrypted cookie
+3. **INITIATE** — client echoes the cookie + proves its permanent identity via a vouch
+4. **READY** — server confirms, both sides have session keys
+
+After the handshake, every ZMTP frame is encrypted as a CurveZMQ MESSAGE using Curve25519-XSalsa20-Poly1305 with strictly incrementing nonces.
+
+Properties:
+- **Perfect forward secrecy** — compromising permanent keys doesn't reveal past traffic
+- **Server statelessness** — between WELCOME and INITIATE, the server holds no per-connection state (cookie-based recovery)
+- **Anti-amplification** — HELLO (200 bytes) > WELCOME (168 bytes)
+- **Replay protection** — strictly incrementing nonces, verified on every message
+
+## License
+
+[ISC](../LICENSE)

data/lib/omq/curve/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OMQ
+  module Curve
+    VERSION = "0.1.0"
+  end
+end

data/lib/omq/curve.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "omq"
+require "rbnacl"
+
+require_relative "curve/version"
+require_relative "z85"
+require_relative "zmtp/mechanism/curve"

data/lib/omq/z85.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OMQ
+  # Z85 encoding/decoding (ZeroMQ RFC 32).
+  #
+  # Encodes binary data in printable ASCII using an 85-character alphabet.
+  # Input length must be a multiple of 4 bytes; output is 5/4 the size.
+  #
+  module Z85
+    CHARS = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#".freeze
+    DECODE = Array.new(128, -1)
+    CHARS.each_byte.with_index { |b, i| DECODE[b] = i }
+    DECODE.freeze
+
+    BASE = 85
+
+    # Encodes binary data to a Z85 string.
+    #
+    # @param data [String] binary data (length must be multiple of 4)
+    # @return [String] Z85-encoded ASCII string
+    # @raise [ArgumentError] if length is not a multiple of 4
+    #
+    def self.encode(data)
+      data = data.b
+      raise ArgumentError, "data length must be a multiple of 4 (got #{data.bytesize})" unless (data.bytesize % 4).zero?
+
+      out = String.new(capacity: data.bytesize * 5 / 4)
+      i = 0
+      while i < data.bytesize
+        # Read 4 bytes as a big-endian 32-bit unsigned integer
+        value = data.getbyte(i) << 24 | data.getbyte(i + 1) << 16 |
+                data.getbyte(i + 2) << 8 | data.getbyte(i + 3)
+        # Encode as 5 Z85 characters (most significant first)
+        4.downto(0) do |j|
+          out << CHARS[(value / (BASE**j)) % BASE]
+        end
+        i += 4
+      end
+      out
+    end
+
+    # Decodes a Z85 string to binary data.
+    #
+    # @param string [String] Z85-encoded ASCII string (length must be multiple of 5)
+    # @return [String] binary data
+    # @raise [ArgumentError] if length is not a multiple of 5 or contains invalid characters
+    #
+    def self.decode(string)
+      raise ArgumentError, "string length must be a multiple of 5 (got #{string.bytesize})" unless (string.bytesize % 5).zero?
+
+      out = String.new(capacity: string.bytesize * 4 / 5, encoding: Encoding::BINARY)
+      i = 0
+      while i < string.bytesize
+        value = 0
+        5.times do |j|
+          byte = string.getbyte(i + j)
+          d = byte < 128 ? DECODE[byte] : -1
+          raise ArgumentError, "invalid Z85 character: #{string[i + j].inspect}" if d == -1
+          value = value * BASE + d
+        end
+        out << ((value >> 24) & 0xFF).chr
+        out << ((value >> 16) & 0xFF).chr
+        out << ((value >> 8) & 0xFF).chr
+        out << (value & 0xFF).chr
+        i += 5
+      end
+      out
+    end
+  end
+end

data/lib/omq/zmtp/mechanism/curve.rb

@@ -0,0 +1,467 @@
+# frozen_string_literal: true
+
+module OMQ
+  module ZMTP
+    module Mechanism
+      # CurveZMQ security mechanism (RFC 26).
+      #
+      # Provides Curve25519-XSalsa20-Poly1305 encryption and authentication
+      # for ZMTP 3.1 connections using the RbNaCl gem.
+      #
+      # After the 4-step handshake (HELLO/WELCOME/INITIATE/READY), all
+      # frames are encrypted as CurveZMQ MESSAGE commands using the
+      # transient session keys.
+      #
+      # DoS resistance (per RFC 26):
+      # - Anti-amplification: HELLO (200 bytes) > WELCOME (168 bytes)
+      # - Server statelessness: after sending WELCOME the server forgets
+      #   all per-connection state. On INITIATE, it recovers cn_public and
+      #   sn_secret from the cookie (which precedes the encrypted box in
+      #   cleartext). Only the socket-wide @cookie_key is needed.
+      # - Cookie verification prevents replay of stale INITIATEs.
+      #
+      class Curve
+        MECHANISM_NAME = "CURVE"
+
+        # Nonce prefixes. Most are 16 bytes (prefix + 8-byte counter on wire).
+        # WELCOME, COOKIE, and VOUCH use 8-byte prefixes with 16-byte random nonces.
+        NONCE_PREFIX_HELLO     = "CurveZMQHELLO---"  # 16 + 8
+        NONCE_PREFIX_WELCOME   = "WELCOME-"           #  8 + 16
+        NONCE_PREFIX_INITIATE  = "CurveZMQINITIATE"  # 16 + 8
+        NONCE_PREFIX_READY     = "CurveZMQREADY---"  # 16 + 8
+        NONCE_PREFIX_MESSAGE_C = "CurveZMQMESSAGEC"  # 16 + 8, client → server
+        NONCE_PREFIX_MESSAGE_S = "CurveZMQMESSAGES"  # 16 + 8, server → client
+        NONCE_PREFIX_VOUCH     = "VOUCH---"           #  8 + 16
+        NONCE_PREFIX_COOKIE    = "COOKIE--"           #  8 + 16
+
+        # Crypto overhead: 16 bytes Poly1305 authenticator
+        BOX_OVERHEAD = 16
+
+        # Maximum nonce value (2^64 - 1). Exceeding this would reuse nonces.
+        MAX_NONCE = (2**64) - 1
+
+        # @param public_key [String] our permanent public key (32 bytes)
+        # @param secret_key [String] our permanent secret key (32 bytes)
+        # @param as_server [Boolean] whether we are the CURVE server
+        # @param server_key [String, nil] server's permanent public key (32 bytes, required for clients)
+        # @param authenticator [#include?, #call, nil] client key authenticator (server only).
+        #   Set/Array → checked via #include?. Proc/lambda → called with the 32-byte
+        #   client public key, must return truthy to allow. nil → allow all.
+        #
+        def initialize(server_key: nil, public_key:, secret_key:, as_server: false, authenticator: nil)
+          validate_key!(public_key, "public_key")
+          validate_key!(secret_key, "secret_key")
+
+          @permanent_public = RbNaCl::PublicKey.new(public_key.b)
+          @permanent_secret = RbNaCl::PrivateKey.new(secret_key.b)
+          @as_server        = as_server
+          @authenticator    = authenticator
+
+          if as_server
+            # One cookie key per socket — enables server statelessness per-connection
+            @cookie_key = RbNaCl::Random.random_bytes(32)
+          else
+            validate_key!(server_key, "server_key")
+            @server_public = RbNaCl::PublicKey.new(server_key.b)
+          end
+
+          # Session state (set during handshake)
+          @session_box = nil  # RbNaCl::Box for MESSAGE encryption
+          @send_nonce  = 0    # outgoing MESSAGE nonce counter
+          @recv_nonce  = -1   # last received MESSAGE nonce (for replay detection)
+        end
+
+        # @return [Boolean] true — CURVE encrypts all post-handshake frames
+        #
+        def encrypted? = true
+
+        # Performs the CurveZMQ handshake.
+        #
+        # @param io [#read, #write] transport IO
+        # @param as_server [Boolean] (unused — tracked via @as_server)
+        # @param socket_type [String]
+        # @param identity [String]
+        # @return [Hash] { peer_socket_type:, peer_identity: }
+        # @raise [ProtocolError]
+        #
+        def handshake!(io, as_server:, socket_type:, identity:)
+          if @as_server
+            server_handshake!(io, socket_type: socket_type, identity: identity)
+          else
+            client_handshake!(io, socket_type: socket_type, identity: identity)
+          end
+        end
+
+        # Encrypts a frame body as a CurveZMQ MESSAGE command.
+        #
+        # The MESSAGE plaintext is: flags_byte + body.
+        # This replaces ZMTP framing — there is no ZMTP frame header inside.
+        #
+        # @param body [String] frame body
+        # @param more [Boolean] MORE flag
+        # @param command [Boolean] COMMAND flag
+        # @return [String] MESSAGE command frame wire bytes (ready to write)
+        #
+        def encrypt(body, more: false, command: false)
+          flags       = 0
+          flags      |= 0x01 if more
+          flags      |= 0x04 if command
+          plaintext   = flags.chr.b + body.b
+          nonce       = make_send_nonce
+          ciphertext  = @session_box.encrypt(nonce, plaintext)
+          short_nonce = nonce.byteslice(16, 8)
+
+          msg_body = "\x07MESSAGE".b + short_nonce + ciphertext
+          Codec::Frame.new(msg_body).to_wire
+        end
+
+        # Decrypts a CurveZMQ MESSAGE command into a Frame.
+        #
+        # @param frame [Codec::Frame] a command frame containing a MESSAGE
+        # @return [Codec::Frame] decrypted frame with flags and body
+        # @raise [ProtocolError] on decryption failure or nonce replay
+        #
+        def decrypt(frame)
+          cmd = Codec::Command.from_body(frame.body)
+          raise ProtocolError, "expected MESSAGE command, got #{cmd.name}" unless cmd.name == "MESSAGE"
+
+          data = cmd.data
+          raise ProtocolError, "MESSAGE too short" if data.bytesize < 8 + BOX_OVERHEAD
+
+          short_nonce = data.byteslice(0, 8)
+          ciphertext  = data.byteslice(8..)
+
+          # Verify strictly incrementing nonce
+          nonce_value = short_nonce.unpack1("Q>")
+          unless nonce_value > @recv_nonce
+            raise ProtocolError, "MESSAGE nonce not strictly incrementing"
+          end
+          @recv_nonce = nonce_value
+
+          nonce = recv_nonce_prefix + short_nonce
+          begin
+            plaintext = @session_box.decrypt(nonce, ciphertext)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "MESSAGE decryption failed"
+          end
+
+          flags = plaintext.getbyte(0)
+          body  = plaintext.byteslice(1..) || "".b
+          Codec::Frame.new(body, more: (flags & 0x01) != 0, command: (flags & 0x04) != 0)
+        end
+
+        private
+
+        # ----------------------------------------------------------------
+        # Client-side handshake
+        # ----------------------------------------------------------------
+
+        def client_handshake!(io, socket_type:, identity:)
+          cn_secret = RbNaCl::PrivateKey.generate
+          cn_public = cn_secret.public_key
+
+          # --- Exchange greetings ---
+          io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: false))
+          peer_greeting = Codec::Greeting.decode(io.read_exactly(Codec::Greeting::SIZE))
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise ProtocolError, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
+          end
+
+          # --- HELLO ---
+          short_nonce = [1].pack("Q>")
+          nonce       = NONCE_PREFIX_HELLO + short_nonce
+          hello_box   = RbNaCl::Box.new(@server_public, cn_secret)
+          signature   = hello_box.encrypt(nonce, "\x00" * 64)
+
+          hello = "".b
+          hello << "\x05HELLO"
+          hello << "\x01\x00"         # version 1.0
+          hello << ("\x00" * 72)      # anti-amplification padding
+          hello << cn_public.to_s     # 32 bytes
+          hello << short_nonce        # 8 bytes
+          hello << signature          # 80 bytes (64 + 16 MAC)
+
+          io.write(Codec::Frame.new(hello, command: true).to_wire)
+
+          # --- Read WELCOME ---
+          welcome_frame = Codec::Frame.read_from(io)
+          raise ProtocolError, "expected command frame" unless welcome_frame.command?
+          welcome_cmd = Codec::Command.from_body(welcome_frame.body)
+          raise ProtocolError, "expected WELCOME, got #{welcome_cmd.name}" unless welcome_cmd.name == "WELCOME"
+
+          wdata = welcome_cmd.data
+          # WELCOME: 16-byte random nonce + 144-byte box = 160 bytes
+          raise ProtocolError, "WELCOME wrong size" unless wdata.bytesize == 16 + 144
+
+          w_short_nonce = wdata.byteslice(0, 16)
+          w_box_data    = wdata.byteslice(16, 144)
+          w_nonce       = NONCE_PREFIX_WELCOME + w_short_nonce
+
+          # WELCOME box is encrypted from server permanent to client transient
+          begin
+            w_plaintext = RbNaCl::Box.new(@server_public, cn_secret).decrypt(w_nonce, w_box_data)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "WELCOME decryption failed"
+          end
+
+          sn_public = RbNaCl::PublicKey.new(w_plaintext.byteslice(0, 32))
+          cookie    = w_plaintext.byteslice(32, 96)
+
+          # Session box: client transient ↔ server transient
+          session = RbNaCl::Box.new(sn_public, cn_secret)
+
+          # --- INITIATE ---
+          # Per RFC 26, the cookie precedes the encrypted box in cleartext.
+          vouch_nonce     = NONCE_PREFIX_VOUCH + RbNaCl::Random.random_bytes(16)
+          vouch_plaintext = cn_public.to_s + @server_public.to_s
+          vouch           = RbNaCl::Box.new(sn_public, @permanent_secret).encrypt(vouch_nonce, vouch_plaintext)
+
+          metadata = Codec::Command.encode_properties(
+            "Socket-Type" => socket_type,
+            "Identity"    => identity,
+          )
+
+          # Box contents per libzmq: client_permanent_pub + vouch_nonce_short + vouch + metadata
+          initiate_box_plaintext = "".b
+          initiate_box_plaintext << @permanent_public.to_s        # 32 bytes
+          initiate_box_plaintext << vouch_nonce.byteslice(8, 16)  # 16-byte short vouch nonce
+          initiate_box_plaintext << vouch                         # 80 bytes (64 + 16 MAC)
+          initiate_box_plaintext << metadata
+
+          init_short_nonce = [1].pack("Q>")
+          init_nonce       = NONCE_PREFIX_INITIATE + init_short_nonce
+          init_ciphertext  = session.encrypt(init_nonce, initiate_box_plaintext)
+
+          # Wire format: cookie (cleartext) + short_nonce + encrypted box
+          initiate = "".b
+          initiate << "\x08INITIATE"
+          initiate << cookie            # 96 bytes, cleartext
+          initiate << init_short_nonce  # 8 bytes
+          initiate << init_ciphertext
+
+          io.write(Codec::Frame.new(initiate, command: true).to_wire)
+
+          # --- Read READY ---
+          ready_frame = Codec::Frame.read_from(io)
+          raise ProtocolError, "expected command frame" unless ready_frame.command?
+          ready_cmd = Codec::Command.from_body(ready_frame.body)
+          raise ProtocolError, "expected READY, got #{ready_cmd.name}" unless ready_cmd.name == "READY"
+
+          rdata = ready_cmd.data
+          raise ProtocolError, "READY too short" if rdata.bytesize < 8 + BOX_OVERHEAD
+
+          r_short_nonce = rdata.byteslice(0, 8)
+          r_ciphertext  = rdata.byteslice(8..)
+          r_nonce       = NONCE_PREFIX_READY + r_short_nonce
+
+          begin
+            r_plaintext = session.decrypt(r_nonce, r_ciphertext)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "READY decryption failed"
+          end
+
+          props            = Codec::Command.decode_properties(r_plaintext)
+          peer_socket_type = props["Socket-Type"]
+          peer_identity    = props["Identity"] || ""
+
+          @session_box = session
+          @send_nonce  = 1   # READY consumed nonce 1
+          @recv_nonce  = 0   # peer's READY consumed their nonce 1
+
+          { peer_socket_type: peer_socket_type, peer_identity: peer_identity }
+        end
+
+        # ----------------------------------------------------------------
+        # Server-side handshake
+        # ----------------------------------------------------------------
+
+        def server_handshake!(io, socket_type:, identity:)
+          # --- Exchange greetings ---
+          io.write(Codec::Greeting.encode(mechanism: MECHANISM_NAME, as_server: true))
+          peer_greeting = Codec::Greeting.decode(io.read_exactly(Codec::Greeting::SIZE))
+          unless peer_greeting[:mechanism] == MECHANISM_NAME
+            raise ProtocolError, "expected CURVE mechanism, got #{peer_greeting[:mechanism]}"
+          end
+
+          # --- Read HELLO ---
+          hello_frame = Codec::Frame.read_from(io)
+          raise ProtocolError, "expected command frame" unless hello_frame.command?
+          hello_cmd = Codec::Command.from_body(hello_frame.body)
+          raise ProtocolError, "expected HELLO, got #{hello_cmd.name}" unless hello_cmd.name == "HELLO"
+
+          hdata = hello_cmd.data
+          # version(2) + padding(72) + cn_public(32) + short_nonce(8) + signature(80) = 194
+          raise ProtocolError, "HELLO wrong size (#{hdata.bytesize})" unless hdata.bytesize == 194
+
+          cn_public     = RbNaCl::PublicKey.new(hdata.byteslice(74, 32))
+          h_short_nonce = hdata.byteslice(106, 8)
+          h_signature   = hdata.byteslice(114, 80)
+
+          h_nonce = NONCE_PREFIX_HELLO + h_short_nonce
+          begin
+            plaintext = RbNaCl::Box.new(cn_public, @permanent_secret).decrypt(h_nonce, h_signature)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "HELLO signature verification failed"
+          end
+          unless RbNaCl::Util.verify64(plaintext, "\x00" * 64)
+            raise ProtocolError, "HELLO signature content invalid"
+          end
+
+          # --- WELCOME ---
+          sn_secret = RbNaCl::PrivateKey.generate
+          sn_public = sn_secret.public_key
+
+          # Cookie: encrypt(cn_public + sn_secret) with socket-wide cookie key
+          cookie_nonce     = NONCE_PREFIX_COOKIE + RbNaCl::Random.random_bytes(16)
+          cookie_plaintext = cn_public.to_s + sn_secret.to_s
+          cookie           = cookie_nonce.byteslice(8, 16) +
+                             RbNaCl::SecretBox.new(@cookie_key).encrypt(cookie_nonce, cookie_plaintext)
+          # cookie = 16 (short nonce) + 64 (plaintext) + 16 (MAC) = 96 bytes
+
+          w_plaintext   = sn_public.to_s + cookie
+          w_short_nonce = RbNaCl::Random.random_bytes(16)  # 16-byte random nonce
+          w_nonce       = NONCE_PREFIX_WELCOME + w_short_nonce
+          w_ciphertext  = RbNaCl::Box.new(cn_public, @permanent_secret).encrypt(w_nonce, w_plaintext)
+
+          welcome = "".b
+          welcome << "\x07WELCOME"
+          welcome << w_short_nonce   # 16 bytes
+          welcome << w_ciphertext    # 128 + 16 = 144 bytes
+
+          io.write(Codec::Frame.new(welcome, command: true).to_wire)
+
+          # --- Read INITIATE ---
+          # Server recovers cn_public and sn_secret from the cookie below.
+          # Only @cookie_key (socket-wide) is needed to process INITIATE.
+          init_frame = Codec::Frame.read_from(io)
+          raise ProtocolError, "expected command frame" unless init_frame.command?
+          init_cmd = Codec::Command.from_body(init_frame.body)
+          raise ProtocolError, "expected INITIATE, got #{init_cmd.name}" unless init_cmd.name == "INITIATE"
+
+          idata = init_cmd.data
+          # cookie(96) + short_nonce(8) + box(at least BOX_OVERHEAD)
+          raise ProtocolError, "INITIATE too short" if idata.bytesize < 96 + 8 + BOX_OVERHEAD
+
+          # Cookie is in cleartext, preceding the encrypted box (per RFC 26)
+          recv_cookie   = idata.byteslice(0, 96)
+          i_short_nonce = idata.byteslice(96, 8)
+          i_ciphertext  = idata.byteslice(104..)
+
+          # Recover cn_public and sn_secret from the cookie
+          cookie_short_nonce   = recv_cookie.byteslice(0, 16)
+          cookie_ciphertext    = recv_cookie.byteslice(16, 80)
+          cookie_decrypt_nonce = NONCE_PREFIX_COOKIE + cookie_short_nonce
+          begin
+            cookie_contents = RbNaCl::SecretBox.new(@cookie_key).decrypt(cookie_decrypt_nonce, cookie_ciphertext)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "INITIATE cookie verification failed"
+          end
+
+          cn_public = RbNaCl::PublicKey.new(cookie_contents.byteslice(0, 32))
+          sn_secret = RbNaCl::PrivateKey.new(cookie_contents.byteslice(32, 32))
+
+          # Now decrypt the INITIATE box with the recovered transient keys
+          session = RbNaCl::Box.new(cn_public, sn_secret)
+          i_nonce = NONCE_PREFIX_INITIATE + i_short_nonce
+
+          begin
+            i_plaintext = session.decrypt(i_nonce, i_ciphertext)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "INITIATE decryption failed"
+          end
+
+          # Parse: client_permanent(32) + vouch_nonce_short(16) + vouch(80) + metadata
+          raise ProtocolError, "INITIATE plaintext too short" if i_plaintext.bytesize < 32 + 16 + 80
+
+          client_permanent  = RbNaCl::PublicKey.new(i_plaintext.byteslice(0, 32))
+          vouch_short_nonce = i_plaintext.byteslice(32, 16)
+          vouch_ciphertext  = i_plaintext.byteslice(48, 80)
+          metadata_bytes    = i_plaintext.byteslice(128..) || "".b
+
+          # Decrypt vouch: from client permanent to server transient
+          vouch_nonce = NONCE_PREFIX_VOUCH + vouch_short_nonce
+          begin
+            vouch_plaintext = RbNaCl::Box.new(client_permanent, sn_secret).decrypt(vouch_nonce, vouch_ciphertext)
+          rescue RbNaCl::CryptoError
+            raise ProtocolError, "INITIATE vouch verification failed"
+          end
+
+          raise ProtocolError, "vouch wrong size" unless vouch_plaintext.bytesize == 64
+
+          vouch_cn     = vouch_plaintext.byteslice(0, 32)
+          vouch_server = vouch_plaintext.byteslice(32, 32)
+
+          unless RbNaCl::Util.verify32(vouch_cn, cn_public.to_s)
+            raise ProtocolError, "vouch client transient key mismatch"
+          end
+          unless RbNaCl::Util.verify32(vouch_server, @permanent_public.to_s)
+            raise ProtocolError, "vouch server key mismatch"
+          end
+
+          # Authenticate client
+          if @authenticator
+            client_key = client_permanent.to_s
+            allowed    = if @authenticator.respond_to?(:include?)
+                           @authenticator.include?(client_key)
+                         else
+                           @authenticator.call(client_key)
+                         end
+            raise ProtocolError, "client key not authorized" unless allowed
+          end
+
+          # --- READY ---
+          ready_metadata = Codec::Command.encode_properties(
+            "Socket-Type" => socket_type,
+            "Identity"    => identity,
+          )
+
+          r_short_nonce = [1].pack("Q>")
+          r_nonce       = NONCE_PREFIX_READY + r_short_nonce
+          r_ciphertext  = session.encrypt(r_nonce, ready_metadata)
+
+          ready = "".b
+          ready << "\x05READY"
+          ready << r_short_nonce
+          ready << r_ciphertext
+
+          io.write(Codec::Frame.new(ready, command: true).to_wire)
+
+          props = Codec::Command.decode_properties(metadata_bytes)
+
+          @session_box = session
+          @send_nonce  = 1   # READY consumed nonce 1
+          @recv_nonce  = 0   # peer's INITIATE consumed their nonce 1
+
+          {
+            peer_socket_type: props["Socket-Type"],
+            peer_identity:    props["Identity"] || "",
+          }
+        end
+
+        # ----------------------------------------------------------------
+        # Nonce helpers
+        # ----------------------------------------------------------------
+
+        def make_send_nonce
+          @send_nonce += 1
+          raise ProtocolError, "nonce counter exhausted" if @send_nonce > MAX_NONCE
+          short = [@send_nonce].pack("Q>")
+          send_nonce_prefix + short
+        end
+
+        def send_nonce_prefix
+          @as_server ? NONCE_PREFIX_MESSAGE_S : NONCE_PREFIX_MESSAGE_C
+        end
+
+        def recv_nonce_prefix
+          @as_server ? NONCE_PREFIX_MESSAGE_C : NONCE_PREFIX_MESSAGE_S
+        end
+
+        def validate_key!(key, name)
+          raise ArgumentError, "#{name} is required" if key.nil?
+          raise ArgumentError, "#{name} must be 32 bytes (got #{key.b.bytesize})" unless key.b.bytesize == 32
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: omq-curve
+version: !ruby/object:Gem::Version
+  version: 0.1.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: omq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Adds CURVE security (Curve25519 encryption and authentication) to OMQ
+  sockets. Requires libsodium via rbnacl.
+email:
+- paddor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/omq/curve.rb
+- lib/omq/curve/version.rb
+- lib/omq/z85.rb
+- lib/omq/zmtp/mechanism/curve.rb
+homepage: https://github.com/paddor/omq-curve
+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.6
+specification_version: 4
+summary: CurveZMQ (RFC 26) encryption for OMQ
+test_files: []