noise-ruby 0.10.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cffe6f7ffc789455f6b27bf3246cce8870cf57600e551d8f8edf91437ccd7afd
-  data.tar.gz: f9c83042c8aa626a7a6e81ad62dd64ccf6c5515c33f1f64e12904b2ffcaa5fa9
+  metadata.gz: 4a3f4c1b701c2de6240cb5fc0fb2410e1790c390142b256e6b822af4fa327cef
+  data.tar.gz: a57735c978c1227262bc122e869aa6866e76a943654981fb57411d70cab34f80
 SHA512:
-  metadata.gz: a1c2fe0e62f0939b48052d348511a97cedcf222316491d43f1d6128d146108587eedeb972d1fbce732a15aa7b73684f76e013e7a57c2f27fe85a3f7331a140bd
-  data.tar.gz: fa9aea76917642726a8688fbc7b3d0f5fb9b32d1fe058ba7fbf81757d9754da92c1809633378b518753cf105e25e452f65975cfbef0f9b679ec12c68c5198d80
+  metadata.gz: 915a8da57226d70b24a5a7289325eba851d1e7e40c7d7ef0d0081411008f388a78eec00a760fe92f05ef82ccd707bc776bc8d4d385a6e14d1c3184714b7437b3
+  data.tar.gz: dd660c060e00d5c1d0c0e89c434743d6e91749ba09d16a8217e0031c641a2788636ba0fbf64bcfcc031ed84c75e290e3526d95af40fc6518a0211b1e292f7d77

data/.dockerignore

@@ -0,0 +1,8 @@
+# Gemfile.lock is deliberately not listed: the Dockerfile copies it so the image installs the same
+# versions the mounted working tree will ask for.
+.git/
+.rspec_status
+.ruby-lsp/
+coverage/
+pkg/
+tmp/

data/.github/workflows/ruby.yml

@@ -14,17 +14,43 @@ on:
     branches: [ master ]
 
 jobs:
-  test:
-
+  lint:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby:
+          - '3.3'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Lint code for consistent style
+        run: bundle exec rubocop -f github
 
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby:
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 2.6
-    - name: Install dependencies
-      run: bundle install
-    - name: Run tests
-      run: bundle exec rake
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rspec spec
+

data/.gitignore

@@ -10,3 +10,6 @@
 
 # rspec failure tracking
 .rspec_status
+
+AGENTS.md
+CLAUDE.md

data/.rubocop.yml

@@ -1,15 +1,11 @@
-Metrics/BlockLength:
+require:
+  - rubocop-rspec
+Metrics:
   Enabled: false
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 120
 
-Metrics/MethodLength:
-  Max: 30
-
-Metrics/AbcSize:
-  Max: 20
-
 Style/Documentation:
   Enabled: false
 
@@ -23,7 +19,30 @@ Style/WordArray:
   MinSize: 100
 
 AllCops:
-  TargetRubyVersion: 2.4.1
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
     MinNameLength: 1
+
+RSpec:
+  Exclude:
+    - "spec/factories/*"
+RSpec/AnyInstance:
+  Enabled: false
+RSpec/ContextWording:
+  Enabled: false
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+RSpec/NamedSubject:
+  Enabled: false
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+RSpec/SpecFilePathFormat:
+  Enabled: false
+RSpec/IndexedLet:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-2.7.6
+3.3.5

data/Dockerfile

@@ -0,0 +1,29 @@
+# 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
+
+# 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.
+# git: noise.gemspec calls `git ls-files` while the gemspec is evaluated.
+RUN apt-get update -qq \
+ && apt-get install -y --no-install-recommends build-essential git libsodium23 cargo \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /work
+
+# Install the gems from the dependency definitions alone so the layer stays cached when only
+# the source changes. Gems live in BUNDLE_PATH (/usr/local/bundle), outside /work, so mounting
+# the working tree over /work at run time does not hide them.
+#
+# Gemfile.lock is gitignored, hence the glob: it is copied when the host has one so the image
+# installs the exact versions the mounted lock will ask for at run time, and skipped otherwise.
+COPY Gemfile* noise.gemspec ./
+COPY lib/noise/version.rb lib/noise/version.rb
+RUN bundle install
+
+# Run with the working tree mounted:
+#   docker run --rm -v "$PWD":/work noise-dev
+#   docker run --rm -v "$PWD":/work noise-dev bundle exec rubocop
+CMD ["bundle", "exec", "rspec"]

data/Gemfile

@@ -4,11 +4,6 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Specify your gem's dependencies in noise.gemspec
+# 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.
 gemspec
-
-# Use secp256k1 as ecdh function
-# gem 'secp256k1-ruby'
-
-# Use blake3 as hash function
-# gem 'blake3'

data/README.md

@@ -47,18 +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
-
 If you use Secp256k1, you must install [libsecp256k1](https://github.com/bitcoin-core/secp256k1).
 
     $ git clone https://github.com/bitcoin-core/secp256k1
@@ -132,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,10 +3,15 @@
 module Noise
   module Connection
     class Base
-      attr_reader :protocol, :handshake_started, :handshake_finished, :handshake_hash, :handshake_state
-      attr_reader :cipher_state_encrypt, :cipher_state_decrypt, :cipher_state_handshake
+      # 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
       attr_accessor :psks, :prologue
-      attr_reader :s, :rs
 
       def initialize(name, keypairs: { s: nil, e: nil, rs: nil, re: nil })
         @protocol = Protocol.create(name)
@@ -27,11 +32,15 @@ module Noise
         @handshake_started = true
       end
 
+      # Restarts the handshake with a fallback pattern, carrying over the keys of the aborted one.
+      #
+      # The roles swap here: the party that wrote the aborted message now reads, and the one that
+      # failed to read it now writes. Both sides are already in that state, so @next_message is
+      # deliberately left as it is rather than reset through initialize_next_message.
       def fallback(fallback_name)
         @protocol = Protocol.create(fallback_name)
         @handshake_started = false
         @handshake_finished = false
-        # initialize_next_message
         @local_keypairs = { e: @handshake_state.e, s: @handshake_state.s }
         @remote_keys = { re: @handshake_state.re, rs: @handshake_state.rs }
         start_handshake
@@ -55,10 +64,13 @@ 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.'
+        end
+
         @next_message = :read
         buffer = +''
-        result = @handshake_state.write_message(payload, buffer)
-        @handshake_finished = true if result
+        @handshake_finished = @handshake_state.write_message(payload, buffer)
         buffer
       end
 
@@ -67,33 +79,95 @@ 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
 
         @next_message = :write
         buffer = +''
-        result = @handshake_state.read_message(data, buffer)
-        @handshake_finished = true if result
+        @handshake_finished = @handshake_state.read_message(data, buffer)
         buffer
       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 valid_keypairs?
+      def missing_keypairs?
         keypairs = @local_keypairs.merge(@remote_keys)
         @protocol.pattern.required_keypairs(initiator?).any? { |keypair| !keypairs[keypair] }
       end
@@ -101,7 +175,7 @@ module Noise
       def validate
         validate_psk! if @protocol.psk?
 
-        raise Noise::Exceptions::NoiseValidationError if valid_keypairs?
+        raise Noise::Exceptions::NoiseValidationError if missing_keypairs?
 
         true
       end
@@ -114,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/decrypt_error.rb

@@ -4,6 +4,7 @@ module Noise
   module Exceptions
     class DecryptError < StandardError
       def initialize(cause)
+        super
         @cause = cause
       end
     end

data/lib/noise/exceptions/encrypt_error.rb

@@ -4,6 +4,7 @@ module Noise
   module Exceptions
     class EncryptError < StandardError
       def initialize(cause)
+        super
         @cause = cause
       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/invalid_public_key_error.rb

@@ -3,7 +3,10 @@
 module Noise
   module Exceptions
     class InvalidPublicKeyError < StandardError
+      attr_reader :public_key
+
       def initialize(public_key)
+        super("Invalid public key: #{public_key.unpack1('H*')}")
         @public_key = public_key
       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/missing_dependency_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Noise
+  module Exceptions
+    class MissingDependencyError < RuntimeError
+    end
+  end
+end

data/lib/noise/exceptions.rb

@@ -4,8 +4,11 @@ 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'
     autoload :NoiseValidationError, 'noise/exceptions/noise_validation_error'

data/lib/noise/functions/cipher/aes_gcm.rb

@@ -7,28 +7,29 @@ module Noise
         MAX_NONCE = 2**64 - 1
 
         def encrypt(k, n, ad, plaintext)
-          cipher = OpenSSL::Cipher::AES.new(256, :GCM).encrypt
+          cipher = OpenSSL::Cipher.new('aes-256-gcm').encrypt
           cipher.key = k
           cipher.iv = nonce_to_bytes(n)
           cipher.auth_data = ad
-          cipher.update(plaintext) + cipher.final + cipher.auth_tag
+          update(cipher, plaintext) + cipher.final + cipher.auth_tag
         rescue OpenSSL::Cipher::CipherError => e
           raise Noise::Exceptions::EncryptError, "Encrypt failed. #{e.message}", e.backtrace
         end
 
         def decrypt(k, n, ad, ciphertext)
-          cipher = OpenSSL::Cipher::AES.new(256, :GCM).decrypt
+          cipher = OpenSSL::Cipher.new('aes-256-gcm').decrypt
           cipher.key = k
           cipher.iv = nonce_to_bytes(n)
           cipher.auth_data = ad
-          cipher.auth_tag = ciphertext[-16..-1]
-          cipher.update(ciphertext[0...-16]) + cipher.final
+          cipher.auth_tag = ciphertext[-16..]
+          update(cipher, ciphertext[0...-16]) + cipher.final
         rescue OpenSSL::Cipher::CipherError => e
           raise Noise::Exceptions::DecryptError, "Decrpyt failed. #{e.message}", e.backtrace
         end
 
+        # 4 zero bytes followed by n as a big-endian 64 bit integer.
         def nonce_to_bytes(n)
-          "\x00" * 4 + format('%16x', n).htb
+          "\x00" * 4 + [n].pack('Q>')
         end
 
         # Returns a new 32-byte cipher key as a pseudorandom function of k.
@@ -40,6 +41,16 @@ module Noise
         def rekey(k)
           encrypt(k, MAX_NONCE, '', "\x00" * 32)[0...32]
         end
+
+        private
+
+        # A zero-length payload is normal in a Noise message, but the openssl gem shipped with
+        # Ruby 3.0 raises ArgumentError('data must not be empty') instead of returning ''.
+        def update(cipher, data)
+          return String.new if data.empty?
+
+          cipher.update(data)
+        end
       end
     end
   end

data/lib/noise/functions/cipher/cha_cha_poly.rb

@@ -20,8 +20,9 @@ module Noise
           raise Noise::Exceptions::DecryptError, "Decrpyt failed. #{e.message}", e.backtrace
         end
 
+        # 4 zero bytes followed by n as a little-endian 64 bit integer.
         def nonce_to_bytes(n)
-          "\x00" * 4 + format('%16x', n).htb.reverse
+          "\x00" * 4 + [n].pack('Q<')
         end
 
         # Returns a new 32-byte cipher key as a pseudorandom function of k.
@@ -31,7 +32,7 @@ module Noise
         # zerolen is a zero-length byte sequence, and zeros is a sequence of
         # 32 bytes filled with zeros.
         def rekey(k)
-          encrypt(k, MAX_NONCE, '', "\x00" * 32)[0..32]
+          encrypt(k, MAX_NONCE, '', "\x00" * 32)[0...32]
         end
       end
     end

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,21 +1,43 @@
 # frozen_string_literal: true
 
-require_force('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
-        DHLEN = Ed448::X448::X448_PRIVATE_BYTES
+        DHLEN = 56
+
+        # 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
@@ -23,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