noise-ruby 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 876220b34ef23fb45d18cb2dd0dfd7627b5bb202e51f57af9c0cd5a62c211626
-  data.tar.gz: 662c47506e70adf05928da7b8c5e3fb48503e0043242f4127459297e29dba476
+  metadata.gz: 4a3f4c1b701c2de6240cb5fc0fb2410e1790c390142b256e6b822af4fa327cef
+  data.tar.gz: a57735c978c1227262bc122e869aa6866e76a943654981fb57411d70cab34f80
 SHA512:
-  metadata.gz: 8db525a248cd3a66f1597736745d70470ef109a3e7c7acd9758fda79c5c45aa78350d833c38a4d6d3d2ae9f8a06dd3b6b7f89a6c4928c12ea3dfe899efca4906
-  data.tar.gz: 420bd4dbeff8a66570f9d71ec219375aafeb9e5a45d76b1f23f6d9dfe47776b73da860b918f585214983224fea488370dc423f27dbd7c8905c95f33d8a4dce13
+  metadata.gz: 915a8da57226d70b24a5a7289325eba851d1e7e40c7d7ef0d0081411008f388a78eec00a760fe92f05ef82ccd707bc776bc8d4d385a6e14d1c3184714b7437b3
+  data.tar.gz: dd660c060e00d5c1d0c0e89c434743d6e91749ba09d16a8217e0031c641a2788636ba0fbf64bcfcc031ed84c75e290e3526d95af40fc6518a0211b1e292f7d77

data/Dockerfile

@@ -1,7 +1,7 @@
 # check=skip=FromPlatformFlagConstDisallowed
-# The test suite loads the x86_64 libsecp256k1 / libgoldilocks bundled in spec/lib, and
-# spec/spec_helper.rb points at them unconditionally, so this image has to be linux/amd64
-# even on an arm64 host. It mirrors the CI runner (ubuntu x86_64).
+# 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
 
 # libsodium: dlopen'd by rbnacl, which lib/noise.rb requires unconditionally.

data/README.md

@@ -47,24 +47,6 @@ Or install it yourself as:
 
     $ gem install noise-ruby
 
-If you use Ed448 as DH function, you must install [libgoldilocks](https://github.com/otrv4/libgoldilocks).
-
-After installing, define an environment variable as follows:
-
-   * on macOS
-
-         $ export LIBGOLDILOCKS=/usr/local/lib/libgoldilocks.dylib
-
-   * on Linux(Ubuntu)
-
-         $ export LIBGOLDILOCKS=/usr/local/lib/libgoldilocks.so
-
-and, add this line to your Gemfile:
-
-```
-gem 'ed448'
-```
-
 If you use Secp256k1, you must install [libsecp256k1](https://github.com/bitcoin-core/secp256k1).
 
     $ git clone https://github.com/bitcoin-core/secp256k1
@@ -138,6 +120,31 @@ cipher = initiator.encrypt("Hello, World!") # => "\xDA\xC7\xD7as\v\xFA\xCC,\xB3\
 plain = responder.decrypt(cipher) # => "Hello, World!"
 ```
 
+#### Out-of-order transport messages
+
+Each party counts the transport messages of each direction with a nonce. If the transport layer can
+deliver messages out of order or lose them, it has to carry the nonce of each message, and the
+receiver sets the nonce before decrypting. Restore the previous value if the message fails to
+authenticate, so that the following messages are still decryptable.
+
+```
+initiator.encryption_nonce # => 0
+responder.decryption_nonce = 2 # decrypt the message numbered 2 next
+plain = responder.decrypt(cipher)
+```
+
+#### Rekey
+
+Rekeying replaces the key of one direction with `REKEY(k)`, so that a key compromised later cannot
+decrypt the messages that came before it. The nonce keeps counting. Both parties must rekey the
+matching direction at the same point of the message stream; when that happens is up to the
+application protocol.
+
+```
+initiator.rekey_encryption
+responder.rekey_decryption
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/noise/connection/base.rb

@@ -3,8 +3,11 @@
 module Noise
   module Connection
     class Base
-      # The Noise spec caps a handshake or transport message at 65535 bytes.
+      # The Noise spec caps a handshake or transport message at 65535 bytes. A transport message is
+      # the ciphertext, so the plaintext a caller may hand to encrypt is shorter by the
+      # authentication tag that ENCRYPT() appends.
       MAX_MESSAGE_LENGTH = 65_535
+      MAX_PLAINTEXT_LENGTH = MAX_MESSAGE_LENGTH - Noise::State::CipherState::TAG_LENGTH
 
       attr_reader :protocol, :handshake_started, :handshake_finished, :handshake_hash, :handshake_state,
                   :cipher_state_encrypt, :cipher_state_decrypt, :cipher_state_handshake, :s, :rs
@@ -86,21 +89,82 @@ module Noise
       end
 
       def encrypt(data)
-        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_finished
+        cipher_state = transport_cipher_state(:encrypt)
+        if data.bytesize > MAX_PLAINTEXT_LENGTH
+          raise Noise::Exceptions::MessageTooLongError,
+                "Plaintext is #{data.bytesize} bytes, which exceeds the maximum of #{MAX_PLAINTEXT_LENGTH}."
+        end
 
-        @cipher_state_encrypt.encrypt_with_ad('', data)
+        cipher_state.encrypt_with_ad('', data)
       end
 
       def decrypt(data)
-        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_finished
+        cipher_state = transport_cipher_state(:decrypt)
+        # Rejected before the cipher state is used, so an over-long message leaves n untouched
+        # and the connection usable, exactly as a failed decryption does.
+        if data.bytesize > MAX_MESSAGE_LENGTH
+          raise Noise::Exceptions::MessageTooLongError,
+                "Message is #{data.bytesize} bytes, which exceeds the maximum of #{MAX_MESSAGE_LENGTH}."
+        end
+
+        cipher_state.decrypt_with_ad('', data)
+      end
+
+      # @return [Integer] the nonce the next #encrypt call uses.
+      def encryption_nonce
+        transport_cipher_state(:encrypt).n
+      end
+
+      # @return [Integer] the nonce the next #decrypt call uses.
+      def decryption_nonce
+        transport_cipher_state(:decrypt).n
+      end
+
+      # Sets the nonce of the next #encrypt call. Needed when the transport layer numbers the
+      # messages itself instead of relying on the sender and the receiver counting in step.
+      #
+      # @param [Integer] nonce a value between 0 and CipherState::MAX_NONCE.
+      def encryption_nonce=(nonce)
+        transport_cipher_state(:encrypt).nonce = nonce
+      end
+
+      # Sets the nonce of the next #decrypt call. This is how the Noise spec handles transport
+      # messages that arrive out of order: the receiver sets n to the nonce of the message it is
+      # about to decrypt, and restores the previous value if the message fails to authenticate.
+      #
+      # @param [Integer] nonce a value between 0 and CipherState::MAX_NONCE.
+      def decryption_nonce=(nonce)
+        transport_cipher_state(:decrypt).nonce = nonce
+      end
+
+      # Replaces the key used by #encrypt with REKEY(k), so that the old key cannot decrypt the
+      # messages that follow. Both parties must rekey the matching direction at the same point of
+      # the message stream, which is up to the application protocol to agree on.
+      #
+      # @return [void]
+      def rekey_encryption
+        transport_cipher_state(:encrypt).rekey
+        nil
+      end
 
-        @cipher_state_decrypt.decrypt_with_ad('', data)
+      # Replaces the key used by #decrypt with REKEY(k). See #rekey_encryption.
+      #
+      # @return [void]
+      def rekey_decryption
+        transport_cipher_state(:decrypt).rekey
+        nil
       end
 
       def validate_psk!
+        raise Noise::Exceptions::NoisePSKError, 'psks are not set.' if @psks.nil?
         # Invalid psk length! Has to be 32 bytes long
-        raise Noise::Exceptions::NoisePSKError if @psks.any? { |psk| psk.bytesize != 32 }
-        raise Noise::Exceptions::NoisePSKError if @protocol.pattern.psk_count != @psks.count
+        raise Noise::Exceptions::NoisePSKError, 'psks have to be 32 bytes long.' if
+          @psks.any? { |psk| psk.bytesize != 32 }
+
+        return if @protocol.pattern.psk_count == @psks.count
+
+        raise Noise::Exceptions::NoisePSKError,
+              "This protocol needs #{@protocol.pattern.psk_count} psks, got #{@psks.count}."
       end
 
       def missing_keypairs?
@@ -124,6 +188,23 @@ module Noise
         @symmetric_state = nil
         @cipher_state_handshake = nil
       end
+
+      private
+
+      # Returns the transport CipherState of the given direction.
+      #
+      # One-way patterns leave the direction the caller cannot use as nil, so the absence of a
+      # cipher state is reported the same way as a handshake that has not finished yet.
+      #
+      # @param [Symbol] direction :encrypt or :decrypt.
+      def transport_cipher_state(direction)
+        raise Noise::Exceptions::NoiseHandshakeError unless @handshake_finished
+
+        cipher_state = direction == :encrypt ? @cipher_state_encrypt : @cipher_state_decrypt
+        raise Noise::Exceptions::NoiseHandshakeError, "This party cannot #{direction} messages." unless cipher_state
+
+        cipher_state
+      end
     end
   end
 end

data/lib/noise/exceptions/invalid_nonce_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    # Raised when a nonce given to CipherState#nonce= is not an unsigned 64-bit integer.
+    class InvalidNonceError < RuntimeError
+    end
+  end
+end

data/lib/noise/exceptions/message_too_long_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+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.
+    class MessageTooLongError < StandardError
+    end
+  end
+end

data/lib/noise/exceptions.rb

@@ -4,8 +4,10 @@ module Noise
   module Exceptions
     autoload :DecryptError, 'noise/exceptions/decrypt_error'
     autoload :EncryptError, 'noise/exceptions/encrypt_error'
+    autoload :InvalidNonceError, 'noise/exceptions/invalid_nonce_error'
     autoload :InvalidPublicKeyError, 'noise/exceptions/invalid_public_key_error'
     autoload :MaxNonceError, 'noise/exceptions/max_nonce_error'
+    autoload :MessageTooLongError, 'noise/exceptions/message_too_long_error'
     autoload :MissingDependencyError, 'noise/exceptions/missing_dependency_error'
     autoload :ProtocolNameError, 'noise/exceptions/protocol_name_error'
     autoload :NoiseHandshakeError, 'noise/exceptions/noise_handshake_error'

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

@@ -12,8 +12,20 @@ module Noise
           Noise::Key.new(ECDSA::Format::IntegerOctetString.encode(private_key, 32), public_key.to_bytes)
         end
 
+        # Computes the X25519 shared secret for the given remote public key.
+        #
+        # RbNaCl reports a public key it cannot use in two different ways: a wrong length
+        # raises RbNaCl::LengthError, and an all-zero or low-order point raises
+        # RbNaCl::CryptoError. Both are translated to InvalidPublicKeyError so that a
+        # caller handling a peer-supplied key rescues the same class for every DH function.
+        # The length is checked before the call so that RbNaCl::LengthError raised for a
+        # malformed private key keeps propagating as itself.
         def dh(private_key, public_key)
+          raise Noise::Exceptions::InvalidPublicKeyError, public_key unless public_key.bytesize == DHLEN
+
           RbNaCl::GroupElement.new(public_key).mult(private_key).to_bytes
+        rescue RbNaCl::CryptoError
+          raise Noise::Exceptions::InvalidPublicKeyError, public_key
         end
 
         def dhlen

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

@@ -1,26 +1,43 @@
 # frozen_string_literal: true
 
-Noise.require_optional('ed448') { Ed448.init }
-
 module Noise
   module Functions
     module DH
+      # The 448 DH function of the Noise specification, which is X448 as defined by RFC 7748 and
+      # not the Ed448 signature scheme the class name suggests. The name is kept because it is what
+      # Protocol::DH maps '448' to and what callers reference.
+      #
+      # OpenSSL implements X448 and exposes it through the raw key interface, so this function needs
+      # no gem and no system library beyond the OpenSSL that AesGcm and the HMAC helpers already use.
       class ED448
-        # Ed448::X448::X448_PRIVATE_BYTES, spelled out so this file loads without the gem.
         DHLEN = 56
 
-        def initialize
-          Noise.optional_dependency!('ed448')
-        end
+        # The name OpenSSL knows the curve by. Ed448 is a different algorithm, and asking for it
+        # here would produce a signing key rather than one that can derive a shared secret.
+        ALGORITHM = 'X448'
 
         def generate_keypair
-          private_key = SecureRandom.random_bytes(DHLEN)
-          public_key = Ed448::X448.derive_public_key(private_key)
-          Noise::Key.new(private_key, public_key)
+          pkey = OpenSSL::PKey.generate_key(ALGORITHM)
+          Noise::Key.new(pkey.raw_private_key, pkey.raw_public_key)
         end
 
+        # Computes the X448 shared secret for the given remote public key.
+        #
+        # OpenSSL reports a public key it cannot use as OpenSSL::PKey::PKeyError, both when the key
+        # is not DHLEN bytes and when the derivation would produce the all-zero output that RFC 7748
+        # requires be rejected. Both are translated to InvalidPublicKeyError so that a caller
+        # handling a peer-supplied key rescues the same class for every DH function. The local key
+        # is built outside the rescue so that a malformed private key keeps propagating as
+        # PKeyError instead of being reported as the peer's fault.
         def dh(private_key, public_key)
-          Ed448::X448.dh(public_key, private_key)
+          raise Noise::Exceptions::InvalidPublicKeyError, public_key unless public_key.bytesize == DHLEN
+
+          local = OpenSSL::PKey.new_raw_private_key(ALGORITHM, private_key)
+          begin
+            local.derive(OpenSSL::PKey.new_raw_public_key(ALGORITHM, public_key))
+          rescue OpenSSL::PKey::PKeyError
+            raise Noise::Exceptions::InvalidPublicKeyError, public_key
+          end
         end
 
         def dhlen
@@ -28,8 +45,8 @@ module Noise
         end
 
         def self.from_private(private_key)
-          public_key = Ed448::X448.derive_public_key(private_key)
-          Noise::Key.new(private_key, public_key)
+          pkey = OpenSSL::PKey.new_raw_private_key(ALGORITHM, private_key)
+          Noise::Key.new(private_key, pkey.raw_public_key)
         end
       end
     end

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

@@ -6,6 +6,10 @@ module Noise
   module Functions
     module DH
       class Secp256k1
+        # Length of a compressed secp256k1 point. libsecp256k1 also accepts the 65-byte
+        # uncompressed form, but Noise exchanges only the compressed one.
+        DHLEN = 33
+
         def initialize
           Noise.optional_dependency!('secp256k1')
         end
@@ -20,7 +24,16 @@ module Noise
           )
         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.
         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
@@ -28,7 +41,7 @@ module Noise
         end
 
         def dhlen
-          33
+          DHLEN
         end
 
         def self.from_private(private_key)

data/lib/noise/state/cipher_state.rb

@@ -29,7 +29,17 @@ module Noise
         !@k.nil?
       end
 
+      # Sets n, the nonce the next encrypt_with_ad or decrypt_with_ad call uses. This is SetNonce()
+      # of the Noise spec, needed to decrypt transport messages that arrive out of order.
+      #
+      # The value is checked here because the ciphers pack n into 8 bytes: a value outside the
+      # unsigned 64-bit range silently produces a wrong nonce instead of an error.
+      #
+      # @param [Integer] nonce a value between 0 and MAX_NONCE.
+      # @raise [Noise::Exceptions::InvalidNonceError] if nonce is out of that range.
       def nonce=(nonce)
+        raise Noise::Exceptions::InvalidNonceError unless nonce.is_a?(Integer) && nonce.between?(0, MAX_NONCE)
+
         @n = nonce
       end
 
@@ -56,6 +66,9 @@ module Noise
         plaintext
       end
 
+      # Replaces k with REKEY(k). n is left as it is, as the Noise spec requires.
+      #
+      # @return [String] the new 32 bytes key.
       def rekey
         @k = @cipher.rekey(@k)
       end

data/lib/noise/version.rb

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

data/lib/noise.rb

@@ -4,6 +4,7 @@ require 'noise/version'
 
 require 'ecdsa'
 require 'logger'
+require 'openssl'
 require 'rbnacl'
 require 'ruby_hmac'
 require 'securerandom'

data/noise.gemspec

@@ -35,10 +35,13 @@ Gem::Specification.new do |spec|
   # 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.
   spec.add_development_dependency 'blake3'
-  spec.add_development_dependency 'ed448'
   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.
+  spec.add_runtime_dependency 'openssl', '>= 3.0'
   spec.add_runtime_dependency 'rbnacl'
   spec.add_runtime_dependency 'ruby-hmac'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: noise-ruby
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Hajime Yamaguchi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: ed448
+  name: secp256k1-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,13 +137,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: secp256k1-ruby
+  name: ecdsa
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -151,19 +151,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: ecdsa
+  name: openssl
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rbnacl
   requirement: !ruby/object:Gem::Requirement
@@ -220,8 +220,10 @@ files:
 - lib/noise/exceptions.rb
 - lib/noise/exceptions/decrypt_error.rb
 - lib/noise/exceptions/encrypt_error.rb
+- lib/noise/exceptions/invalid_nonce_error.rb
 - lib/noise/exceptions/invalid_public_key_error.rb
 - lib/noise/exceptions/max_nonce_error.rb
+- lib/noise/exceptions/message_too_long_error.rb
 - lib/noise/exceptions/missing_dependency_error.rb
 - lib/noise/exceptions/noise_handshake_error.rb
 - lib/noise/exceptions/noise_psk_error.rb