libsmbclient: Browsing and a URI spec, updated.

[Richard Sharpe]

Hi,

   Shall we be trotting home again,
   but answer came there none.

Caldera has commissioned the development of a Samba client library that
will allow Linux and UNIX programs to be written to access resources on SMB
servers.  The clear goal is to allow the development of applications like
the Windows explorer that allow users to browse resources on Linux/UNIX
systems as well as SMB servers of all types.

There has been much discussion about the issues of browsing and directory
listing in the libsmbclient library, and things are starting to solidify
now.  This document sets out the resolution of the discussion, and
represents what will be developed in libsmbclient.

Firstly, however, some clarification on browsing under Windows.

Browsing involves a complex series of activities and protocols (More
details can be found in Special Edition, Using Samba and Ethereal dissects
many of the SMB calls used to implement browsing). 

On the server side, the NBNS and NBDS are used to register browsing related
names, distribute server and workgroup announcements, and manage the
election of master browsers and backup browsers, etc.

On the client side, however, a broadcast request is sent to the local
master browser NetBIOS name via an IP broadcast to retrieve the backup
browser list, but  after that, Lan Manager requests, like NetServerEnum and
NetShareEnum requests are made after connecting to the IPC$ share on the
browse server.

Indeed, even when you want to see all the domains/workgroups on a network,
a client connects to a backup browser and sends a NetServerEnum2 request on
the IPC$ share with a server type of 0x00000000, which causes Samba, and I
assume NT servers, to list the workgroups/domains it knows about (their
NetBIOS names only).

A clear desire with libsmbclient is to be able support browsing as well as
access to resources on servers.  The question is, whether browsing of
workgroups and servers can be unified with browsing of shares and
directories on servers.  If this can be achieved, a single interface can be
provided to users of the libsmbclient library.

By noting that browsing the workgroups on a network is implemented in
exactly the same way as browsing the servers in a workgroup, and that
workgroup and server names are disjoint, we can unify the browsing of
workgroups and servers on a network.

A very clear approach is:

   smb://
      This is the top of the tree. It means list all workgroups.

   smb://server|workgroup/
      Since server names and workgroup names are mutually exclusive, 
      list all shares on the server or all servers in the workgroup. 
      If the name <workgroup><1D>has been registered, then list all
      servers in the workgroup, otherwise, if <server><20> has been 
      registered, list all shares on the server.  There are some 
      obscure cases where it may be possible for the same name to be
      registered as a server name (eg BADSERVER<20>) and as a local
      master browser name (eg, BADSERVER<1D>), but this would only
      occur in a badly configured network (more discussion here).

      It should be noted here that workgroup also means ntdomain.

   smb://server/share
      List all directories in share on the server.

   smb://server/share/directory
      List all the objects in directory in share on the server.

This has the advantage that it conforms to people'e expectations of how
UNCs behave and how URLs behave, and we get to unify workgroup and server
browsing with directory listings.

As an aside, we should conform to RFC2396 and its URI syntax. This leads to
a very natural addition of authentication information, as RFC2396 provides
for 'userinfo', and provides a natural mechanism for specifying a username
and password, although it cautions against passing such information over
the wire [see below for comments on security].

A more complete form of the syntax, then might be:

  smb://[[userinfo@]server[:port]][/share[/path[/file]]]

where <userinfo> could be:

  [user[:password]]

A remaining question, though, is how can the domain (NT domain, that is) of
authentication be indicated in the above <userinfo>. RFC2396 seems to only
allow us a few remaining characters (';', ':', '&', '=', '+', '$', ',') or
we must escape the character we use to mark the presence of a domain in
which the authentication information is relevant.

The consensus from the list is that the best syntax for <userinfo> is

   [[domain;]user[:password]]

While libsmbclient has a callback to allow authentication information to be
retrieved from the caller, any <userinfo> passed in via the URI may
override that provided via the callback.

The intention is that the smbc_opendir routine would be passed a URI
formatted as above, and it would perform the appropriate operations to
retrieve a browse-list or directory listing.  Subsequent calls to
smbc_readdir would return the next object in the list.  Clearly, with each
dirent returned, there will need to be an indication of the type of object
returned as well.

A NOTE ON NETBIOS NAMES

NetBIOS names are becoming increasingly obsolete. They are only required by
older Microsoft OSes. Samba does not care about NetBIOS names (but does use
them for virtual servers), and NT 4.0 (I believe) and certaily Win2000
allows the use of *SMBSERVER as the called name.

Thus, <server> should be allowed to be a DNS name, with CALLED names being
set to *SMBSERVER, or the first component of the DNS name, or perhaps with
each being tried in turn.

However, browsing of workgroups and servers is all based around NetBIOS
names, so until something like Active Directory is implemented, NetBIOS
names will have to be used.

COMMENTS ON SECURITY

There would appear to be less of a security issue, in that these URIs will
not be passed over the wire; they are for specification to the library,
which will pull them apart and use the appropriate pieces where needed. If
the server supports 'encrypted' passwords, then that will be used. 

However, the embedding of authentication information in URIs may lead to
harvesting of this information from memory and command lines, so care must
be taken here.

ACKNOWLEDGMENTS

A number of people have made suggestions and criticisms that have been
incorporated into this document.  I would like to thank Chris Hertel,
Michael Sweet, Michael Allen, Steve Langasek, Simo Sorce and Kevin Colby.
Please accept my apologies if I have missed your contribution.


Regards
-------
Richard Sharpe, sharpe at ns.aus.com
Samba (Team member, www.samba.org), Ethereal (Team member, www.zing.org)
Contributing author, SAMS Teach Yourself Samba in 24 Hours
Author, Special Edition, Using Samba