NOTE

We’re not dead yet!
…​but this project is on hold until we figure out what to do about Python.

Python has been declared end-of-life and the recommendation is to port to Py3. Thing is, Py3 has been out for quite a while now so who knows if it will be replaced by Py4 or somesuch.

In the mean time, work proceeds on Zambezi.

---

Hi!

Carnaval

…​is an SMB2+ protocol suite implementation in Python.

This project may look a bit stale, but work continues in the shadows.

So far we have a complete low-level implementation of the NBT transport layer; a good start. We also have SMB1 protocol negotiation and SMB1 Echo, but we won’t be doing much more with SMB1 for a while (if ever). The next step is SMB2 packing and parsing.

Stay tuned.

Patch Submissions

If you want to contribute something, we would just be tickled pink, but please note the licensing philosophy discussion below.

Licensing Philosophy

This code is provided with the hope that it is both usable and useful, but without any promises regarding net weight, color, the quality or origin of the bits used to represent the code on any computer or in any form of data transmission, fitness for any specific purpose, or the number of jelly beans in the giant jam jar. We’re just putting this out there with the wild wish that it will make someone happier than they already hopefully are.

These modules are licensed under either the GNU Lesser General Public License (LGPL) or the GNU Affero General Public License. If there were a GNU Affero LGPL we would use that instead of the regular LGPL. In all cases, we are using version 3.0 of the licenses or (as they say) any later version.

In general, code modules that provide classes but which are not really programs on their own are licensed under the LGPL. Example programs, working servers, testing programs, etc., are licensed under the AGPL. See the individual files for specifics, but the licensing is intended to make sense.

The long term goal is to provide both a practical toolkit and a worthy reference implementation.

AGPL: https://www.gnu.org/licenses/agpl.html
LGPL: https://www.gnu.org/licenses/lgpl.html

Ramblings

A quick Internet search shows that there have been a handful of attempts to create an SMB client in Python, and a possibly a few tries at an SMB server.

Here we go again.

We are trying to meet the following goals:

• Provide a useful SMB2/3 client and server implementation in Python. We don’t expect that it’ll be wildly fast, but we do want it to be both reliable and useful. (SMB1 may follow later on. SMB2/3 is a higher priority for now.)

• Provide modular support for additional protocols, such as the Distributed File System (see [MS-DFSC]).

• Provide clear and complete documentation. The pydoc output in all of our modules should be be enough to get you started, and provide useful links to further information if you want to dig deeper.

• Act as a guide for others who want to implement some aspect of the SMB suite. We’re trying to keep the code clean and clear and commented so that that it’s not only clear what the code is doing, but why it’s doing it.

That’s pretty lofty, particularly since we’ve only gotten as far as the NBT transport layer and a couple of SMB1 commands. On the other hand, the project has some experienced SMB folks involved and what we’ve produced so far is living up to our high expectations.

Words

CIFS

Common Internet File System. CIFS is the "marketing upgrade" name that was bestowed upon the SMB protocol in the mid-1990’s. For a while, some in the community used the CIFS name to refer to the suite of protocols that centered upon SMB, including SMB, NBT, the Browser protocols, DFS, Mailslot protocol, and a few others. Unfortunately, some lawyers got hold of the name and used it to refer to what we now call SMB1 (see below). Confusion reigned, and the term lost all relevance. CIFS is now considered a dead name. Microsoft doesn’t use it any more, except in older documentation or references to legacy implementations. The term is still popular among sales engineers.

DFS

Distributed File System. Microsoft’s DFS is fairly simple. The part we care about is the logical namespace, which is described in [MS-DFSC].

NBT

NetBIOS over TCP transport protocol. NBT is the virtual LAN protocol specified by IETF Standard #19 which, in turn, consists of RFC1001 and RFC1002. NBT provides a mechanism for supporting the semantics of the NetBIOS API over TCP/UDP/IP internetworks. (See [NBGUIDE], [IMPCIFS], [RFC1001], and [RFC1002].)

SMB

Server Message Block protocol. SMB was originally created by IBM in the early 1980’s for use with PC-DOS. It was later updated and extended for use with OS/2, and marketed under the name LAN Manager. OS/2 LAN Manager was eventually ported to Windows NT, where it was called NT LAN Manager (NTLM). The ported dialect was identified as "NT LM 0.12".

SMB1

Also known as SMBv1, CIFS, or "NT LM 0.12"; SMB1 is the designation given to the "NT LM 0.12" dialect of the original SMB protocol as implemented in all versions of Windows since Windows NT 3.51. The SMB1 name may be thought of as excluding older OS/2 LAN Manger and DOS versions of SMB, except that the Windows NT LAN Manager implementation is (mostly) backward compatible with those older versions. (See [MS-CIFS]; changes to SMB1 between Windows NT4 and all subsequent Windows versions are documented in [MS-SMB].)

SMB2

A.K.A. SMBv2; SMB2 is not a dialect of SMB1, it is a different protocol. It does, however, share many characteristics with SMB1. SMB2 was introduced in Windows Vista. This original release was not particularly ambitious, and its existence was hardly noticed at the time. SMBv2.1 was released with Windows 7. SMB2.2 was scheduled for release with Windows 8, but see the description of SMB3. (See [MS-SMB2].)

SMB3

A.K.A. SMBv3 or SMB2.2; SMB3 is, in fact, a set of dialects of SMB2. SMB3 was originally intended to be released as SMB version 2.2 but it contained a number of new features and so was re-dubbed SMB3 (another "marketing upgrade"). SMB3 supports I/O over RDMA as well as scale-out and failover clustering. SMB3 is documented in [MS-SMB2].

SMB2+

The SMB2 and SMB3 dialects; SMB2 and SMB3 are the same protocol with two different names. That’s confusing, so the community has started to use "SMB2+" when referring to the protocol, and all of its collective dialects. Again, see [MS-SMB2].

References

All of the references listed below are available online.

[IMPCIFS]

Hertel, Christopher R., "Implementing CIFS - The Common Internet File System", Prentice Hall, August 2003, ISBN:013047116X
http://www.ubiqx.org/cifs/

[MS-CIFS]

Microsoft Corporation, "Common Internet File System (CIFS) Protocol Specification"
http://msdn.microsoft.com/en-us/library/ee442092.aspx

[MS-DFSC]

Microsoft Corporation, "Distributed File System (DFS): Referral Protocol Specification"
http://msdn.microsoft.com/en-us/library/cc226982.aspx

[MS-SMB]

Microsoft Corporation, "Server Message Block (SMB) Protocol Specification"
http://msdn.microsoft.com/en-us/library/cc246231.aspx

[MS-SMB2]

Microsoft Corporation, "Server Message Block (SMB) Protocol Versions 2 and 3"
http://msdn.microsoft.com/en-us/library/cc246482.aspx

[NBGUIDE]

Winston, Gavin, "NetBIOS Specification", 1998-2012 (Archived)
https://web.archive.org/web/20170724042731/http://www.netbiosguide.com:80/

[RFC1001]

Network Working Group, "Protocol Standard for a NetBIOS Service on a TCP/UDP Transport: Concepts and Methods", STD 19, RFC 1001, March 1987
http://www.ietf.org/rfc/rfc1001.txt

[RFC1002]

Network Working Group, "Protocol Standard for a NetBIOS Service on a TCP/UDP Transport: Detailed Specifications", STD 19, RFC 1002, March 1987
http://www.ietf.org/rfc/rfc1002.txt

[SNIASMB3]

(SNIA) SMB3 Reference Page
https://www.snia.org/smb3

Timestamp

$Id: 0.README; 2020-12-15 16:19:47 -0600; crh$