---Implements functionality related to Server Message Block (SMB, also known -- as CIFS) traffic, which is a Windows protocol. -- -- SMB traffic is normally sent to/from ports 139 or 445 of Windows systems. Other systems -- implement SMB as well, including Samba and a lot of embedded devices. Some of them implement -- it properly and many of them not. Although the protocol has been documented decently -- well by Samba and others, many 3rd party implementations are broken or make assumptions. -- Even Samba's and Windows' implementations aren't completely compatiable. As a result, -- creating an implementation that accepts everything is a bit of a minefield. -- -- Where possible, this implementation, since it's intended for scanning, will attempt to -- accept any invalid implementations it can, and fail gracefully if it can't. This has -- been tested against a great number of weird implementations, and it now works against -- all of them. -- -- The intention of this library is to eventually handle all aspects of the SMB protocol. -- That being said, I'm only implementing the pieces that I (Ron Bowes) need. If you -- require something more, let me know and I'll put it on my todo list. -- -- A programmer using this library should already have some knowledge of the SMB protocol, -- although a lot isn't necessary. You can pick up a lot by looking at the code. The basic -- login/logoff is this: -- -- -- [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 -- [disconnect] -- -- -- In terms of functions here, the protocol is: -- -- -- status, smbstate = smb.start(host) -- status, err = smb.negotiate_protocol(smbstate, {}) -- status, err = smb.start_session(smbstate, {}) -- status, err = smb.tree_connect(smbstate, path, {}) -- ... -- status, err = smb.tree_disconnect(smbstate) -- status, err = smb.logoff(smbstate) -- status, err = smb.stop(smbstate) -- -- -- The stop function will automatically call tree_disconnect and logoff, -- cleaning up the session, if it hasn't been done already. -- -- To initially begin the connection, there are two options: -- -- 1) Attempt to start a raw session over 445, if it's open. -- -- 2) Attempt to start a NetBIOS session over 139. Although the -- protocol's the same, it requires a session request packet. -- That packet requires the computer's name, which is requested -- using a NBSTAT probe over UDP port 137. -- -- 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. -- Some systems will refuse to use that protocol and return "-1" or "1" instead of 0. If that's -- detected, we kill the connection (because the protocol following won't work). -- -- 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 username and password are generally picked up from the program parameters, which are -- set when running a script, or from the registry where it can be set by other scripts (for -- example, smb-brute.nse). However, they can also be passed as parameters to the -- function, which will override any other username/password set. -- -- If a username and password are set, they are used for the first login attempt. If a login fails, -- or they weren't set, a connection as the 'GUEST' account with a blank password is attempted. If -- that fails, then a NULL session is established, which should always work. The username/password -- will give the highest access level, GUEST will give lower access, and NULL will give the lowest -- (often, NULL will give no access). -- -- The actual login protocol used by SMB_COM_SESSION_SETUP_ANDX is explained in detail -- in smbauth.lua. -- -- Thanks go to Christopher R. Hertel and his book Implementing CIFS, which -- taught me everything I know about Microsoft's protocols. Additionally, I used Samba's -- list of error codes for my constants. Although I don't believe they would be covered -- by GPL, since they're public now anyways, but I'm not a lawyer and, if somebody feels -- differently, let me know and we can sort this out. -- -- Scripts that use this module can use the script arguments listed below -- example of using these script arguments: -- -- nmap --script=smb-