1#@!#!123s

: / usr / share / nmap / nselib /
Filename : iscsi.lua
back
--- An iSCSI library implementing written by Patrik Karlsson <patrik@cqure.net>
-- The library currently supports target discovery and login.
--
-- The implementation is based on packetdumps and the iSCSI RFC
-- * http://tools.ietf.org/html/rfc3720
--
-- The library contains the protocol message pairs in <code>Packet</code>
-- E.g. <code>LoginRequest</code> and <code>LoginResponse</code>
--
-- Each request can be "serialized" to a string using:
-- <code>tostring(request)</code>. 
-- All responses can be read and instantiated from the socket by calling:
-- <code>local status,resp = Response.fromSocket(sock)</code>
--
-- In addition the library has the following classes:
-- * <code>Packet</code>
-- ** A class containing the request and response packets
-- * <code>Comm</code>
-- ** A class used to send and receive packet between the library and server
-- ** The class handles some of the packet "counting" and value updating
-- * <code>Socket</code>
-- ** A buffered socket class that allows reading of exakt number of bytes
-- * <code>KVP</code>
-- ** A key/value pair class that holds key value pairs
-- * <code>Helper</code>
-- ** A class that wraps the <code>Comm</code> and <code>Packet</code> classes
-- ** The purpose of the class is to provide easy access to common iSCSI task
--
--
-- @author "Patrik Karlsson <patrik@cqure.net>"
-- @copyright Same as Nmap--See http://nmap.org/book/man-legal.html

-- Version 0.2
-- Created 2010/11/18 - v0.1 - created by Patrik Karlsson <patrik@cqure.net>
-- Revised 2010/11/28 - v0.2 - improved error handling, fixed discovery issues
--								with multiple addresses <patrik@cqure.net>


local bin = require "bin"
local bit = require "bit"
local ipOps = require "ipOps"
local nmap = require "nmap"
local stdnse = require "stdnse"
local openssl = stdnse.silent_require "openssl"
local string = require "string"
local table = require "table"
_ENV = stdnse.module("iscsi", stdnse.seeall)


Packet = {
	
	Opcode = { 
		LOGIN = 0x03,
		TEXT = 0x04,
		LOGOUT = 0x06,
	},
	
	LoginRequest = {
		
		CSG = {
			SecurityNegotiation = 0,
			LoginOperationalNegotiation = 1,
			FullFeaturePhase = 3,
		},

		NSG = {
			SecurityNegotiation = 0,
			LoginOperationalNegotiation = 1,
			FullFeaturePhase = 3,
		},
		
		--- Creates a new instance of LoginRequest
		--
		-- @return instance of LoginRequest
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			o.immediate = 0
			o.opcode = Packet.Opcode.LOGIN
			o.flags = {}
			o.ver_max = 0
			o.ver_min = 0
			o.total_ahs_len = 0
			o.data_seg_len = 0
			o.isid = { t=0x01, a=0x00, b=0x0001, c=0x37, d=0 }
			o.tsih = 0
			o.initiator_task_tag = 1
			o.cid = 1
			o.cmdsn = 0
			o.expstatsn = 1
			o.kvp = KVP:new()
			return o
		end,
		
		setImmediate = function(self, b) self.immediate = ( b and 1 or 0 ) end,
		
		--- Sets the transit bit
		--
		-- @param b boolean containing the new transit value
		setTransit = function(self, b)	self.flags.transit = ( b and 1 or 0 ) end,

		--- Sets the continue bit
		--
		-- @param b boolean containing the new continue value
		setContinue = function(self, b) self.flags.continue = ( b and 1 or 0 ) end,

		--- Sets the CSG values
		--
		-- @param csg number containing the new NSG value 
		setCSG = function(self, csg) self.flags.csg = csg end,

		--- Sets the NSG values
		--
		-- @param nsg number containing the new NSG value 
		setNSG = function(self, nsg) self.flags.nsg = nsg end,

		--- Converts the class instance to string
		--
		-- @return string containing the converted instance
		__tostring = function( self )
			local reserved = 0
			local kvps = tostring(self.kvp)

			self.data_seg_len = #kvps

			local pad = 4 - ((#kvps + 48) % 4)
			pad = ( pad == 4 ) and 0 or pad

			for i=1, pad do kvps = kvps .. "\0" end

			local len = bit.lshift( self.total_ahs_len, 24 ) + self.data_seg_len
			local flags = bit.lshift( ( self.flags.transit or 0 ), 7 ) 
			flags = flags + bit.lshift( ( self.flags.continue or 0 ), 6)
			flags = flags + ( self.flags.nsg or 0 )
			flags = flags + bit.lshift( ( self.flags.csg or 0 ), 2 )
			
			local opcode = self.opcode + bit.lshift((self.immediate or 0), 6)
			
			local data = bin.pack(">CCCCICSCSSISSIILLA", opcode, 
				flags, self.ver_max, self.ver_min, len, 
				bit.lshift( self.isid.t, 6 ) +	bit.band( self.isid.a, 0x3f), 
				self.isid.b, self.isid.c, self.isid.d, self.tsih, 
				self.initiator_task_tag, self.cid, reserved, self.cmdsn, 
				self.expstatsn, reserved, reserved, kvps )
				
			return data
		end
		
	},
	
	LoginResponse = {
	
		-- Error messages
		ErrorMsgs = {
			[0x0000] = "Success",
			[0x0101] = "Target moved temporarily",
			[0x0102] = "Target moved permanently",
			[0x0200] = "Initiator error",
			[0x0201] = "Authentication failure",
			[0x0202] = "Authorization failure",
			[0x0203] = "Target not found",
			[0x0204] = "Target removed",
			[0x0205] = "Unsupported version",
			[0x0206] = "Too many connections",
			[0x0207] = "Missing parameter",
			[0x0208] = "Can't include in session",
			[0x0209] = "Session type not supported",
			[0x020a] = "Session does not exist",
			[0x020b] = "Invalid request during login",
			[0x0300] = "Target error",
			[0x0301] = "Service unavailable",
			[0x0302] = "Out of resources",
		},
		
		-- Error constants
		Errors = {
			SUCCESS = 0,
			AUTH_FAILED = 0x0201,
		},
		
		--- Creates a new instance of LoginResponse
		--
		-- @return instance of LoginResponse
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			return o
		end,
		
		--- Returns the error message
		getErrorMessage = function( self )
			return Packet.LoginResponse.ErrorMsgs[self.status_code] or "Unknown error"
		end,
		
		--- Returns the error code
		getErrorCode = function( self ) return self.status_code or 0 end,
		
		--- Creates a LoginResponse with data read from the socket
		--
		-- @return status true on success, false on failure
		-- @return resp instance of LoginResponse
		fromSocket = function( s )
			local status, header = s:recv(48)
			
			if ( not(status) ) then 
				return false, "Failed to read header from socket"
			end
			
			local resp = Packet.LoginResponse:new()
			local pos, len = bin.unpack(">I", header, 5)
						
			resp.total_ahs_len = bit.rshift(len, 24)
			resp.data_seg_len = bit.band(len, 0x00ffffff)
			pos, resp.status_code = bin.unpack(">S", header, 37)
			
			local pad = ( 4 - ( resp.data_seg_len % 4 ) )
			pad = ( pad == 4 ) and 0 or pad
						
			local status, data = s:recv( resp.data_seg_len + pad )
			if ( not(status) ) then 
				return false, "Failed to read data from socket"
			end
			
			resp.kvp = KVP:new()
			for _, kvp in ipairs(stdnse.strsplit( "\0", data )) do
				local k, v = kvp:match("(.*)=(.*)")
				if ( v ) then resp.kvp:add( k, v ) end
			end
			
			return true, resp
		end,
		
	},
	
	TextRequest = {
				
		--- Creates a new instance of TextRequest
		--
		-- @return instance of TextRequest
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			o.opcode = Packet.Opcode.TEXT 
			o.flags = {}
			o.flags.final = 0
			o.flags.continue = 0
			o.total_ahs_len = 0
			o.data_seg_len = 0
			o.lun = 0
			o.initiator_task_tag = 1
			o.target_trans_tag = 0xffffffff
			o.cmdsn = 2
			o.expstatsn = 1
			o.kvp = KVP:new()
			return o
		end,
		
		--- Sets the final bit of the TextRequest
		setFinal = function( self, b ) self.flags.final = ( b and 1 or 0 ) end,

		--- Sets the continue bit of the TextRequest
		setContinue = function( self, b ) self.flags.continue = ( b and 1 or 0 ) end,
				
		--- Converts the class instance to string
		--
		-- @return string containing the converted instance
		__tostring = function(self)
			local flags = bit.lshift( ( self.flags.final or 0 ), 7 )
			flags = flags + bit.lshift( (self.flags.continue or 0), 6 ) 

			local kvps = tostring(self.kvp)
			for i=1, (#kvps % 2) do kvps = kvps .. "\0" end
			self.data_seg_len = #kvps
		
			local len = bit.lshift( self.total_ahs_len, 24 ) + self.data_seg_len
			local reserved = 0
			local data = bin.pack(">CCSILIIIILLA", self.opcode, flags, reserved,
				len, self.lun, self.initiator_task_tag, self.target_trans_tag, 
				self.cmdsn, self.expstatsn, reserved, reserved, kvps)
				
			return data
		end,
		
	},

	TextResponse = {
				
		--- Creates a new instance of TextResponse
		--
		-- @return instance of TextResponse
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			return o
		end,
				
		--- Creates a TextResponse with data read from the socket
		--
		-- @return status true on success, false on failure
		-- @return instance of TextResponse
		--         err string containing error message
		fromSocket = function( s )
			local resp = Packet.TextResponse:new()
			local textdata = ""
			
			repeat
				local status, header = s:recv(48)
				local pos, _, flags, _, _, len = bin.unpack(">CCCCI", header)
				local cont = ( bit.band(flags, 0x40) == 0x40 )

				resp.total_ahs_len = bit.rshift(len, 24)
				resp.data_seg_len = bit.band(len, 0x00ffffff)
			
				local data
				status, data = s:recv( resp.data_seg_len )
						
				textdata = textdata .. data
				
			until( not(cont) )
			
			resp.records = {}

			local kvps = stdnse.strsplit( "\0", textdata )
			local record
			
			-- Each target record starts with one text key of the form:
			--   TargetName=<target-name-goes-here>
			-- Followed by zero or more address keys of the form:
			--  TargetAddress=<hostname-or-ipaddress>[:<tcp-port>], 
			--  <portal-group-tag>
			for _, kvp in ipairs(kvps) do
				local k, v = kvp:match("(.*)%=(.*)")
				if ( k == "TargetName" ) then
					if ( record ) then
						table.insert(resp.records, record)
						record = {}
					end
					if ( #resp.records == 0 ) then record = {} end
					record.name = v
				elseif ( k == "TargetAddress" ) then
					record.addr = record.addr or {}
					table.insert( record.addr, v )
				elseif ( not(k) ) then 
					-- this should be the ending empty kvp
					table.insert(resp.records, record)
					break
				else
					stdnse.print_debug("ERROR: iscsi.TextResponse: Unknown target record (%s)", k)
				end
			end
			
			return true, resp
		end,
	},
	
	--- Class handling a login request
	LogoutRequest = {
		
		--- Creates a new instance of LogoutRequest
		--
		-- @return instance of LogoutRequest
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			o.opcode = Packet.Opcode.LOGOUT
			o.immediate = 1
			o.reasoncode = 0
			o.total_ahs_len = 0
			o.data_seg_len = 0
			o.initiator_task_tag = 2
			o.cid = 1
			o.cmdsn = 0
			o.expstatsn = 1
			return o
		end,		
		
		--- Converts the class instance to string
		--
		-- @return string containing the converted instance
		__tostring = function(self)
			local opcode = self.opcode + bit.lshift((self.immediate or 0), 6)
			local reserved = 0
			local len = bit.lshift( self.total_ahs_len, 24 ) + self.data_seg_len
			local data = bin.pack(">CCSILISSIILL", opcode, (0x80 + self.reasoncode),
				reserved, len, reserved,self.initiator_task_tag, self.cid,
				reserved, self.cmdsn, self.expstatsn, reserved, reserved )
				
			return data
		end,
	},
	
	
	--- Class handling the Logout response
	LogoutResponse = {
		
		--- Creates a new instance of LogoutResponse
		--
		-- @return instance of LogoutResponse
		new = function( self )
			local o = {}
		   	setmetatable(o, self)
	        self.__index = self
			return o
		end,
		
		--- Creates a LogoutResponse with data read from the socket
		--
		-- @return status true on success, false on failure
		-- @return instance of LogoutResponse
		--         err string containing error message
		fromSocket = function( s )
			local resp = Packet.LogoutResponse:new()
			local status, header = s:recv(48)
			if ( not(status) ) then	return status, header end
			return true, resp
		end
		
	}
}

--- The communication class handles socket reads and writes
-- In addition it keeps track of both immediate packets and the amount of read
-- packets and updates cmdsn and expstatsn accordingly.
Comm = {
	
	--- Creates a new instance of Comm
	--
	-- @return instance of Comm
	new = function(self, socket)
		local o = {}
       	setmetatable(o, self)
        self.__index = self
		o.expstatsn = 0
		o.cmdsn = 1
		o.socket = socket
		return o
	end,
	
	--- Sends a packet and retrieves the response
	--
	-- @param out_packet instance of a packet to send
	-- @param in_class class of the packet to read
	-- @return status true on success, false on failure
	-- @return r decoded instance of in_class 
	exchange = function( self, out_packet, in_class )
	
		local expstatsn = ( self.expstatsn == 0 ) and 1 or self.expstatsn
	
		if ( out_packet.immediate and out_packet.immediate == 1 ) then
			self.cmdsn = self.cmdsn + 1
		end
	
		out_packet.expstatsn = expstatsn
		out_packet.cmdsn = self.cmdsn
		
		self.socket:send( tostring( out_packet ) )

		local status, r = in_class.fromSocket( self.socket )
		self.expstatsn = self.expstatsn + 1
		
		return status, r
	end,
	
	
}

--- A buffered socket implementation
Socket =
{	
	
	--- Creates a new instance of Socket
	--
	-- @return instance of Socket
	new = function(self)
		local o = {}
       	setmetatable(o, self)
        self.__index = self
		o.Socket = nmap.new_socket()
		o.Buffer = nil
		return o
	end,
	

	--- Establishes a connection.
	--
	-- @param hostid Hostname or IP address.
	-- @param port Port number.
	-- @param protocol <code>"tcp"</code>, <code>"udp"</code>, or
	-- @return Status (true or false).
	-- @return Error code (if status is false).
	connect = function( self, hostid, port, protocol )
		self.Socket:set_timeout(10000)
		return self.Socket:connect( hostid, port, protocol )
	end,
	
	--- Closes an open connection.
	--
	-- @return Status (true or false).
	-- @return Error code (if status is false).
	close = function( self )
		return self.Socket:close()
	end,
	
	--- Opposed to the <code>socket:receive_bytes</code> function, that returns
	-- at least x bytes, this function returns the amount of bytes requested.
	--
	-- @param count of bytes to read
	-- @return true on success, false on failure
	-- @return data containing bytes read from the socket
	-- 		   err containing error message if status is false
	recv = function( self, count )
		local status, data
	
		self.Buffer = self.Buffer or ""
	
		if ( #self.Buffer < count ) then
			status, data = self.Socket:receive_bytes( count - #self.Buffer )
			if ( not(status) or #data < count - #self.Buffer ) then
				return false, data
			end
			self.Buffer = self.Buffer .. data
		end
			
		data = self.Buffer:sub( 1, count )
		self.Buffer = self.Buffer:sub( count + 1)
	
		return true, data	
	end,
	
	--- Sends data over the socket
	--
	-- @return Status (true or false).
	-- @return Error code (if status is false).
	send = function( self, data )
		return self.Socket:send( data )
	end,
}

--- Key/Value pairs class
KVP = {
	
	--- Creates a new instance of KVP
	--
	-- @return instance of KVP
	new = function( self )
		local o = {}
	   	setmetatable(o, self)
        self.__index = self
		o.kvp = {}
		return o
	end,
	
	--- Adds a key/value pair
	--
	-- @param key string containing the key name
	-- @param value string containing the value
	add = function( self, key, value )
		table.insert( self.kvp, {[key]=value} )
	end,
	
	--- Gets all values for a specific key
	--
	-- @param key string containing the name of the key to retrieve
	-- @return values table containing all values for the specified key
	get = function( self, key ) 
		local values = {}
		for _, kvp in ipairs(self.kvp) do
			for k, v in pairs( kvp ) do
				if ( key == k ) then
					table.insert( values, v )
				end
			end
		end
		return values
	end,
	
	--- Returns all key value pairs as string delimited by \0
	-- eg. "key1=val1\0key2=val2\0"
	--
	-- @return string containing all key/value pairs
	__tostring = function( self )
		local ret = ""
		for _, kvp in ipairs(self.kvp) do
			for k, v in pairs( kvp ) do
				ret = ret .. ("%s=%s\0"):format(k,v)
			end
		end
		return ret
	end,
	
}

--- CHAP authentication class
CHAP = {
	
	--- Calculate a CHAP - response
	--
	-- @param identifier number containing the CHAP identifier
	-- @param challenge string containing the challenge
	-- @param secret string containing the users password
	-- @return response string containing the CHAP response
	calcResponse = function( identifier, challenge, secret )
		return openssl.md5( identifier .. secret .. challenge )
	end,
	
}

--- The helper class contains functions with more descriptive names
Helper = {
	
	--- Creates a new instance of the Helper class
	--
	-- @param host table as received by the script action function
	-- @param port table as received by the script action function
	-- @return o instance of Helper
	new = function( self, host, port )
		local o = {}
	   	setmetatable(o, self)
        self.__index = self
		o.host, o.port = host, port
		o.socket = Socket:new()
		return o
	end,
	
	--- Connects to the iSCSI target
	--
	-- @return status true on success, false on failure
	-- @return err string containing error message is status is false
	connect = function( self )
		local status, err = self.socket:connect(self.host, self.port, "tcp")
		if ( not(status) ) then return false, err end

		self.comm = Comm:new( self.socket )
		return true
	end,
	
	--- Attempts to discover accessible iSCSI targets on the remote server
	--
	-- @return status true on success, false on failure
	-- @return targets table containing discovered targets
	--         each table entry is a target table with <code>name</code>
	--         and <code>addr</code>.
	--         err string containing an error message is status is false
	discoverTargets = function( self )
		local p = Packet.LoginRequest:new()
		
		p:setTransit(true)
		p:setNSG(Packet.LoginRequest.NSG.LoginOperationalNegotiation)
		p.kvp:add( "InitiatorName", "iqn.1991-05.com.microsoft:nmap_iscsi_probe" )
		p.kvp:add( "SessionType", "Discovery" )
		p.kvp:add( "AuthMethod", "None" )
	
		local status, resp = self.comm:exchange( p, Packet.LoginResponse )
		if ( not(status) ) then
			return false, ("ERROR: iscsi.Helper.discoverTargets: %s"):format(resp)
		end
	
		local auth_method = resp.kvp:get("AuthMethod")[1]
		if ( auth_method:upper() ~= "NONE" ) then
			return false, "ERROR: iscsi.Helper.discoverTargets: Unsupported authentication method"
		end

		p = Packet.LoginRequest:new()
		p:setTransit(true)
		p:setNSG(Packet.LoginRequest.NSG.FullFeaturePhase)
		p:setCSG(Packet.LoginRequest.CSG.LoginOperationalNegotiation)
		p.kvp:add( "HeaderDigest", "None")
		p.kvp:add( "DataDigest", "None")
		p.kvp:add( "MaxRecvDataSegmentLength", "65536")
		p.kvp:add( "DefaultTime2Wait", "0")
		p.kvp:add( "DefaultTime2Retain", "60")
		
		status, resp = self.comm:exchange( p, Packet.LoginResponse )
				
		p = Packet.TextRequest:new()
		p:setFinal(true)
		p.kvp:add( "SendTargets", "All" )
		status, resp = self.comm:exchange( p, Packet.TextResponse )

		if ( not(resp.records) ) then
			return false, "iscsi.discoverTargets: response returned no targets"
		end
		
		for _, record in ipairs(resp.records) do
			table.sort( record.addr, function(a, b) local c = ipOps.compare_ip(a:match("(.-):"), "le", b:match("(.-):")); return c end )
		end
		return true, resp.records
	end,
	
	--- Logs out from the iSCSI target
	--
	-- @return status true on success, false on failure
	logout = function(self)
		local p = Packet.LogoutRequest:new()
		local status, resp = self.comm:exchange( p, Packet.LogoutResponse )
		return status
	end,

	--- Authenticate to the iSCSI service
	--
	-- @param target_name string containing the name of the iSCSI target
	-- @param username string containing the username
	-- @param password string containing the password
	-- @param auth_method string containing either "None" or "Chap"
	-- @return status true on success false on failure
	-- @return response containing the loginresponse or
	--         err string containing an error message if status is false
	login = function( self, target_name, username, password, auth_method )

		local auth_method = auth_method or "None"
		
		if ( not(target_name) ) then
			return false, "No target name specified"
		end
		
		if ( auth_method:upper()~= "NONE" and 
			 auth_method:upper()~= "CHAP" ) then
			return false, "Unknown authentication method"
		end
		
		local p = Packet.LoginRequest:new()
		
		p:setTransit(true)
		p:setNSG(Packet.LoginRequest.NSG.LoginOperationalNegotiation)
		p.kvp:add( "InitiatorName", "iqn.1991-05.com.microsoft:nmap_iscsi_probe" )
		p.kvp:add( "SessionType", "Normal" )
		p.kvp:add( "TargetName", target_name )
		p.kvp:add( "AuthMethod", auth_method )
		
		if ( not(self.comm) ) then
			return false, "ERROR: iscsi.Helper.login: Not connected"
		end
		local status, resp = self.comm:exchange( p, Packet.LoginResponse )
		if ( not(status) ) then
			return false, ("ERROR: iscsi.Helper.login: %s"):format(resp)
		end

		if ( resp.status_code ~= 0 ) then
			stdnse.print_debug(3, "ERROR: iscsi.Helper.login: Authentication failed (error code: %d)", resp.status_code)
			return false, resp
		elseif ( auth_method:upper()=="NONE" ) then
			return true, resp
		end
		
		p = Packet.LoginRequest:new()
		p.kvp:add( "CHAP_A", "5" )
		status, resp = self.comm:exchange( p, Packet.LoginResponse )
		if ( not(status) ) then
			return false, ("ERROR: iscsi.Helper.login: %s"):format(resp)
		end
		
		local alg = resp.kvp:get("CHAP_A")[1]
		if ( alg ~= "5" ) then return false, "Unsupported authentication algorithm" end

		local chall = resp.kvp:get("CHAP_C")[1]
		if ( not(chall) ) then return false, "Failed to decode challenge" end
		chall = bin.pack("H", chall:sub(3))
		
		local ident = resp.kvp:get("CHAP_I")[1]
		if (not(ident)) then return false, "Failed to decoded identifier" end
		ident = string.char(tonumber(ident))

		local resp = CHAP.calcResponse( ident, chall, password )
		resp = "0x" .. select(2, bin.unpack("H16", resp))
		
		p = Packet.LoginRequest:new()
		p:setImmediate(true)
		p:setTransit(true)
		p:setNSG(Packet.LoginRequest.NSG.LoginOperationalNegotiation)
		p.kvp:add("CHAP_N", username)
		p.kvp:add("CHAP_R", resp)

		status, resp = self.comm:exchange( p, Packet.LoginResponse )
		if ( not(status) ) then
			return false, ("ERROR: iscsi.Helper.login: %s"):format(resp)
		end

		if ( resp:getErrorCode() ~= Packet.LoginResponse.Errors.SUCCESS ) then
			return false, "Login failed"
		end
		
		return true, resp
	end,
	
	--- Disconnects the socket from the server
	close = function(self) self.socket:close() end
	
}





return _ENV;