Class: RubySMB::Client

Inherits:
Object
  • Object
show all
Includes:
Authentication, Echo, Negotiation, Signing, TreeConnect
Defined in:
lib/ruby_smb/client.rb,
lib/ruby_smb/client/echo.rb,
lib/ruby_smb/client/signing.rb,
lib/ruby_smb/client/negotiation.rb,
lib/ruby_smb/client/tree_connect.rb,
lib/ruby_smb/client/authentication.rb

Overview

Represents an SMB client capable of talking to SMB1 or SMB2 servers and handling all end-user client functionality.

Defined Under Namespace

Modules: Authentication, Echo, Negotiation, Signing, TreeConnect

Constant Summary collapse

SMB1_DIALECT_SMB1_DEFAULT =

The Default SMB1 Dialect string used in an SMB1 Negotiate Request

"NT LM 0.12"
SMB1_DIALECT_SMB2_DEFAULT =

The Default SMB2 Dialect string used in an SMB1 Negotiate Request

"SMB 2.002"
SMB2_DIALECT_DEFAULT =

Dialect value for SMB2 Default (Version 2.02)

0x0202

Instance Attribute Summary collapse

Attributes included from Signing

#session_key

Instance Method Summary collapse

Methods included from Echo

#smb1_echo, #smb2_echo

Methods included from TreeConnect

#smb1_tree_connect, #smb1_tree_from_response, #smb2_tree_connect, #smb2_tree_from_response

Methods included from Signing

#smb1_sign, #smb2_sign

Methods included from Authentication

#authenticate, #smb1_anonymous_auth, #smb1_anonymous_auth_request, #smb1_anonymous_auth_response, #smb1_authenticate, #smb1_ntlmssp_auth_packet, #smb1_ntlmssp_authenticate, #smb1_ntlmssp_challenge_packet, #smb1_ntlmssp_final_packet, #smb1_ntlmssp_negotiate, #smb1_ntlmssp_negotiate_packet, #smb1_type2_message, #smb2_authenticate, #smb2_ntlmssp_auth_packet, #smb2_ntlmssp_authenticate, #smb2_ntlmssp_challenge_packet, #smb2_ntlmssp_final_packet, #smb2_ntlmssp_negotiate, #smb2_ntlmssp_negotiate_packet, #smb2_type2_message

Methods included from Negotiation

#negotiate, #negotiate_request, #negotiate_response, #parse_negotiate_response, #smb1_negotiate_request, #smb2_negotiate_request

Constructor Details

#initialize(dispatcher, smb1: true, smb2: true, username:, password:, domain: '.', local_workstation: 'WORKSTATION') ⇒ Client

Returns a new instance of Client.

Parameters:

  • dispatcher (RubySMB::Dispacther::Socket) —

    the packet dispatcher to use

  • smb1 (Boolean) (defaults to: true) —

    whether or not to enable SMB1 support

  • smb2 (Boolean) (defaults to: true) —

    whether or not to enable SMB2 support

Raises:

  • (ArgumentError) 


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/ruby_smb/client.rb', line 102

def initialize(dispatcher, smb1: true, smb2: true, username:,password:, domain:'.', local_workstation:'WORKSTATION')
  raise ArgumentError, 'No Dispatcher provided' unless dispatcher.kind_of? RubySMB::Dispatcher::Base
  if smb1 == false && smb2 == false
    raise ArgumentError, 'You must enable at least one Protocol'
  end
  @dispatcher        = dispatcher
  @domain            = domain
  @local_workstation = local_workstation
  @password          = password.encode("utf-8") || ''.encode("utf-8")
  @sequence_counter  = 0
  @session_id        = 0x00
  @session_key       = ''
  @signing_required  = false
  @smb1              = smb1
  @smb2              = smb2
  @username          = username.encode("utf-8") || ''.encode("utf-8")

  @ntlm_client = Net::NTLM::Client.new(
    @username,
    @password,
    workstation: @local_workstation,
    domain: @domain
  )

  @smb2_message_id = 0
end

Instance Attribute Details

#dispatcher ⇒ RubySMB::Dispatcher::Socket

Returns:



29
30
31
 
# File 'lib/ruby_smb/client.rb', line 29

def dispatcher
  @dispatcher
end

#domain ⇒ String

Returns:

  • (String) 


34
35
36
 
# File 'lib/ruby_smb/client.rb', line 34

def domain
  @domain
end

#local_workstation ⇒ String

Returns:

  • (String) 


39
40
41
 
# File 'lib/ruby_smb/client.rb', line 39

def local_workstation
  @local_workstation
end

#ntlm_client ⇒ String

Returns:

  • (String) 


44
45
46
 
# File 'lib/ruby_smb/client.rb', line 44

def ntlm_client
  @ntlm_client
end

#password ⇒ String

Returns:

  • (String) 


49
50
51
 
# File 'lib/ruby_smb/client.rb', line 49

def password
  @password
end

#peer_native_os ⇒ String

Returns:

  • (String) 


55
56
57
 
# File 'lib/ruby_smb/client.rb', line 55

def peer_native_os
  @peer_native_os
end

#sequence_counter ⇒ Integer

Returns:

  • (Integer) 


62
63
64
 
# File 'lib/ruby_smb/client.rb', line 62

def sequence_counter
  @sequence_counter
end

#session_id ⇒ Integer

Returns:

  • (Integer) 


67
68
69
 
# File 'lib/ruby_smb/client.rb', line 67

def session_id
  @session_id
end

#signing_enabled ⇒ Boolean

Returns:

  • (Boolean) 


72
 
# File 'lib/ruby_smb/client.rb', line 72

attr_accessor :signing_required

#signing_required ⇒ Object

Whether or not the Server requires signing



72
73
74
 
# File 'lib/ruby_smb/client.rb', line 72

def signing_required
  @signing_required
end

#smb1 ⇒ Boolean

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/ruby_smb/client.rb', line 77

def smb1
  @smb1
end

#smb2 ⇒ Boolean

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/ruby_smb/client.rb', line 82

def smb2
  @smb2
end

#smb2_message_id ⇒ Integer

Returns:

  • (Integer) 


87
88
89
 
# File 'lib/ruby_smb/client.rb', line 87

def smb2_message_id
  @smb2_message_id
end

#user_id ⇒ String

Returns:

  • (String) 


97
98
99
 
# File 'lib/ruby_smb/client.rb', line 97

def user_id
  @user_id
end

#username ⇒ String

Returns:

  • (String) 


92
93
94
 
# File 'lib/ruby_smb/client.rb', line 92

def username
  @username
end

Instance Method Details

#disconnect! ⇒ void

This method returns an undefined value.

Logs off any currently open session on the server and closes the TCP socket connection.



133
134
135
136
137
138
139
140
 
# File 'lib/ruby_smb/client.rb', line 133

def disconnect!
  begin
    logoff!
  rescue
    wipe_state!
  end
  dispatcher.tcp_socket.close
end

#echo(count: 1, data: '') ⇒ WindowsError::ErrorCode

Sends an Echo request to the server and returns the NTStatus of the last response packet received.

Parameters:

  • echo (Integer) —

    the number of times the server should echo (ignored in SMB2)

  • data (String) (defaults to: '') —

    the data the server should echo back (ignored in SMB2)

Returns:

  • (WindowsError::ErrorCode) —

    the NTStatus of the last response received



148
149
150
151
152
153
154
155
 
# File 'lib/ruby_smb/client.rb', line 148

def echo(count: 1, data: '' )
  if smb2
    response = smb2_echo
  else
    response = smb1_echo(count:count, data:data)
  end
  response.status_code
end

#increment_smb_message_id(packet) ⇒ RubySMB::GenericPacket

Sets the message id field in an SMB2 packet's header to the one tracked by the client. It then increments the counter on the client.

Parameters:

Returns:



163
164
165
166
167
168
169
 
# File 'lib/ruby_smb/client.rb', line 163

def increment_smb_message_id(packet)
  if packet.smb2_header.message_id == 0 && self.smb2_message_id != 0
    packet.smb2_header.message_id = self.smb2_message_id
    self.smb2_message_id += 1
  end
  packet
end

#login(username: self.username, password: self.password, domain: self.domain, local_workstation: self.local_workstation) ⇒ Object

Performs protocol negotiation and session setup. It defaults to using the credentials supplied during initialization, but can take a new set of credentials if needed.



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/ruby_smb/client.rb', line 173

def (username: self.username, password: self.password, domain: self.domain, local_workstation: self.local_workstation )
  @domain            = domain
  @local_workstation = local_workstation
  @password          = password.encode("utf-8") || ''.encode("utf-8")
  @username          = username.encode("utf-8") || ''.encode("utf-8")

  @ntlm_client = Net::NTLM::Client.new(
    @username,
    @password,
    workstation: @local_workstation,
    domain: @domain
  )

  negotiate
  authenticate
end

#logoff! ⇒ WindowsError::ErrorCode

Sends a LOGOFF command to the remote server to terminate the session

Returns:

  • (WindowsError::ErrorCode) —

    the NTStatus of the response



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ruby_smb/client.rb', line 193

def logoff!
  if smb2
    request      = RubySMB::SMB2::Packet::LogoffRequest.new
    raw_response = send_recv(request)
    response     = RubySMB::SMB2::Packet::LogoffResponse.read(raw_response)
  else
    request      = RubySMB::SMB1::Packet::LogoffRequest.new
    raw_response = send_recv(request)
    response     = RubySMB::SMB1::Packet::LogoffResponse.read(raw_response)
  end
  wipe_state!
  response.status_code
end

#send_recv(packet) ⇒ String

Sends a packet and receives the raw response through the Dispatcher. It will also sign the packet if neccessary.

Parameters:

Returns:

  • (String) —

    the raw response data received



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/ruby_smb/client.rb', line 212

def send_recv(packet)
  case packet.packet_smb_version
    when 'SMB1'
      if self.user_id
        packet.smb_header.uid = self.user_id
      end
      packet = smb1_sign(packet)
    when 'SMB2'
      packet = increment_smb_message_id(packet)
      packet.smb2_header.session_id = self.session_id
      unless packet.is_a?(RubySMB::SMB2::Packet::SessionSetupRequest)
        packet = smb2_sign(packet)
      end
    else
      packet = packet
  end
  dispatcher.send_packet(packet)
  raw_response = dispatcher.recv_packet

  if self.signing_required && !self.session_key.empty?
    self.sequence_counter += 1
  end
  raw_response
end

#tree_connect(share) ⇒ RubySMB::SMB1::Tree, RubySMB::SMB2::Tree

Connects to the supplied share

Parameters:

  • share (String) —

    the path to the share in \\server\share_name format

Returns:



242
243
244
245
246
247
248
 
# File 'lib/ruby_smb/client.rb', line 242

def tree_connect(share)
  if smb2
    smb2_tree_connect(share)
  else
    smb1_tree_connect(share)
  end
end

#wipe_state! ⇒ void

This method returns an undefined value.

Resets all of the session state on the client, setting it back to scratch. Should only be called when a session is no longer valid.



255
256
257
258
259
260
261
 
# File 'lib/ruby_smb/client.rb', line 255

def wipe_state!
  self.session_id       = 0x00
  self.user_id          = 0x00
  self.session_key      = ''
  self.sequence_counter = 0
  self.smb2_message_id  = 0
end