noise-ruby 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a3f4c1b701c2de6240cb5fc0fb2410e1790c390142b256e6b822af4fa327cef
-  data.tar.gz: a57735c978c1227262bc122e869aa6866e76a943654981fb57411d70cab34f80
+  metadata.gz: 326691ebec86a68d5b4978756edcd5752c7307e4eba85c615e08262f8133481e
+  data.tar.gz: 0626adc9ec4b0821211b04b3573a950684ca526edcd5e956450107d4d8c69ce0
 SHA512:
-  metadata.gz: 915a8da57226d70b24a5a7289325eba851d1e7e40c7d7ef0d0081411008f388a78eec00a760fe92f05ef82ccd707bc776bc8d4d385a6e14d1c3184714b7437b3
-  data.tar.gz: dd660c060e00d5c1d0c0e89c434743d6e91749ba09d16a8217e0031c641a2788636ba0fbf64bcfcc031ed84c75e290e3526d95af40fc6518a0211b1e292f7d77
+  metadata.gz: 2246a0d4be698a11efb560f6e9ddd70b50a926255c32877d8fd7346780e99e4d2950ac2e10ed81fb787ce9a61f626027e69136e94d680c9959e79c1702c73c47
+  data.tar.gz: fe3e968bbb464d11bd574750bdd97410b7ef5564328b327946654f76f8476fae4eadb7fbb8acebf4c4036b4f5edaa2d4a5b265c38705cc2ad33e25f310f78255

data/.github/workflows/ruby.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '3.3'
+          - '4.0'
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -37,11 +37,10 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '3.0'
-          - '3.1'
           - '3.2'
           - '3.3'
           - '3.4'
+          - '4.0'
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

data/.rubocop.yml

@@ -19,7 +19,7 @@ Style/WordArray:
   MinSize: 100
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   SuggestExtensions: false
 
 Naming/MethodParameterName:

data/.ruby-version

@@ -1 +1 @@
-3.3.5
+4.0.6

data/Dockerfile

@@ -1,8 +1,7 @@
-# check=skip=FromPlatformFlagConstDisallowed
-# The test suite loads the x86_64 libsecp256k1 bundled in spec/lib, and spec/spec_helper.rb
-# points at it unconditionally, so this image has to be linux/amd64 even on an arm64 host.
-# It mirrors the CI runner (ubuntu x86_64).
-FROM --platform=linux/amd64 ruby:3.3
+# A Linux environment close to the CI runner, for checking a change against the Ruby version CI
+# lints with. Nothing in the suite is architecture specific, so the image builds for the host
+# architecture and needs no emulation.
+FROM ruby:4.0
 
 # libsodium: dlopen'd by rbnacl, which lib/noise.rb requires unconditionally.
 # cargo: the blake3 gem is a Rust extension and is built at install time.

data/Gemfile

@@ -4,6 +4,6 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Specify your gem's dependencies in noise.gemspec. The optional ed448, secp256k1-ruby and blake3
-# backends are development dependencies there, so the test suite covers all of them.
+# Specify your gem's dependencies in noise.gemspec. The optional blake3 backend is a development
+# dependency there, so the test suite covers it too.
 gemspec

data/README.md

@@ -30,6 +30,9 @@ Supported Features:
 
 ## Installation
 
+This gem requires Ruby 3.2 or later, and is tested on 3.2, 3.3, 3.4 and 4.0. Ruby 3.0 and 3.1 are
+past end of life and are no longer supported; stay on noise-ruby 0.12.0 or earlier if you need them.
+
 This gem needs libsodium library.
 To install libsodium, see https://github.com/jedisct1/libsodium
 
@@ -47,21 +50,6 @@ Or install it yourself as:
 
     $ gem install noise-ruby
 
-If you use Secp256k1, you must install [libsecp256k1](https://github.com/bitcoin-core/secp256k1).
-
-    $ git clone https://github.com/bitcoin-core/secp256k1
-    $ cd secp256k1
-    $ ./autogen.sh
-    $ ./configure --enable-module-recovery --enable-experimental --enable-module-ecdh
-    $ make
-    $ sudo make install
-
-and, add this line to your Gemfile:
-
-```
-gem 'secp256k1-ruby'
-```
-
 If you use BLAKE3, you must install [Rust and Cargo](https://www.rust-lang.org/tools/install).
 And add this line to your Gemfile:
 
@@ -75,6 +63,25 @@ Followings shows handshake protocol with "Noise_NN_25519_ChaChaPoly_BLAKE2b"
 
 ### Handshake
 
+#### Supplying keys
+
+Patterns other than `NN` need keys before the handshake starts. `Connection::Initiator.new` and
+`Connection::Responder.new` take them in the `keypairs:` hash: `:s` is the local static private key,
+`:rs` and `:re` are the remote party's static and ephemeral public keys.
+
+```
+initiator = Noise::Connection::Initiator.new("Noise_XX_25519_ChaChaPoly_SHA256", keypairs: { s: static_private_key })
+```
+
+`keypairs:` also accepts `:e`, the local ephemeral private key. **It exists only so that
+`spec/vectors_spec.rb` can reproduce the official test vectors, which fix both sides' ephemeral keys
+to make the output deterministic. Never set it in production.** A connection created with `:e` reuses
+that ephemeral keypair instead of generating a fresh one per handshake, which destroys the forward
+secrecy every pattern depends on: an attacker who recovers the key can decrypt every session that
+used it, past and future. Nothing fails and no warning is printed - the handshake still succeeds and
+your own tests still pass - so the loss is invisible. Leave `:e` unset and let the library generate
+it.
+
 #### initiator
 
 ```

data/lib/noise/connection/base.rb

@@ -13,6 +13,16 @@ module Noise
                   :cipher_state_encrypt, :cipher_state_decrypt, :cipher_state_handshake, :s, :rs
       attr_accessor :psks, :prologue
 
+      # @param [String] name the protocol name, for example 'Noise_XX_25519_ChaChaPoly_SHA256'.
+      # @param [Hash] keypairs the keys the pattern needs, as private or public key strings.
+      #   :s is the local static private key, :rs and :re the remote static and ephemeral public keys.
+      #
+      #   :e sets the local ephemeral private key. It exists only so that spec/vectors_spec.rb can
+      #   reproduce the official test vectors, which fix both sides' ephemeral keys to make the
+      #   output deterministic. Never set it outside that use: HandshakeState#write_message reuses
+      #   the keypair given here instead of generating a fresh one, and an ephemeral key reused
+      #   across handshakes gives up the forward secrecy every pattern depends on. The handshake
+      #   still succeeds, so nothing reports the loss.
       def initialize(name, keypairs: { s: nil, e: nil, rs: nil, re: nil })
         @protocol = Protocol.create(name)
 
@@ -64,8 +74,10 @@ module Noise
         raise Noise::Exceptions::NoiseHandshakeError if @next_message != :write
         raise Noise::Exceptions::NoiseHandshakeError if @handshake_finished
 
-        if @handshake_state.expected_message_length(payload.bytesize) > MAX_MESSAGE_LENGTH
-          raise Noise::Exceptions::NoiseHandshakeError, 'Message exceeds the maximum length.'
+        length = @handshake_state.expected_message_length(payload.bytesize)
+        if length > MAX_MESSAGE_LENGTH
+          raise Noise::Exceptions::MessageTooLongError,
+                "Message would be #{length} bytes, which exceeds the maximum of #{MAX_MESSAGE_LENGTH}."
         end
 
         @next_message = :read
@@ -79,8 +91,11 @@ module Noise
         raise Noise::Exceptions::NoiseHandshakeError unless @handshake_started
         raise Noise::Exceptions::NoiseHandshakeError if @next_message != :read
         raise Noise::Exceptions::NoiseHandshakeError if @handshake_finished
-        raise Noise::Exceptions::NoiseHandshakeError, 'Message exceeds the maximum length.' if
-          data.bytesize > MAX_MESSAGE_LENGTH
+
+        if data.bytesize > MAX_MESSAGE_LENGTH
+          raise Noise::Exceptions::MessageTooLongError,
+                "Message is #{data.bytesize} bytes, which exceeds the maximum of #{MAX_MESSAGE_LENGTH}."
+        end
 
         @next_message = :write
         buffer = +''

data/lib/noise/exceptions/message_too_long_error.rb

@@ -2,9 +2,18 @@
 
 module Noise
   module Exceptions
-    # Raised when a transport message would exceed, or does exceed, the 65535 byte limit the Noise
-    # specification places on every message. Kept apart from DecryptError so that a caller can tell a
-    # badly framed message from a failed authentication, which has very different security meaning.
+    # Raised when a message would exceed, or does exceed, the 65535 byte limit the Noise
+    # specification places on every message. Raised from the handshake and the transport paths
+    # alike, so that a caller handling "the peer sent something too long" rescues one class rather
+    # than one per phase.
+    #
+    # It covers over-long messages only, and the other framing errors keep their own classes: a
+    # truncated handshake message raises NoiseHandshakeError, and a transport message shorter than
+    # the authentication tag raises DecryptError. A caller that treats every framing error alike
+    # has to rescue all three.
+    #
+    # Kept apart from DecryptError so that a badly framed message can be told from a failed
+    # authentication, which has very different security meaning.
     class MessageTooLongError < StandardError
     end
   end

data/lib/noise/functions/dh/secp256k1.rb

@@ -1,17 +1,35 @@
 # frozen_string_literal: true
 
-Noise.require_optional 'secp256k1'
-
 module Noise
   module Functions
     module DH
+      # The secp256k1 DH function, as the Lightning Network uses it in BOLT #8.
+      #
+      # The shared secret is SHA256 of the shared point in compressed form, not the raw X
+      # coordinate. That is what BOLT #8 specifies and what libsecp256k1's ecdh returned when this
+      # function was backed by that library, so the value on the wire is unchanged.
       class Secp256k1
-        # Length of a compressed secp256k1 point. libsecp256k1 also accepts the 65-byte
-        # uncompressed form, but Noise exchanges only the compressed one.
+        # Length of a compressed secp256k1 point. The 65-byte uncompressed form encodes the same
+        # point, but Noise exchanges only the compressed one, so it is rejected.
         DHLEN = 33
 
+        # Length of a secp256k1 scalar, which is what a private key is.
+        PRIVATE_KEY_LEN = 32
+
+        # The name OpenSSL knows the curve by.
+        CURVE = 'secp256k1'
+
+        # Builds the curve group once, because dh needs it on every call.
+        #
+        # secp256k1 is a builtin curve of OpenSSL 3, but an OpenSSL restricted to a FIPS provider
+        # does not offer it. That leaves the function unusable in the same way a missing system
+        # library did, so it is reported as MissingDependencyError rather than as an OpenSSL error
+        # raised in the middle of a handshake.
         def initialize
-          Noise.optional_dependency!('secp256k1')
+          @group = OpenSSL::PKey::EC::Group.new(CURVE)
+        rescue OpenSSL::PKey::EC::Group::Error => e
+          raise Noise::Exceptions::MissingDependencyError,
+                "OpenSSL does not offer the #{CURVE} curve: #{e.message}"
         end
 
         def generate_keypair
@@ -19,25 +37,29 @@ module Noise
           private_key = 1 + SecureRandom.random_number(group.order - 1)
           public_key = group.generator.multiply_by_scalar(private_key)
           Noise::Key.new(
-            ECDSA::Format::IntegerOctetString.encode(private_key, 32),
+            ECDSA::Format::IntegerOctetString.encode(private_key, PRIVATE_KEY_LEN),
             ECDSA::Format::PointOctetString.encode(public_key, compression: true)
           )
         end
 
         # Computes the ECDH shared secret for the given remote public key.
         #
-        # A point that is not on the curve makes libsecp256k1 raise Secp256k1::AssertError,
-        # while a public key of any other length raises ArgumentError before the point is
-        # even parsed. Both are translated to InvalidPublicKeyError, matching the other DH
-        # functions. The length is checked here rather than left to the gem so that
-        # ArgumentError raised for a malformed private key keeps propagating as itself.
+        # Every way a peer-supplied key can be unusable raises InvalidPublicKeyError, matching the
+        # other DH functions: a length other than DHLEN, and an encoding that names no point on the
+        # curve. A private key the caller owns is not the peer's fault, so a malformed one raises
+        # ArgumentError instead, as it did when the gem parsed it.
         def dh(private_key, public_key)
           raise Noise::Exceptions::InvalidPublicKeyError, public_key unless public_key.bytesize == DHLEN
 
-          key = ::Secp256k1::PublicKey.new(pubkey: public_key, raw: true)
-          key.ecdh(private_key)
-        rescue ::Secp256k1::AssertError
-          raise Noise::Exceptions::InvalidPublicKeyError, public_key
+          scalar = OpenSSL::BN.new(self.class.decode_private_key(private_key))
+          shared = parse_public_key(public_key).mul(scalar)
+          # A backstop rather than a reachable case: secp256k1 has cofactor 1, so a point that
+          # parsed has order n, and the scalar is already known to be in [1, n-1]. It stays because
+          # the cost is one comparison and the failure it guards is severe - the compressed
+          # encoding of infinity is the single byte 0x00, whose SHA256 anyone can precompute.
+          raise Noise::Exceptions::InvalidPublicKeyError, public_key if shared.infinity?
+
+          OpenSSL::Digest.digest('SHA256', shared.to_octet_string(:compressed))
         end
 
         def dhlen
@@ -45,11 +67,48 @@ module Noise
         end
 
         def self.from_private(private_key)
-          group = ECDSA::Group::Secp256k1
-          scalar = ECDSA::Format::IntegerOctetString.decode(private_key)
-          point = group.generator.multiply_by_scalar(scalar)
+          scalar = decode_private_key(private_key)
+          point = ECDSA::Group::Secp256k1.generator.multiply_by_scalar(scalar)
           Noise::Key.new(private_key, ECDSA::Format::PointOctetString.encode(point, compression: true))
         end
+
+        # Decodes a private key into the scalar it denotes, rejecting the values that cannot serve
+        # as one. Both entry points that take a private key go through this, so a key from_private
+        # accepts is one dh can use.
+        #
+        # Rejected are a length other than PRIVATE_KEY_LEN, zero, and anything at or above the
+        # group order: those scalars multiply every point to infinity, whose compressed encoding is
+        # the single byte 0x00. Without the check from_private would hand back a Noise::Key holding
+        # that one byte as its public key, and the handshake it is used in would fail only once the
+        # key reached the wire. A private key belongs to the caller rather than to the peer, so a
+        # bad one raises ArgumentError and not InvalidPublicKeyError.
+        def self.decode_private_key(private_key)
+          unless private_key.bytesize == PRIVATE_KEY_LEN
+            raise ArgumentError, "private key must be #{PRIVATE_KEY_LEN} bytes"
+          end
+
+          scalar = ECDSA::Format::IntegerOctetString.decode(private_key)
+          order = ECDSA::Group::Secp256k1.order
+          raise ArgumentError, 'private key is out of range' unless scalar.between?(1, order - 1)
+
+          scalar
+        end
+
+        private
+
+        # Decodes a public key into a point on the curve.
+        #
+        # The key is passed as a String, not as an OpenSSL::BN. OpenSSL then decodes it as an octet
+        # string and raises Point::Error for anything that is not a point on the curve, the
+        # all-zero key included: 0x00 introduces the encoding of infinity, which is one byte long,
+        # so 33 zero bytes are rejected as a malformed encoding. Handing over a BN instead would
+        # drop the leading zero byte and produce the point at infinity, whose shared secret is a
+        # constant that the sender of such a key could precompute.
+        def parse_public_key(public_key)
+          OpenSSL::PKey::EC::Point.new(@group, public_key)
+        rescue OpenSSL::PKey::EC::Point::Error
+          raise Noise::Exceptions::InvalidPublicKeyError, public_key
+        end
       end
     end
   end

data/lib/noise/state/handshake_state.rb

@@ -107,6 +107,12 @@ module Noise
         pattern.each do |token|
           case token
           when Noise::Token::E
+            # A fresh keypair per handshake is what the pattern's forward secrecy rests on. Two
+            # things preset @e. Connection::Base#fallback carries the ephemeral of the aborted
+            # handshake into the new state, which the fallback patterns require: process_fallback
+            # mixes its public key as a pre-message. A caller passing keypairs[:e] to
+            # Connection::Base#initialize also presets it, and that is supported for reproducing
+            # the official test vectors and nothing else.
             @e ||= @protocol.dh_fn.generate_keypair
             message_buffer << @e.public_key
             mix_e(@e.public_key)

data/lib/noise/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Noise
-  VERSION = '0.12.0'
+  VERSION = '0.13.0'
 end

data/lib/noise.rb

@@ -3,7 +3,6 @@
 require 'noise/version'
 
 require 'ecdsa'
-require 'logger'
 require 'openssl'
 require 'rbnacl'
 require 'ruby_hmac'
@@ -27,18 +26,25 @@ module Noise
   @unavailable_dependencies = {}
 
   class << self
-    def logger
-      @logger ||= Logger.new($stdout)
-    end
-
+    # Requires an optional backend gem and yields once it is loaded. A LoadError is not fatal:
+    # the reason is recorded so optional_dependency! can raise it later, and a warning goes to
+    # $stderr so the missing backend is visible at load time. Kernel#warn is used rather than a
+    # Logger because logger is no longer a default gem on Ruby 4.0, and this single message does
+    # not justify a runtime dependency on it.
     def require_optional(name)
       require name
-      yield if block_given?
     rescue LoadError => e
       @unavailable_dependencies[name] = e.message
-      logger.warn("Optional dependency '#{name}' is unavailable: #{e.message}")
+      warn("Optional dependency '#{name}' is unavailable: #{e.message}")
+    else
+      # The block runs outside the rescue on purpose: a LoadError raised by the block itself is
+      # about something other than this dependency, and swallowing it here would hide the cause.
+      yield if block_given?
     end
 
+    # Raises MissingDependencyError if the named optional backend failed to load earlier. Call it
+    # from the entry point of a function that needs the backend, so the failure surfaces where the
+    # backend is used rather than at require time.
     def optional_dependency!(name)
       reason = @unavailable_dependencies[name]
       return if reason.nil?

data/noise.gemspec

@@ -6,7 +6,7 @@ require 'noise/version'
 
 Gem::Specification.new do |spec|
   spec.name = 'noise-ruby'
-  spec.required_ruby_version = '~> 3.0'
+  spec.required_ruby_version = '>= 3.2'
   spec.version       = Noise::VERSION
   spec.authors       = ['Hajime Yamaguchi']
   spec.email         = ['gen.yamaguchi0@gmail.com']
@@ -22,7 +22,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
 
@@ -31,16 +30,16 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'simplecov-json'
 
-  # Optional backends. Each one is needed only when its function appears in a protocol name, and
-  # each also needs a system library that cannot be installed as a gem, so none of them is a runtime
-  # dependency. Add the one you need to your own Gemfile; see the README for the system libraries.
+  # Optional backend. BLAKE3 is needed only when it appears in a protocol name, and it needs Rust
+  # to build, so it is not a runtime dependency. Add it to your own Gemfile if you need it; see the
+  # README.
   spec.add_development_dependency 'blake3'
-  spec.add_development_dependency 'secp256k1-ruby'
 
   spec.add_runtime_dependency 'ecdsa'
   # The 448 DH function needs the raw key API (OpenSSL::PKey.new_raw_private_key and friends),
-  # which arrived in openssl 3.0. Ruby 3.0 still ships 2.2 as its default gem, so the version has
-  # to be requested explicitly rather than left to whatever the interpreter bundles.
+  # which arrived in openssl 3.0. Every supported interpreter bundles a newer default gem, but the
+  # floor is stated so an older openssl pinned in an application's Gemfile fails to resolve rather
+  # than failing at runtime.
   spec.add_runtime_dependency 'openssl', '>= 3.0'
   spec.add_runtime_dependency 'rbnacl'
   spec.add_runtime_dependency 'ruby-hmac'

metadata

@@ -1,29 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noise-ruby
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Hajime Yamaguchi
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,20 +107,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: secp256k1-ruby
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: ecdsa
   requirement: !ruby/object:Gem::Requirement
@@ -259,23 +230,21 @@ files:
 homepage: https://github.com/Yamaguchi/noise
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A Ruby implementation of the Noise Protocol framework
 test_files: []