ruby_smb 3.3.22 → 3.3.25

data/lib/ruby_smb/nbss/node_status.rb

@@ -0,0 +1,137 @@
+require 'socket'
+require 'ipaddr'
+require 'securerandom'
+
+module RubySMB
+  module Nbss
+    # Pure-Ruby implementation of `nmblookup -A <ip>`: sends an NBNS Node
+    # Status Request (RFC 1002 4.2.17) over UDP/137 and returns the
+    # server's name table.
+    #
+    # No external binaries are invoked. Compare to Samba's `nmblookup`,
+    # which shells out and requires the `samba-common-bin` package to be
+    # installed.
+    module NodeStatus
+      NBNS_PORT = 137
+
+      # Default per-attempt receive timeout, in seconds.
+      DEFAULT_TIMEOUT = 2.0
+
+      # Default number of attempts before giving up.
+      DEFAULT_RETRIES = 3
+
+      # One entry in the returned name table.
+      #
+      # @!attribute [rw] name [String] the NetBIOS name (trimmed)
+      # @!attribute [rw] suffix [Integer] 1-byte NetBIOS suffix
+      # @!attribute [rw] group [Boolean] true for a group name, false for unique
+      # @!attribute [rw] active [Boolean] true if the name is registered
+      Entry = Struct.new(:name, :suffix, :group, :active) do
+        def unique?
+          !group
+        end
+
+        # Human-readable form like `WIN95            <20> UNIQUE ACTIVE`.
+        def to_s
+          flags = [group ? 'GROUP' : 'UNIQUE', active ? 'ACTIVE' : 'INACTIVE'].join(' ')
+          format('%-16s <%02X> %s', name, suffix, flags)
+        end
+      end
+
+      # Query a host for its NetBIOS name table.
+      #
+      # NBNS is IPv4-only and this is a unicast query, so `host` must be a
+      # numeric IPv4 address (e.g. `10.0.0.1`). A hostname is rejected because
+      # replies are matched against the numeric peer address returned by
+      # `recvfrom`, which a hostname would never equal.
+      #
+      # @param host [String] target IPv4 address (unicast — no broadcast)
+      # @param port [Integer] destination UDP port (default 137)
+      # @param timeout [Numeric] per-attempt receive timeout in seconds
+      # @param retries [Integer] total number of attempts
+      # @param udp_socket [UDPSocket, Rex::Socket::Udp] caller-owned UDP socket.
+      #   The caller is responsible for binding and closing it. It must
+      #   implement `#send(mesg, flags, host, port)` and `#recvfrom(maxlen)`,
+      #   and leave `do_not_reverse_lookup` at its default so `recvfrom` does
+      #   not perform a reverse DNS lookup per datagram.
+      # @return [Array<Entry>, nil] the name table, or nil on timeout/parse failure
+      # @raise [ArgumentError] if `host` is not a numeric IPv4 address
+      def self.query(host, port: NBNS_PORT, timeout: DEFAULT_TIMEOUT,
+                     retries: DEFAULT_RETRIES, udp_socket:)
+        expected_address = begin
+          IPAddr.new(host).native
+        rescue IPAddr::InvalidAddressError
+          raise ArgumentError, "host must be an IPv4 address, got #{host.inspect}"
+        end
+        raise ArgumentError, "NBNS is IPv4-only, got #{host.inspect}" unless expected_address.ipv4?
+
+        request = NodeStatusRequest.new(transaction_id: SecureRandom.random_number(0x10000))
+        bytes = request.to_binary_s
+
+        retries.times do
+          udp_socket.send(bytes, 0, host, port)
+          next unless IO.select([udp_socket], nil, nil, timeout)
+
+          data, addr = udp_socket.recvfrom(4096)
+          next if data.nil? || data.empty?
+          next unless source_matches?(addr, expected_address)
+
+          response = NodeStatusResponse.read(data)
+          # Reject anything that isn't the response to our own query.
+          next unless response.transaction_id.to_i == request.transaction_id.to_i
+          next unless response.response.to_i == 1
+          next unless response.rr_type.to_i == NodeStatusRequest::QUESTION_TYPE_NBSTAT
+
+          return entries_from(response)
+        rescue IOError, EOFError, SystemCallError
+          next
+        end
+        nil
+      end
+
+      # Return the unique file-server name (suffix 0x20) from a host, or nil
+      # if the name table doesn't contain one. Convenience helper for the
+      # common case of "give me this host's file-server name."
+      #
+      # @param host [String] target IPv4 address
+      # @param kwargs [Hash] forwarded to {.query}
+      # @return [String, nil]
+      def self.file_server_name(host, **kwargs)
+        entries = query(host, **kwargs) or return nil
+        entry = entries.find { |e| e.suffix == 0x20 && e.unique? }
+        entry&.name
+      end
+
+      def self.entries_from(response)
+        response.node_names.map do |n|
+          Entry.new(
+            n.netbios_name.to_s.rstrip,
+            n.suffix.to_i,
+            n.group?,
+            n.active?
+          )
+        end
+      end
+      private_class_method :entries_from
+
+      # Accept a reply only when it comes from the queried address. A UDP
+      # socket's `#recvfrom` always returns the sender as
+      # `[address_family, port, host, numeric_host]`, so the numeric address
+      # lives at `addr[3]`, which is compared against the normalized target.
+      # Any datagram whose source cannot be determined (not an Array, or a nil
+      # numeric address) is rejected — an unverifiable source is untrusted.
+      def self.source_matches?(addr, expected_address)
+        source = addr.is_a?(Array) ? addr[3] : nil
+        return false if source.nil?
+
+        source_address = begin
+          IPAddr.new(source).native
+        rescue IPAddr::InvalidAddressError
+          return false
+        end
+        source_address == expected_address
+      end
+      private_class_method :source_matches?
+    end
+  end
+end

data/lib/ruby_smb/nbss/node_status_request.rb

@@ -0,0 +1,38 @@
+require 'ruby_smb/nbss/name_service_header_flags'
+
+module RubySMB
+  module Nbss
+    # NetBIOS Name Service (NBNS) Node Status Request packet, as defined in
+    # [RFC 1002 4.2.17](https://tools.ietf.org/html/rfc1002#section-4.2.17).
+    # Sent over UDP to port 137 to retrieve a host's NetBIOS name table.
+    class NodeStatusRequest < BinData::Record
+      # NBSTAT question type, RFC 1002 4.2.1.3.
+      QUESTION_TYPE_NBSTAT = 0x0021
+      # Internet class.
+      QUESTION_CLASS_IN    = 0x0001
+      # RFC 1002 4.2.17: a node status query always asks for the wildcard name,
+      # 16 bytes of 0x2A ('*') padded with 0x00.
+      WILDCARD_NAME = '*'.ljust(16, "\x00").freeze
+
+      endian :big
+
+      # 12-byte NBNS header (RFC 1002 4.2.1.1 and 4.2.1.2). The second word is
+      # R | OPCODE | NM_FLAGS | RCODE.
+      uint16                    :transaction_id, label: 'Transaction ID'
+      bit1                      :response,       label: 'Response',    initial_value: 0
+      bit4                      :opcode,         label: 'Opcode',      initial_value: 0
+      name_service_header_flags :nm_flags,       label: 'Flags'
+      bit4                      :rcode,          label: 'Result Code', initial_value: 0
+      uint16                    :qdcount,        label: 'QDCount', initial_value: 1
+      uint16                    :ancount,        label: 'ANCount', initial_value: 0
+      uint16                    :nscount,        label: 'NSCount', initial_value: 0
+      uint16                    :arcount,        label: 'ARCount', initial_value: 0
+
+      # Question section. For a node status query this is always the wildcard
+      # NetBIOS name, L1-encoded.
+      netbios_name :question_name,  label: 'Question Name', initial_value: WILDCARD_NAME
+      uint16       :question_type,  label: 'Question Type',  initial_value: QUESTION_TYPE_NBSTAT
+      uint16       :question_class, label: 'Question Class', initial_value: QUESTION_CLASS_IN
+    end
+  end
+end

data/lib/ruby_smb/nbss/node_status_response.rb

@@ -0,0 +1,85 @@
+require 'ruby_smb/nbss/name_service_header_flags'
+
+module RubySMB
+  module Nbss
+    # The NAME_FLAGS field for each Node Status Response name entry.
+    class NodeStatusNameFlags < BinData::Record
+      endian :big
+
+      bit1 :group,           label: 'Group Name',      initial_value: 0
+      bit2 :owner_node_type, label: 'Owner Node Type', initial_value: 0
+      bit1 :deregister,      label: 'Deregister',      initial_value: 0
+      bit1 :conflict,        label: 'Conflict',        initial_value: 0
+      bit1 :active,          label: 'Active',          initial_value: 0
+      bit1 :permanent,       label: 'Permanent',       initial_value: 0
+      bit9 :reserved,        label: 'Reserved',        initial_value: 0
+    end
+
+    # Single entry in the NODE_NAME_ARRAY of a Node Status Response,
+    # as defined in [RFC 1002 4.2.18](https://tools.ietf.org/html/rfc1002#section-4.2.18).
+    # Fixed 18-byte layout (15-byte name, 1-byte suffix, 16-bit flags).
+    class NodeStatusName < BinData::Record
+      # NAME_FLAGS bits (RFC 1002 4.2.18).
+      GROUP_BIT = 0x8000   # 1 = group name, 0 = unique name
+      ACTIVE_BIT = 0x0400  # 1 = name registered
+
+      endian :big
+
+      string :netbios_name, label: 'NetBIOS Name', length: 15
+      uint8  :suffix,       label: 'Suffix'
+      node_status_name_flags :name_flags, label: 'Name Flags'
+
+      def group?
+        (raw_name_flags & GROUP_BIT) != 0
+      end
+
+      def unique?
+        !group?
+      end
+
+      def active?
+        (raw_name_flags & ACTIVE_BIT) != 0
+      end
+
+      private
+
+      # The 16-bit NAME_FLAGS field as a raw integer, for masking against
+      # the GROUP_BIT / ACTIVE_BIT constants.
+      def raw_name_flags
+        name_flags.to_binary_s.unpack1('n')
+      end
+    end
+
+    # NetBIOS Name Service (NBNS) Node Status Response packet, as defined in
+    # [RFC 1002 4.2.18](https://tools.ietf.org/html/rfc1002#section-4.2.18).
+    # Received over UDP from port 137 in reply to a {NodeStatusRequest}.
+    # Does not decode the trailing STATISTICS field; callers only need the
+    # name table.
+    class NodeStatusResponse < BinData::Record
+      endian :big
+
+      # 12-byte NBNS header. The second word is R | OPCODE | NM_FLAGS | RCODE.
+      uint16                    :transaction_id, label: 'Transaction ID'
+      bit1                      :response,       label: 'Response',    initial_value: 0
+      bit4                      :opcode,         label: 'Opcode',      initial_value: 0
+      name_service_header_flags :nm_flags,       label: 'Flags'
+      bit4                      :rcode,          label: 'Result Code', initial_value: 0
+      uint16                    :qdcount,        label: 'QDCount'
+      uint16                    :ancount,        label: 'ANCount'
+      uint16                    :nscount,        label: 'NSCount'
+      uint16                    :arcount,        label: 'ARCount'
+
+      # Answer section. Microsoft's implementation omits the question-echo,
+      # so the owner name appears directly after the header.
+      netbios_name :owner_name, label: 'Owner Name'
+      uint16 :rr_type,          label: 'RR Type'
+      uint16 :rr_class,         label: 'RR Class'
+      uint32 :ttl,              label: 'TTL'
+      uint16 :rdlength,         label: 'RDLENGTH'
+
+      # RDATA begins here. NODE_NAME_ARRAY is preceded by an 8-bit count.
+      uint8  :num_names,        label: 'Number of Names'
+      array  :node_names, type: :node_status_name, initial_length: :num_names
+    end
+  end
+end

data/lib/ruby_smb/nbss.rb

@@ -9,9 +9,20 @@ module RubySMB
     RETARGET_SESSION_RESPONSE = 0x84
     SESSION_KEEP_ALIVE        = 0x85
 
+    # NBSS negative session response error codes (RFC 1002 section 4.3.6)
+    NOT_LISTENING_ON_CALLED_NAME       = 0x80
+    NOT_LISTENING_FOR_CALLING_NAME     = 0x81
+    CALLED_NAME_NOT_PRESENT            = 0x82
+    CALLED_NAME_INSUFFICIENT_RESOURCES = 0x83
+    UNSPECIFIED_ERROR                  = 0x8F
+
     require 'ruby_smb/nbss/netbios_name'
     require 'ruby_smb/nbss/session_header'
     require 'ruby_smb/nbss/session_request'
     require 'ruby_smb/nbss/negative_session_response'
+    require 'ruby_smb/nbss/name_service_header_flags'
+    require 'ruby_smb/nbss/node_status_request'
+    require 'ruby_smb/nbss/node_status_response'
+    require 'ruby_smb/nbss/node_status'
   end
 end

data/lib/ruby_smb/peer_info.rb

@@ -3,8 +3,10 @@ module RubySMB
     # Extract and store useful information about the peer/server from the
     # NTLM Type 2 (challenge) TargetInfo fields.
     #
-    # @param target_info_str [String] the Target Info string
+    # @param target_info_str [String, nil] the Target Info string
     def store_target_info(target_info_str)
+      return if target_info_str.nil? || target_info_str.empty?
+
       target_info = Net::NTLM::TargetInfo.new(target_info_str)
       {
         Net::NTLM::TargetInfo::MSV_AV_NB_COMPUTER_NAME  => :@default_name,

data/lib/ruby_smb/version.rb

@@ -1,3 +1,3 @@
 module RubySMB
-  VERSION = '3.3.22'.freeze
+  VERSION = '3.3.25'.freeze
 end

data/ruby_smb.gemspec

@@ -43,6 +43,9 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'rubyntlm', '>= 0.6.5'
   spec.add_runtime_dependency 'windows_error', '>= 0.1.4'
   spec.add_runtime_dependency 'bindata', '2.4.15'
+  # 0.12 introduced the model `wrapper` DSL the SPNEGO types rely on; the upper Ruby versions resolve to a
+  # newer rasn1, while Ruby 2.7 caps at 0.13.1 (0.14+ needs Ruby 3.0), and both are known good.
+  spec.add_runtime_dependency 'rasn1', '>= 0.12'
   spec.add_runtime_dependency 'openssl-ccm'
   spec.add_runtime_dependency 'openssl-cmac'
 end

data/spec/lib/ruby_smb/client_spec.rb

@@ -742,6 +742,28 @@ RSpec.describe RubySMB::Client do
         allow(RubySMB::Nbss::SessionHeader).to receive(:read).and_raise(IOError)
         expect { client.session_request }.to raise_error(RubySMB::Error::InvalidPacket)
       end
+
+      describe 'NetBiosSessionService error propagates the error_code' do
+        it 'attaches the numeric NBSS error code to the raised exception' do
+          negative = RubySMB::Nbss::NegativeSessionResponse.new
+          negative.session_header.session_packet_type = RubySMB::Nbss::NEGATIVE_SESSION_RESPONSE
+          negative.error_code = RubySMB::Nbss::NOT_LISTENING_ON_CALLED_NAME
+          allow(dispatcher).to receive(:recv_packet).and_return(negative.to_binary_s)
+          expect { client.session_request('OTHERNAME') }.to raise_error(RubySMB::Error::NetBiosSessionService) do |e|
+            expect(e.error_code.to_i).to eq(RubySMB::Nbss::NOT_LISTENING_ON_CALLED_NAME)
+          end
+        end
+
+        it 'reports CALLED_NAME_NOT_PRESENT so the caller can resolve and retry' do
+          negative = RubySMB::Nbss::NegativeSessionResponse.new
+          negative.session_header.session_packet_type = RubySMB::Nbss::NEGATIVE_SESSION_RESPONSE
+          negative.error_code = RubySMB::Nbss::CALLED_NAME_NOT_PRESENT
+          allow(dispatcher).to receive(:recv_packet).and_return(negative.to_binary_s)
+          expect { client.session_request }.to raise_error(RubySMB::Error::NetBiosSessionService) do |e|
+            expect(e.error_code.to_i).to eq(RubySMB::Nbss::CALLED_NAME_NOT_PRESENT)
+          end
+        end
+      end
     end
 
     describe '#session_request_packet' do
@@ -776,6 +798,7 @@ RSpec.describe RubySMB::Client do
         expect(client.session_request_packet.called_name).to eq('*SMBSERVER      ')
       end
     end
+
   end
 
   context 'Protocol Negotiation' do
@@ -1614,6 +1637,15 @@ RSpec.describe RubySMB::Client do
           expect(smb1_client.session_key).to eq ntlm_client.session_key
         end
 
+        it 'continues authentication when the server advertises empty target info' do
+          challenge = Net::NTLM::Message.decode64(type2_string)
+          challenge.set_flag(:TARGET_INFO)
+          challenge.target_info = ''.b
+          allow(smb1_client).to receive(:smb1_type2_message).and_return(challenge.encode64)
+
+          expect(smb1_client.smb1_authenticate).to eq WindowsError::NTStatus::STATUS_SUCCESS
+        end
+
         it 'stores the OS version number from the challenge message' do
           smb1_client.smb1_authenticate
           expect(smb1_client.os_version).to eq '6.1.7601'
@@ -1860,6 +1892,15 @@ RSpec.describe RubySMB::Client do
           expect(smb2_client.session_key).to eq ntlm_client.session_key
         end
 
+        it 'continues authentication when the server advertises empty target info' do
+          challenge = Net::NTLM::Message.decode64(type2_string)
+          challenge.set_flag(:TARGET_INFO)
+          challenge.target_info = ''.b
+          allow(smb2_client).to receive(:smb2_type2_message).and_return(challenge.encode64)
+
+          expect(smb2_client.smb2_authenticate).to eq WindowsError::NTStatus::STATUS_SUCCESS
+        end
+
         it 'stores the OS version number from the challenge message' do
           smb2_client.smb2_authenticate
           expect(smb2_client.os_version).to eq '6.1.7601'
@@ -2068,6 +2109,25 @@ RSpec.describe RubySMB::Client do
         client.store_target_info(target_info_str)
       end
 
+      it 'preserves existing peer information when given empty target info' do
+        client.store_target_info(target_info_str)
+        expect { client.store_target_info(''.b) }.to_not change {
+          [client.default_name, client.default_domain, client.dns_host_name, client.dns_domain_name, client.dns_tree_name]
+        }
+      end
+
+      it 'accepts nil target info' do
+        expect { client.store_target_info(nil) }.to_not raise_error
+      end
+
+      it 'accepts empty target info encoded with an end-of-list marker' do
+        expect { client.store_target_info("\x00\x00\x00\x00".b) }.to_not raise_error
+      end
+
+      it 'rejects nonempty invalid target info' do
+        expect { client.store_target_info("\xff\xff\x00\x00".b) }.to raise_error(Net::NTLM::InvalidTargetDataError)
+      end
+
       it 'sets the expected Client\'s attribute' do
         client.store_target_info(target_info_str)
         expect(client.default_name).to eq 'TESTNAME'

data/spec/lib/ruby_smb/dcerpc/client_spec.rb

@@ -173,6 +173,14 @@ RSpec.describe RubySMB::Dcerpc::Client do
         expect(auth_client.process_ntlm_type2(type2_message)).to start_with("NTLMSSP\x00\x03\x00\x00\x00")
       end
 
+      it 'returns a type3 message when the server advertises empty target info' do
+        challenge = Net::NTLM::Message.parse(type2_message)
+        challenge.set_flag(:TARGET_INFO)
+        challenge.target_info = ''.b
+
+        expect(auth_client.process_ntlm_type2(challenge.serialize)).to start_with("NTLMSSP\x00\x03\x00\x00\x00")
+      end
+
       it 'stores the session key' do
         auth_client.process_ntlm_type2(type2_message)
         expect(auth_client.instance_variable_get(:@session_key).size).to eq(16)

data/spec/lib/ruby_smb/gss/provider/kerberos_spec.rb

@@ -0,0 +1,206 @@
+RSpec.describe RubySMB::Gss::Provider::Kerberos do
+  let(:server_client) { double('server_client', logger: Logger.new(IO::NULL)) }
+  # opaque stand-in for a real AP-REQ; this provider never interprets the payload
+  let(:ap_req) { "\x6e\x82\x01\x0a".b + Random.new(1).bytes(64) }
+  let(:mech_token) { RubySMB::Gss::Provider::Kerberos::TOK_ID_KRB_AP_REQ + ap_req }
+
+  subject(:provider) { RubySMB::Gss::Provider::Kerberos.new }
+
+  describe '#mech_types' do
+    it 'advertises both the standard and the Microsoft Kerberos mechanism' do
+      expect(provider.mech_types.map(&:oid)).to eq(
+        [RubySMB::Gss::OID_KERBEROS_5.oid, RubySMB::Gss::OID_MICROSOFT_KERBEROS_5.oid]
+      )
+    end
+
+    it 'reports support for both' do
+      expect(provider.supports_mech_type?(RubySMB::Gss::OID_KERBEROS_5)).to be true
+      expect(provider.supports_mech_type?(RubySMB::Gss::OID_MICROSOFT_KERBEROS_5)).to be true
+    end
+
+    it 'does not report support for other mechanisms' do
+      expect(provider.supports_mech_type?(RubySMB::Gss::OID_NTLMSSP)).to be false
+    end
+  end
+
+  describe '.token_id' do
+    # a GSS-API InitialContextToken, shaped as a Windows client actually sends one: the token id follows the
+    # mechanism OID rather than starting the token, and the framing around it is not valid ASN.1
+    let(:initial_context_token) do
+      "\x60\x82\x0c\x0e".b +
+        OpenSSL::ASN1::ObjectId.new('1.2.840.113554.1.2.2').to_der +
+        RubySMB::Gss::Provider::Kerberos::TOK_ID_KRB_AP_REQ +
+        "\x6e\x82\x0b\xfd".b
+    end
+
+    it 'reads the identifier from past the mechanism OID' do
+      expect(RubySMB::Gss::Provider::Kerberos.token_id(initial_context_token))
+        .to eq(RubySMB::Gss::Provider::Kerberos::TOK_ID_KRB_AP_REQ)
+    end
+
+    it 'handles a short form length' do
+      short = "\x60\x14".b + OpenSSL::ASN1::ObjectId.new('1.2.840.113554.1.2.2').to_der +
+              RubySMB::Gss::Provider::Kerberos::TOK_ID_KRB_AP_REP + "\x6f\x00".b
+      expect(RubySMB::Gss::Provider::Kerberos.token_id(short))
+        .to eq(RubySMB::Gss::Provider::Kerberos::TOK_ID_KRB_AP_REP)
+    end
+
+    it 'is nil for anything not shaped like an InitialContextToken' do
+      expect(RubySMB::Gss::Provider::Kerberos.token_id(nil)).to be_nil
+      expect(RubySMB::Gss::Provider::Kerberos.token_id('')).to be_nil
+      expect(RubySMB::Gss::Provider::Kerberos.token_id('short')).to be_nil
+      # a SEQUENCE rather than an InitialContextToken
+      expect(RubySMB::Gss::Provider::Kerberos.token_id("\x30\x82\x00\x05".b)).to be_nil
+    end
+
+    it 'is nil when no mechanism OID follows' do
+      expect(RubySMB::Gss::Provider::Kerberos.token_id("\x60\x04\x02\x01\x05\x00".b)).to be_nil
+    end
+  end
+
+  describe '#on_mech_token' do
+    it 'can be set with a block' do
+      provider.on_mech_token { |_token, _authenticator| :handled }
+      expect(provider.on_mech_token('token', nil)).to eq(:handled)
+    end
+
+    it 'can be set through the constructor' do
+      configured = RubySMB::Gss::Provider::Kerberos.new { |_token, _authenticator| :handled }
+      expect(configured.on_mech_token('token', nil)).to eq(:handled)
+    end
+
+    it 'is nil when no handler has been set' do
+      expect(provider.on_mech_token('token', nil)).to be_nil
+    end
+  end
+
+  # referenced explicitly; described_class would resolve to the authenticator inside this group
+  describe RubySMB::Gss::Provider::Kerberos::Authenticator do
+    subject(:authenticator) { provider.new_authenticator(server_client) }
+
+    describe '#process' do
+      context 'when building the advertisement' do
+        it 'offers the Kerberos mechanisms' do
+          expect(authenticator.process(nil).buffer).to eq(RubySMB::Gss.gss_neg_token_init(provider.mech_types))
+        end
+
+        it 'succeeds' do
+          expect(authenticator.process(nil).nt_status).to eq(WindowsError::NTStatus::STATUS_SUCCESS)
+        end
+      end
+
+      context 'with a mechanism token' do
+        it 'passes the token to the handler' do
+          received = nil
+          provider.on_mech_token { |token, _authenticator| received = token; nil }
+          authenticator.process(neg_token_init(mech_token))
+          expect(received).to eq(mech_token)
+        end
+
+        it 'does not alter the token, so a forwarded ticket stays valid' do
+          received = nil
+          provider.on_mech_token { |token, _authenticator| received = token; nil }
+          authenticator.process(neg_token_init(mech_token))
+          expect(received).to eq(mech_token)
+          expect(received[2..]).to eq(ap_req)
+        end
+
+        it 'records the token on the authenticator' do
+          authenticator.process(neg_token_init(mech_token))
+          expect(authenticator.mech_token).to eq(mech_token)
+        end
+
+        it 'returns whatever the handler decides' do
+          expected = RubySMB::Gss::Provider::Result.new(nil, WindowsError::NTStatus::STATUS_SUCCESS)
+          provider.on_mech_token { |_token, _authenticator| expected }
+          expect(authenticator.process(neg_token_init(mech_token))).to be(expected)
+        end
+
+        it 'refuses the attempt when no handler is set' do
+          # nothing here can validate a ticket, so the attempt must not silently succeed
+          result = authenticator.process(neg_token_init(mech_token))
+          expect(result.nt_status).to eq(WindowsError::NTStatus::STATUS_LOGON_FAILURE)
+        end
+
+        it 'refuses the attempt when the handler returns something that is not a Result' do
+          # the session setup path calls nt_status on the result, so a non-Result (e.g. a boolean from a naive
+          # handler) must be refused here rather than handed on to crash the caller
+          provider.on_mech_token { |_token, _authenticator| true }
+          result = authenticator.process(neg_token_init(mech_token))
+          expect(result).to be_a(RubySMB::Gss::Provider::Result)
+          expect(result.nt_status).to eq(WindowsError::NTStatus::STATUS_LOGON_FAILURE)
+        end
+
+        it 'accepts a token carried in a continuation' do
+          received = nil
+          provider.on_mech_token { |token, _authenticator| received = token; nil }
+          authenticator.process(RubySMB::Gss.gss_type3(mech_token))
+          expect(received).to eq(mech_token)
+        end
+      end
+
+      context 'with a malformed request' do
+        it 'returns nil rather than raising' do
+          expect(authenticator.process('not asn1 at all')).to be_nil
+        end
+
+        it 'returns nil when there is no mechanism token' do
+          expect(authenticator.process(neg_token_init(nil))).to be_nil
+        end
+      end
+    end
+
+    describe '#reset!' do
+      it 'forgets the recorded token' do
+        authenticator.process(neg_token_init(mech_token))
+        expect(authenticator.mech_token).to_not be_nil
+        authenticator.reset!
+        expect(authenticator.mech_token).to be_nil
+      end
+    end
+  end
+
+  describe 'alongside NTLM' do
+    let(:ntlm_provider) { RubySMB::Gss::Provider::NTLM.new.tap { |p| p.put_account('RubySMB', 'password') } }
+    let(:multi) { RubySMB::Gss::Provider::Multi.new([provider, ntlm_provider]) }
+
+    it 'is offered ahead of NTLM' do
+      expect(multi.mech_types.map(&:oid)).to eq(
+        [
+          RubySMB::Gss::OID_KERBEROS_5.oid,
+          RubySMB::Gss::OID_MICROSOFT_KERBEROS_5.oid,
+          RubySMB::Gss::OID_NTLMSSP.oid
+        ]
+      )
+    end
+
+    it 'receives the token when a client selects Kerberos' do
+      received = nil
+      provider.on_mech_token { |token, _authenticator| received = token; nil }
+      multi.new_authenticator(server_client).process(neg_token_init(mech_token))
+      expect(received).to eq(mech_token)
+    end
+
+    it 'is left alone when a client selects NTLM' do
+      received = nil
+      provider.on_mech_token { |token, _authenticator| received = token; nil }
+      type1 = Net::NTLM::Message::Type1.new.tap { |msg| msg.domain = 'WORKGROUP' }
+      result = multi.new_authenticator(server_client).process(RubySMB::Gss.gss_type1(type1.serialize))
+      expect(received).to be_nil
+      expect(result.nt_status).to eq(WindowsError::NTStatus::STATUS_MORE_PROCESSING_REQUIRED)
+    end
+  end
+
+  # Build a SPNEGO NegTokenInit selecting Kerberos and carrying the specified mechanism token.
+  def neg_token_init(token)
+    inner = [OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::Sequence.new([RubySMB::Gss::OID_KERBEROS_5])], 0, :CONTEXT_SPECIFIC)]
+    inner << OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::OctetString.new(token)], 2, :CONTEXT_SPECIFIC) unless token.nil?
+
+    OpenSSL::ASN1::ASN1Data.new(
+      [
+        RubySMB::Gss::OID_SPNEGO,
+        OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::Sequence.new(inner)], 0, :CONTEXT_SPECIFIC)
+      ], 0, :APPLICATION
+    ).to_der
+  end
+end