From eb5a40dc8139f16e1af151d6a6af60e52fc5905c Mon Sep 17 00:00:00 2001 From: david Date: Tue, 21 Oct 2008 22:19:52 +0000 Subject: [PATCH] Use markup in nselib/smb.lua. --- nselib/smb.lua | 112 ++++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 53 deletions(-) diff --git a/nselib/smb.lua b/nselib/smb.lua index cb011de57..8150b09be 100644 --- a/nselib/smb.lua +++ b/nselib/smb.lua @@ -9,31 +9,37 @@ -- although a lot isn't necessary. You can pick up a lot by looking at the code that uses -- this. The basic login is this:\n --\n --- [connect]\n --- C->S SMB_COM_NEGOTIATE\n --- S->C SMB_COM_NEGOTIATE\n --- C->S SMB_COM_SESSION_SETUP_ANDX\n --- S->C SMB_COM_SESSION_SETUP_ANDX\n --- C->S SMB_COM_TREE_CONNECT_ANDX\n --- S->C SMB_COM_TREE_CONNECT_ANDX\n --- ...\n --- C->S SMB_COM_TREE_DISCONNECT\n --- S->C SMB_COM_TREE_DISCONNECT\n --- C->S SMB_COM_LOGOFF_ANDX\n --- S->C SMB_COM_LOGOFF_ANDX\n ---\n +-- +-- [connect] +-- C->S SMB_COM_NEGOTIATE +-- S->C SMB_COM_NEGOTIATE +-- C->S SMB_COM_SESSION_SETUP_ANDX +-- S->C SMB_COM_SESSION_SETUP_ANDX +-- C->S SMB_COM_TREE_CONNECT_ANDX +-- S->C SMB_COM_TREE_CONNECT_ANDX +-- ... +-- C->S SMB_COM_TREE_DISCONNECT +-- S->C SMB_COM_TREE_DISCONNECT +-- C->S SMB_COM_LOGOFF_ANDX +-- S->C SMB_COM_LOGOFF_ANDX +-- +--\n\n -- In terms of functions here, the protocol is:\n --- status, socket = smb.start(host)\n --- status, negotiate_result = smb.negotiate_protocol(socket)\n --- status, session_result = smb.start_session(socket, username, negotiate_result['session_key'], negotiate_result['capabilities'])\n --- status, tree_result = smb.tree_connect(socket, path, session_result['uid'])\n --- status, disconnect_result = smb.tree_disconnect(socket, session_result['uid'], tree_result['tid'])\n --- status, logoff_result = smb.logoff(socket, session_result['uid'])\n --- status, err = smb.stop(socket)\n +-- +-- status, socket = smb.start(host) +-- status, negotiate_result = smb.negotiate_protocol(socket) +-- status, session_result = smb.start_session(socket, username, negotiate_result['session_key'], negotiate_result['capabilities']) +-- status, tree_result = smb.tree_connect(socket, path, session_result['uid']) +-- status, disconnect_result = smb.tree_disconnect(socket, session_result['uid'], tree_result['tid']) +-- status, logoff_result = smb.logoff(socket, session_result['uid']) +-- status, err = smb.stop(socket) +-- --\n --- Optionally, the 'stop' function can also call tree_disconnect and logoff, by giving it extra parameters:\n --- status, err = smb.stop(socket, session_result['uid'], tree_result['tid'])\n --- \n +-- Optionally, the stop function can also call tree_disconnect and logoff, by giving it extra parameters:\n +-- +-- status, err = smb.stop(socket, session_result['uid'], tree_result['tid']) +-- +-- -- To initially begin the connection, there are two options:\n -- 1) Attempt to start a raw session over 445, if it's open. \n -- 2) Attempt to start a NetBIOS session over 139. Although the @@ -41,24 +47,23 @@ -- That packet requires the computer's name, which is requested -- using a NBSTAT probe over UDP port 137. \n -- --- Once it's connected, a SMB_COM_NEGOTIATE packet is sent, +-- Once it's connected, a SMB_COM_NEGOTIATE packet is sent, -- requesting the protocol "NT LM 0.12", which is the most commonly -- supported one. Among other things, the server's response contains -- the host's security level, the system time, and the computer/domain -- name.\n --\n --- If that's successful, SMB_COM_SESSION_SETUP_ANDX is sent. It is essentially the logon +-- If that's successful, SMB_COM_SESSION_SETUP_ANDX is sent. It is essentially the logon -- packet, where the username, domain, and password are sent to the server for verification. --- The response to SMB_COM_SESSION_SETUP_ANDX is fairly simple, containing a boolean for +-- The response to SMB_COM_SESSION_SETUP_ANDX is fairly simple, containing a boolean for -- success, along with the operating system and the lan manager name. \n --\n --- After a successful SMB_COM_SESSION_SETUP_ANDX has been made, a --- SMB_COM_TREE_CONNECT_ANDX packet can be sent. This is what connects to a share. +-- After a successful SMB_COM_SESSION_SETUP_ANDX has been made, a +-- SMB_COM_TREE_CONNECT_ANDX packet can be sent. This is what connects to a share. -- The server responds to this with a boolean answer, and little more information. \n --\n --- Each share will either return STATUS_BAD_NETWORK_NAME if the share doesn't --- exist, STATUS_ACCESS_DENIED if it exists but we don't have access, or --- STATUS_SUCCESS if exists and we do have access. \n +-- Each share will either return STATUS_BAD_NETWORK_NAME if the share doesn't exist, STATUS_ACCESS_DENIED if it exists but we don't have access, or +-- STATUS_SUCCESS if exists and we do have access. \n --\n -- Thanks go to Christopher R. Hertel and Implementing CIFS, which -- taught me everything I know about Microsoft's protocols. \n @@ -707,8 +712,8 @@ function get_port(host) return nil end ---- Begins a SMB session, automatically determining the best way to connect. Also starts a mutex --- with mutex_id. This prevents multiple threads from making queries at the same time (which breaks +--- Begins a SMB session, automatically determining the best way to connect. Also starts a mutex. +-- This prevents multiple threads from making queries at the same time (which breaks -- SMB). -- -- @param host The host object @@ -754,7 +759,7 @@ function start(host) end --- Kills the SMB connection, closes the socket, and releases the mutex. Because of the mutex --- being released, a script HAS to call stop() before it exits, no matter why it's exiting! +-- being released, a script HAS to call stop() before it exits, no matter why it's exiting! -- -- In addition to killing the connection, this function can log off the user and disconnect -- a tree. To do so, the appropriate parameters are passed. For a logoff, the uid is required. @@ -793,7 +798,6 @@ end --- Begins a raw SMB session, likely over port 445. Since nothing extra is required, this -- function simply makes a connection and returns the socket. --- it off to smb_start(). -- --@param host The host object to check. --@param port The port to use (most likely 445). @@ -955,6 +959,7 @@ end --- Creates a string containing a SMB packet header. The header looks like this:\n +-- -- --------------------------------------------------------------------------------------------------\n -- | 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 |\n -- --------------------------------------------------------------------------------------------------\n @@ -974,16 +979,17 @@ end -- --------------------------------------------------------------------------------------------------\n -- | UID | MID |\n -- ------------------------------------------------------------------------------------------------- \n +-- -- -- All fields are, incidentally, encoded in little endian byte order. \n --\n -- For the purposes here, the program doesn't care about most of the fields so they're given default \n -- values. The fields of interest are:\n --- * Command -- The command of the packet (SMB_COM_NEGOTIATE, SMB_COM_SESSION_SETUP_ANDX, etc)\n +-- * Command -- The command of the packet (SMB_COM_NEGOTIATE, SMB_COM_SESSION_SETUP_ANDX, etc)\n -- * UID/TID -- Sent by the server, and just have to be echoed back\n --@param command The command to use. ---@param uid The UserID, which is returned by SMB_COM_SESSION_SETUP_ANDX (0 otherwise) ---@param tid The TreeID, which is returned by SMB_COM_TREE_CONNECT_ANDX (0 otherwise) +--@param uid The UserID, which is returned by SMB_COM_SESSION_SETUP_ANDX (0 otherwise) +--@param tid The TreeID, which is returned by SMB_COM_TREE_CONNECT_ANDX (0 otherwise) --@return A binary string containing the packed packet header. local function smb_encode_header(command, uid, tid) @@ -1021,7 +1027,7 @@ end -- The encoding is simple:\n -- (1 byte) The number of 2-byte values in the parameters section\n -- (variable) The parameter section\n --- This is automatically done by smb_send(). +-- This is automatically done by smb_send(). -- -- @param parameters The parameters section. -- @return The encoded parameters. @@ -1033,7 +1039,7 @@ end -- The encoding is simple:\n -- (2 bytes) The number of bytes in the data section\n -- (variable) The data section\n --- This is automatically done by smb_send(). +-- This is automatically done by smb_send(). -- -- @param data The data section. -- @return The encoded data. @@ -1046,7 +1052,7 @@ end -- wide, depending on whether or not we're using raw, but that shouldn't matter. -- --@param socket The socket to send the packet on. ---@param header The header, encoded with smb_get_header(). +--@param header The header, encoded with smb_get_header(). --@param parameters The parameters --@param data The data --@return (result, err) If result is false, err is the error message. Otherwise, err is @@ -1103,7 +1109,7 @@ function smb_read(socket) return true, header, parameters, data end ---- Sends out SMB_COM_NEGOTIATE, which is typically the first SMB packet sent out. +--- Sends out SMB_COM_NEGOTIATE, which is typically the first SMB packet sent out. -- Sends the following:\n -- * List of known protocols\n --\n @@ -1220,7 +1226,7 @@ function negotiate_protocol(socket) return true, response end ---- Sends out SMB_COM_SESSION_SETUP_ANDX, which attempts to log a user in. +--- Sends out SMB_COM_SESSION_SETUP_ANDX, which attempts to log a user in. -- Sends the following:\n -- * Negotiated parameters (multiplexed connections, virtual circuit, capabilities)\n -- * Passwords (plaintext, unicode, lanman, ntlm, lmv2, ntlmv2, etc)\n @@ -1234,8 +1240,8 @@ end --\n --@param socket The socket, in the proper state (ie, after protocol has been negotiated). --@param username The account name to use. For Null sessions, leave it blank (''). ---@param session_key The session_key value, returned by SMB_COM_NEGOTIATE. ---@param capabilities The server's capabilities, returned by SMB_COM_NEGOTIATE. +--@param session_key The session_key value, returned by SMB_COM_NEGOTIATE. +--@param capabilities The server's capabilities, returned by SMB_COM_NEGOTIATE. --@return (status, result) If status is false, result is an error message. Otherwise, result is a -- table with the following elements:\n -- 'uid' The UserID for the session @@ -1313,7 +1319,7 @@ function start_session(socket, username, session_key, capabilities) end ---- Sends out SMB_COM_SESSION_TREE_CONNECT_ANDX, which attempts to connect to a share. +--- Sends out SMB_COM_SESSION_TREE_CONNECT_ANDX, which attempts to connect to a share. -- Sends the following:\n -- * Password (for share-level security, which we don't support)\n -- * Share name\n @@ -1323,8 +1329,8 @@ end -- * Tree ID\n --\n --@param socket The socket, in the proper state. ---@param path The path to connect (eg, \\servername\C$) ---@param uid The UserID, returned by SMB_COM_SESSION_SETUP_ANDX +--@param path The path to connect (eg, "\\servername\C$") +--@param uid The UserID, returned by SMB_COM_SESSION_SETUP_ANDX --@return (status, result) If status is false, result is an error message. Otherwise, result is a -- table with the following elements:\n -- 'tid' The TreeID for the session @@ -1376,8 +1382,8 @@ end --- Disconnects a tree session. Should be called before logging off and disconnecting. --@param socket The socket ---@param uid The UserID, returned by SMB_COM_SESSION_SETUP_ANDX ---@param tid The TreeID, returned by SMB_COM_TREE_CONNECT_ANDX +--@param uid The UserID, returned by SMB_COM_SESSION_SETUP_ANDX +--@param tid The TreeID, returned by SMB_COM_TREE_CONNECT_ANDX --@param return (status, result) If statis is false, result is an error message. If status is true, -- the disconnect was successful. function tree_disconnect(socket, uid, tid) @@ -1411,7 +1417,7 @@ function tree_disconnect(socket, uid, tid) end ----Logs of the current user. Strictly speaking this isn't necessary, but it's the polite thing to do. +---Logs off the current user. Strictly speaking this isn't necessary, but it's the polite thing to do. --@param socket The socket. --@param uid The user ID. --@param return (status, result) If statis is false, result is an error message. If status is true, @@ -1545,8 +1551,8 @@ end -- transactions I've done have required parameters. --@param data The data to send with the packet. This is basically the next protocol layer --@param uid The UserID ---@param tid The TreeID (handle to $IPC) ---@param fid The FileID (opened by create_file) +--@param tid The TreeID (handle to $IPC) +--@param fid The FileID (opened by create_file) --@return (status, result) If status is false, result is an error message. Otherwise, result is a table -- containing 'parameters' and 'data', representing the parameters and data returned by the server. function send_transaction(socket, func, function_parameters, function_data, uid, tid, fid)